Anton.Docs
Dashboard (opens in a new tab)

Record and approve a decision

A clearing decision recorded with an API credential waits for a person to approve it, and that person cannot be tied to your API credentials.

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.

Before you begin

Choose the decision

The decisions allowed depend on the review's kind.

Review kindDecisions
possible_sanctions_match, possible_pep_match, screening_reviewwaiting_on_customer, not_a_match, confirmed_match
manualwaiting_on_customer, no_concern, concern_confirmed

Each decision accepts its own reason_code values, and other goes with any of them.

decisionreason_code
waiting_on_customerdob_needed, id_document_needed, more_information_needed
not_a_matchdob_differs, nationality_differs, id_document_verified, different_entity_type, location_differs
confirmed_matchidentity_confirmed, exact_identifier_match, customer_confirmed
no_concernactivity_explained, documents_verified
concern_confirmedsuspicious_activity, policy_breach

Record it

POST/v1/intelligence/reviews/{id}/decisionsRecord a decision

The response reads requires_approval: true. The approval is in the portal.

Reference
Not yet tested in sandbox
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_rule is sanctions_pep or all, and decision_proposed reaches you as an event. GET /v1/intelligence/reviews/settings shows 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_approval is always true.

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

EventWhen
intelligence.review.decision_proposedA decision is waiting for a second approver.
intelligence.review.decidedA decision took effect, including waiting on your customer.
intelligence.review.reopenedA decision was sent back or withdrawn, or your customer responded. reason is sent_back, withdrawn or customer_responded.
intelligence.review.closedA 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

409review_closed
The review is closed and takes no further changes.
409decision_pending
The review already has a decision waiting for approval. Wait for the approval before recording another.
409second_approver_unavailable
The decision needs a second approver and nobody else on your team can approve it. Give a person the Compliance role, then retry.
422invalid_decision
The decision is not allowed for this review's kind.
422invalid_reason_code
The reason_code is not accepted for that decision.
422note_too_long
note is over 2000 characters.

Next

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗