POST/simulate/sanction-status

Simulate Sanction Status

Sets the verdict on one sanctions screening of the application. Does not fire a webhook — sanctions screening is informational to a broker.

When IndividualId is sent, the individual's screening is updated; otherwise the business-name screening is updated.

The status you set sticks. It is stamped with a broker-override marker (statusUpdatedBy prefixed b_), and every system path that would otherwise recompute this status — the status calculator and the re-derivation from the ComplyAdvantage match status — leaves it alone from then on. The underlying record is still refreshed; only the status is preserved.

A screening is re-run from scratch when the underlying data changes (a re-submit can trigger this), which creates a new screening record that supersedes this one. The override protects the record it was set on, not the subject forever.

Precondition: the screening must already have run. The simulator returns 400 unless the screening has been submitted to ComplyAdvantage and come back with a resolvable match status. Screening is initiated after KYC completes, so in practice KYC must also be done. Simulating a verdict on a screening that never ran would fabricate a state the real flow cannot reach.

Blocked in production. Returns 400 when simulation is disabled (broker.simulate.enabled=false or production environment).

Headers

Field	Type	Required	Possible values	Description
`session-token`	string	Required	—	SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header.

Request body

Field	Type	Required	Possible values	Description
`Id`	string	Required	—	Application ID.
`Status`	integer	Required	2 (missing) \| 3 (approved) \| 4 (rejected)	Target sanctions-screening status.
`IndividualId`	string	Optional	—	Individual/UBO ID. When present, the individual's screening is updated. Omit to update the business-name screening.
`Remark`	string	Optional	—	Optional remark stored on the screening record. Not delivered as a webhook — this endpoint fires none.

Example request

{
  "Id": "6a3a2f324c2e4b093dce834b",
  "IndividualId": "6a3a30264c2e4b093dce834c",
  "Status": 3,
  "Remark": "No sanctions match."
}

{
  "Id": "6a3a2f324c2e4b093dce834b",
  "IndividualId": "6a3a30264c2e4b093dce834c",
  "Status": 3,
  "Remark": "No sanctions match."
}

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 301 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 503	API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized).
`ResponseMessage`	string	Success \| Created \| NoContent \| BadRequest \| Unauthorized \| Forbidden \| NotFound \| Gone \| UnprocessableContent \| ServerError \| ResourceMoved \| ServiceUnAvailable \| UnProcessableEntity	Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome.
`ResponseData`	object	Please refer to below example for response body	Updated screening identifiers. `BusinessScreening` is `true` when the business-name screening was updated. `ApplicationId` is the application that was targeted.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "DocumentId": "6a3a2f324c2e4b093dce834b",
    "IndividualId": "6a3a2f324c2e4b093dce834b",
    "CommentId": "6a3a2f324c2e4b093dce834b",
    "Status": 0,
    "BusinessScreening": true,
    "ApplicationId": "6a3a2f324c2e4b093dce834b"
  }
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "DocumentId": "6a3a2f324c2e4b093dce834b",
    "IndividualId": "6a3a2f324c2e4b093dce834b",
    "CommentId": "6a3a2f324c2e4b093dce834b",
    "Status": 0,
    "BusinessScreening": true,
    "ApplicationId": "6a3a2f324c2e4b093dce834b"
  }
}

Does **not** fire a webhook. Returns 400 if simulation is disabled, the screening has not run, or the application / individual is not found.

Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.