You record a decision with a reason code through the API. Approving it, sending it back and withdrawing it are done by people, in the portal, and the API has no endpoints for them. The response to your call is the decision. Fetch the review for its new status.
Choose the decision
The decisions allowed depend on the review's kind.
| Review kind | Decisions |
|---|---|
possible_sanctions_match, possible_pep_match, screening_review | waiting_on_customer, not_a_match, confirmed_match |
manual | waiting_on_customer, no_concern, concern_confirmed |
Each decision accepts its own reason_code values, and other goes with any of them.
decision | reason_code |
|---|---|
waiting_on_customer | dob_needed, id_document_needed, more_information_needed |
not_a_match | dob_differs, nationality_differs, id_document_verified, different_entity_type, location_differs |
confirmed_match | identity_confirmed, exact_identifier_match, customer_confirmed |
no_concern | activity_explained, documents_verified |
concern_confirmed | suspicious_activity, policy_breach |
Record it
The response reads requires_approval: true. The approval is in the portal.
curl -X POST \ https://api.antonpayments.dev/v1/intelligence/reviews/irv_dbvqsbiukoh4g0rnek30/decisions \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "DPoP: $DPOP_PROOF" \ -H "Idempotency-Key: rv-0001-decision-1" \ -H "Content-Type: application/json" \ -d '{ "decision": "not_a_match", "reason_code": "dob_differs", "note": "Date of birth differs from the listed person." }'
note is optional, up to 2000 characters. It is stored in a vault and never returned: the response says only note_recorded. Send an Idempotency-Key with every change.
Who approves
Two rules can require a second person.
- Your second-approver setting. A decision it covers waits for a person to approve it in the portal.
approval_ruleissanctions_peporall, anddecision_proposedreaches you as an event.GET /v1/intelligence/reviews/settingsshows the setting, read only. api_clearance. A decision your API credential records that clears the subject (not_a_match,no_concern) always waits for a person, whatever the setting.api_clearance_requires_approvalis alwaystrue.
The approver for api_clearance must be independent of your API credentials. They cannot be the person who created the credential, or hold a role that can create, rotate or revoke credentials (Admin, Technical). In practice that is your Compliance role.
The decision's approval is null until there is an answer, then carries outcome as approved, sent_back or withdrawn. The review's pending_decision_id names the decision that is waiting.
Wait on your customer
waiting_on_customer pauses the due time while you ask your customer for something. Call POST /v1/intelligence/reviews/{id}/resume with an Idempotency-Key and no body when they answer. The due time moves out by the time spent waiting. A review that is not waiting is 409 review_not_waiting.
Add a note
POST /v1/intelligence/reviews/{id}/notes takes text, up to 2000 characters, on an open review. The text goes to a vault and is never returned. Your team reads it in the portal, and it appears in the case files your people export. A review that already has the most notes it can hold is 409 note_limit_reached.
Events
| Event | When |
|---|---|
intelligence.review.decision_proposed | A decision is waiting for a second approver. |
intelligence.review.decided | A decision took effect, including waiting on your customer. |
intelligence.review.reopened | A decision was sent back or withdrawn, or your customer responded. reason is sent_back, withdrawn or customer_responded. |
intelligence.review.closed | A review closed, with its outcome. |
The event can carry decision_id, decision, reason_code, requires_approval, approval_rule and approved, and never a name or note text.
When it goes wrong
reason_code is not accepted for that decision.note is over 2000 characters.