# Manual Risk Feedback

{% hint style="danger" %}
Castro note: Hidden because I think this is an internal use only method. But keeping as a placeholder until confirmed.
{% endhint %}

Manual Risk Feedback lets your risk and compliance teams send a final decision or additional classification for an onboarding application into the system. This is used when a human reviewer has evaluated the merchant and wants to mark the application as approved, declined, or fraud based on manual review.

Use this endpoint when you want to:

* Record a manual decision from risk or compliance for a specific application
* Mark an application as fraud after investigation
* Confirm an approval decision that is based on human review rather than only automated checks
* Decline an application with a clear reason and reviewer record

The operation is designed to carry a small, structured payload with the decision, the reviewer, and the reason.

### Endpoint

```http
POST /merchant-onboarding/{applicationId}/feedback
```

Path parameter

* `applicationId`\
  The onboarding application identifier returned when you created the application with the submit endpoints.

Authentication

* Requires a valid OAuth access token for the bead-integrator client.
* Use the standard Authorization header.

Headers

```http
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json
```

### Request body

The request body uses the `SubmitFeedbackRequest` model.

Fields

* `stakeholderEmail`
  * Required
  * The email address of the merchant stakeholder the feedback applies to.
  * Typically this is the primary signer or main point of contact associated with the application.
* `status`
  * Required
  * The feedback status you are applying to the application.
  * Allowed values:
    * `approved`
    * `declined`
    * `fraud`
* `reason`
  * Required
  * A short, human-readable reason for this decision.
  * Example: `"Insufficient documentation for ownership structure"` or `"Confirmed synthetic identity fraud"`.
* `description`
  * Optional
  * Longer free-text description providing details for this decision.
  * Can include investigation notes, references to internal case IDs, and any additional context that may be useful for audit or downstream teams.
* `reviewedBy`
  * Required
  * Name or identifier of the person making the decision.
  * Example: `"Jane Doe"` or `"RiskUser123"`.

Example request body

```json
{
  "stakeholderEmail": "owner@example-merchant.com",
  "status": "declined",
  "reason": "Unable to verify business identity",
  "description": "Multiple attempts to collect valid documents failed. Business registration records could not be matched to application details.",
  "reviewedBy": "Jane Doe"
}
```

### Example request

```http
POST /merchant-onboarding/app-abc123/feedback
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

{
  "stakeholderEmail": "owner@example-merchant.com",
  "status": "fraud",
  "reason": "Confirmed stolen identity",
  "description": "Document review and external data sources confirmed identity theft. Do not reapply without manual override.",
  "reviewedBy": "Risk Analyst 1"
}
```

The endpoint responds with a success status (for example 200, 201, or 202) when the feedback has been accepted and applied. The exact success code may vary by environment.

### When to use Manual Risk Feedback

Manual Risk Feedback is typically used by internal teams, not directly by partner systems or merchants. Common scenarios include:

* Manual approval\
  Automated checks flagged the application for review. A risk or compliance analyst investigates and decides the merchant is acceptable. They send feedback with `status = "approved"` and a clear reason and description.
* Manual decline\
  A human reviewer identifies issues that require declining the application, such as mismatched documents, unverifiable ownership, or other risk concerns. They send feedback with `status = "declined"` and a clear explanation.
* Fraud classification\
  Investigation confirms that the application involves fraud, such as stolen identities, fabricated records, or synthetic identities. The reviewer sends feedback with `status = "fraud"` and details in `reason` and `description`. This may drive additional internal handling, such as blocking related accounts.

You can build internal tools that call this endpoint behind the scenes, so risk and compliance users interact with a UI while your backend issues the API call.

### Interaction with onboarding status and webhooks

Manual Risk Feedback works alongside the core onboarding status and webhook flows.

Typical behavior:

* When feedback is applied, the underlying risk engine and onboarding system update their view of the application.
* Status may change from a pending or review state to an outcome driven by the feedback (for example, approved, declined, or fraud).
* Webhooks for application events can notify your systems that a decision has been recorded, allowing you to update your own records or trigger downstream workflows.

Recommended approach:

* Use Get Status to see the current application state before applying feedback.
* After sending feedback, rely on webhooks or another status call to see the resulting state.
* Use the combination of status and feedback history for audit and analytics.

### Error handling

You should handle potential error responses from this endpoint in your integration.

Typical patterns:

* 400 Bad Request\
  The request body is missing required fields, has invalid values (for example, status not in the allowed list), or otherwise fails validation. Your tooling should validate required fields before sending.
* 401 Unauthorized\
  The access token is missing, expired, or invalid. Ensure you obtain and send a valid token in the Authorization header.
* 403 Forbidden\
  The caller is authenticated but not authorized to submit feedback for this application. This typically indicates a permissions or configuration issue.
* 404 Not Found\
  The `applicationId` does not match any existing onboarding application in the environment.
* 409 Conflict\
  The application is in a state where the requested feedback cannot be applied, or there is a conflicting update. Your system should surface these errors clearly so risk and compliance teams understand when feedback was not accepted.

Log error responses with the application id, HTTP status, and the error body (with sensitive data masked as appropriate) to support troubleshooting.

### Best practices

* Use clear, consistent reasons\
  Encourage reviewers to use standardized phrases in `reason` so that you can later group and analyze decisions. Free-form detail can go into `description`.
* Track reviewer identity\
  Always populate `reviewedBy` with a value that lets you identify who made the decision. This is important for audit and compliance.
* Keep stakeholderEmail aligned\
  Ensure `stakeholderEmail` matches the primary contact or signer associated with the application so you can correlate feedback with the correct person.
* Combine with internal case management\
  If you use internal case or ticket systems, include case identifiers in the `description` field so that you can move between systems easily.
* Avoid exposing this directly to external partners\
  Manual Risk Feedback is primarily an internal control. If partners need to see outcomes, surface results via your own APIs or UI based on onboarding status, not by exposing this endpoint directly.

By using Manual Risk Feedback in combination with onboarding status, webhooks, and your internal risk processes, you can maintain a clear, auditable record of human decisions in the merchant onboarding lifecycle.