Preview

Suspend participant from review

POST
/providers/{providerID}/participant-reviews/{reviewID}/suspensions

Suspend the participant’s relationship with your provider and resolve the pending review in one atomic change. The suspension applies to your provider only; the participant’s global status does not change. From the next attempt, the participant cannot send payouts or create requests through your provider, including from a session that is already open. Money that a payer sends for one of their existing requests is not paid out to them until you reactivate them or the request expires. Signing in, payments that already started, reversals, and refunds are not affected. Closing a review never reactivates a relationship.

Fetch the review detail first. Send its versionID as expectedVersionID and its relationship.versionID as expectedRelationshipVersionID. Moov Money compares both inside the write. Returns a 409 with error code participant-review-version-conflict when either differs, and changes neither the review nor the relationship. The problem detail does not name the current versions. Fetch the review detail again before you retry.

When the relationship is already suspended, it keeps its original reason code and note. The review records your decision, and the relationship version still advances so an older reactivation cannot clear it.

Each suspension from a review writes a suspension relationship action with this review’s participantReviewID, also when the relationship was already suspended. The action carries this request’s reasonCode, its reason as the note, and the new relationship versionID.

Returns 201 with the resolved review and the committed relationship state. Returns a 409 with error code state-conflict when the review is already resolved, whatever versions you send. A review from another provider and a missing review both return 404. Returns 422 when the body fails validation.

Send an X-Idempotency-Key header so a retried request is processed once. Replaying the same key with the same body returns the original 201 response. Replaying it with a different body returns a 409 with error code idempotency-key-reused. Returns a 409 with error code idempotency-request-in-progress when a request with this key is still running. Returns 400 when the header is missing or malformed.

Auth: API key or bearer token. Scoped to the calling provider. Requires both participant-review write access and relationship write access; missing either returns 403.

Request
cURL
curl -X POST https://api.moov.money/providers/{providerID}/participant-reviews/{reviewID}/suspensions \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedRelationshipVersionID": "relationship-v4",
  "expectedVersionID": "review-v2",
  "reason": "Unresolved identity concern",
  "reasonCode": "suspected-fraud"
}'
Responses
201 400 401 403 404 409 422
The resource was successfully created.
Suspend and resolve
{
  "review": {
    "assessmentIDs": [
      "ras_01HF5J9ZKQT4RXP8M2VYBN3D"
    ],
    "assigneeUserID": "4d7c1b9e-2f3a-4e5b-8c6d-7e8f9a0b1c2d",
    "createdOn": "2026-10-06T15:00:00Z",
    "externalID": "customer-abc-123",
    "notes": [
      {
        "actor": {
          "callingAccountID": "acc_01HF5J9ZKQT4RXP8M2VYBN3D",
          "kind": "user",
          "userID": "4d7c1b9e-2f3a-4e5b-8c6d-7e8f9a0b1c2d"
        },
        "createdOn": "2026-10-06T15:30:00Z",
        "resolvedByDisplay": {
          "displayName": "Jordan Lee",
          "email": "[email protected]"
        },
        "text": "Contacted participant"
      }
    ],
    "participantID": "3v2whagmwvbujhwbt7v3nl6ffq_user",
    "reason": "Investigate sign-in activity",
    "relationship": {
      "suspended": true,
      "versionID": "relationship-v5"
    },
    "resolution": {
      "action": "suspend",
      "actor": {
        "callingAccountID": "acc_01HF5J9ZKQT4RXP8M2VYBN3D",
        "kind": "user",
        "userID": "4d7c1b9e-2f3a-4e5b-8c6d-7e8f9a0b1c2d"
      },
      "reason": "Unresolved identity concern",
      "reasonCode": "suspected-fraud",
      "resolvedByDisplay": {
        "displayName": "Jordan Lee",
        "email": "[email protected]"
      },
      "resolvedOn": "2026-10-06T16:00:00Z"
    },
    "reviewID": "8b1f6c2e-4d3a-5e7f-9a0b-1c2d3e4f5a6b",
    "status": "resolved",
    "versionID": "review-v3"
  }
}
Malformed request: the body or headers failed validation.
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.
Authentication missing, invalid, or insufficient.
Authentication present but the action is forbidden for this principal/claim.
The requested resource was not found.
The request conflicts with the current state of the target resource.
Stale relationship version
map[detail:The review or relationship changed since you read it. Fetch the review again. status:409 title:Conflict type:https://api.moov.money/errors#participant-review-version-conflict]
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.
The request was well-formed but couldn’t be processed (e.g. card declined).
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.

Headers

X-Moov-Version

string
Set this header to the API version being targeted (e.g. v2026.10.00). When omitted, the server applies its default version.

X-Idempotency-Key

string required
Client-supplied key that identifies this create request, 1 to 255 characters. Send the header once. Retries with the same key are processed once for 24 hours after the request completes.

Path parameters

providerID

string required
Your provider account ID.

reviewID

string required
Identifier of the participant review.

Request

application/json
Suspend the participant’s relationship with your provider and resolve the review. Read both version tokens from one fresh read of the review detail.

reason

string [1 to 512] characters required
Why you are suspending, 1 to 512 characters. Becomes the suspension note, so it also supplies the note that other requires.

reasonCode

string<enum> required
Suspension classification.
Possible values: suspected-fraud, account-compromise, customer-request, compliance-review, legal-hold, policy-violation, other

expectedVersionID

string required
The review versionID from your latest read of the review detail.

expectedRelationshipVersionID

string required
The relationship.versionID from the same read of the review detail.

Response

Response envelope for a participant review; the review is nested under review.

review

object required
The full participant review.
Show child attributes

review

reviewID

string required
Unique system-assigned participant-review identifier.

participantID

string required
Participant under review.

externalID

string required
Your identifier for the participant under review.

status

string<enum> required
Current review status.
Possible values: pending, resolved

versionID

string required
Opaque state-version token for this review. Send it back as expectedVersionID on your next note, assignment, or resolution.

reason

string
Why the review was opened. Omitted when a risk assessment opened the review without a written reason.

assessmentIDs

array<string> required
Risk assessments linked to this review. An open request that joins this pending review adds its assessmentID here. Empty when none are linked.

assigneeUserID

string
Moov user ID of the team member assigned to this review. Omitted while unassigned.

createdOn

string<date-time> required
When the review was opened.

resolution

object
The decision. Present when status is resolved.
Show child attributes

review.resolution

action

string<enum> required
The decision.
Possible values: no_action, suspend

reason

string required
Your explanation of the decision.

reasonCode

string<enum>
Suspension classification you chose. Present when action is suspend. When the relationship was already suspended, the relationship keeps its original classification and this field records your decision only.
Possible values: suspected-fraud, account-compromise, customer-request, compliance-review, legal-hold, policy-violation, other

resolvedOn

string<date-time> required
When the review was resolved.

actor

object required
Who resolved the review.
Show child attributes

review.resolution.actor

kind

string<enum> required
Kind of actor.
Possible values: user, application, system

userID

string
Moov user ID of the person who acted. Present when kind is user. Omitted when kind is application or system.

applicationKeyID

string
ID of the application key that acted. Present when kind is application. Omitted when kind is user or system.

callingAccountID

string
Moov account ID that the actor acted from. Present when kind is user or application. Omitted when kind is system.

resolvedByDisplay

object
Display recorded for actor when the review was resolved. A person shows the name and email recorded then. An application actor and a system actor show a fixed label. Omitted when no display was recorded; actor still identifies who resolved the review.
Show child attributes

review.resolution.resolvedByDisplay

displayName

string required
Name shown for the actor. A user actor uses the name recorded at resolution. An application actor uses the fixed label API application. A system actor uses the fixed label Moov Money.

email

string
Email recorded for a person at resolution. Omitted for an application actor, a system actor, or when no email was recorded.

relationship

object required
Current state of the participant’s relationship with your provider. Send relationship.versionID as expectedRelationshipVersionID when you suspend from this review.
Show child attributes

review.relationship

suspended

boolean required
Whether you suspended this participant. A suspended participant cannot send payouts or create requests through your provider. Money that a payer sends for one of their existing requests is not paid out to them until you reactivate them or the request expires. Signing in, payments that already started, reversals, and refunds are not affected.

versionID

string required
Opaque version of the relationship state. Send it as expectedVersionID on your next suspension or reactivation. It is not a relationship ID.

notes

array<object> required
Notes on the review, oldest first. Empty when none exist.
Show child attributes

review.notes[]

text

string required
Note text.

createdOn

string<date-time> required
When the note was added.

actor

object required
Who added the note.
Show child attributes

review.notes[].actor

kind

string<enum> required
Kind of actor.
Possible values: user, application, system

userID

string
Moov user ID of the person who acted. Present when kind is user. Omitted when kind is application or system.

applicationKeyID

string
ID of the application key that acted. Present when kind is application. Omitted when kind is user or system.

callingAccountID

string
Moov account ID that the actor acted from. Present when kind is user or application. Omitted when kind is system.

resolvedByDisplay

object
Display recorded for actor when the note was added. A person shows the name and email recorded then. An application actor and a system actor show a fixed label. Omitted when no display was recorded; actor still identifies who added the note.
Show child attributes

review.notes[].resolvedByDisplay

displayName

string required
Name shown for the actor. A user actor uses the name recorded at resolution. An application actor uses the fixed label API application. A system actor uses the fixed label Moov Money.

email

string
Email recorded for a person at resolution. Omitted for an application actor, a system actor, or when no email was recorded.