Decisions API

Overview

The Decisions API allows manually setting the status of verification documents. Creating a decision updates the document's status and may cascade to update the overall verification status (e.g., approving the final document approves the entire verification).

This is typically used by human reviewers to override or confirm automated processing results.

Try it live

Make decisions on documents in the Playground → — add your API token to get started.

Decision Status Reference

Code	Status	Description
0	Pending	No decision has been made (not used when creating)
1	Approved	Document passed validation
2	Rejected	Document failed validation
3	Double Check	Document needs manual review
4	Canceled	Document was removed from consideration

Create Decision

POST /api/v1/{flow}/decisions

Description

Manually set the status of a verification document. This creates a DocumentDecision record and updates the document's status to match. If all documents in the verification have a final decision, the verification status cascades accordingly.

Path Parameters

Parameter	Type	Description
flow	string	The flow path name (e.g. usps1583)

Request Body

Parameter	Type	Required	Description
status	integer	Yes	Decision status code. One of: 0 (Pending), 1 (Approved), 2 (Rejected), 3 (Double Check), 4 (Canceled)
document	string	Yes	The document ID to attach the decision to (e.g. doc_xxxxx)
validation_workflow	string	No	Custom workflow description (e.g. "Manual by some@email.com")

Example Request

POST /api/v1/usps1583/decisions
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "status": 1,
  "document": "doc_xxxxx",
  "validation_workflow": "Manual by some@email.com"
}

Response (201 Created)

The response is the updated VerificationDocument with the new decision reflected in its decisions array and status_label.

{
  "data": {
    "id": "doc_xxxxx",
    "url_front": "https://...",
    "url_back": "https://...",
    "status_label": "Approved",
    "verification_id": "ver_xxxxx",
    "created_at": "2026-06-11T17:14:46.000000Z",
    "updated_at": "2026-06-11T17:16:06.000000Z",
    "extracted_data": {
      "person": {
        "surname": "Simpson",
        "full_name": "Simpson Homer",
        "given_names": "Homer",
        "date_of_birth": "1988-07-23"
      },
      "address": {
        "zip": "92026",
        "city": "Springfield",
        "full": "742 Evergreen Terrace, Springfield, Tennessee 92026",
        "state": "Tennessee",
        "street": "742 Evergreen Terrace",
        "country": "USA"
      },
      "document": {
        "type": "Driver License",
        "number": "",
        "has_selfie": "1",
        "identified": "United States of America - Driver License",
        "country_code": "USA",
        "country_name": "United States of America",
        "issuing_entity": "Government",
        "expiration_date": "2028-07-23",
        "selfie_comparison": "99"
      }
    },
    "decisions": [
      {
        "id": "dec_xxxxx",
        "status_label": "Approved",
        "validation_workflow": "Manual by some@email.com",
        "created_at": "2026-06-11T17:16:06.000000Z",
        "updated_at": "2026-06-11T17:16:06.000000Z"
      }
    ]
  }
}

Possible Errors

Status	Meaning
400	Document's verification does not belong to the specified flow, or the document is canceled
401	Missing or invalid authentication
404	Document not found
422	Validation error (missing status or document)

Status Cascade Logic

When a decision is created, the system evaluates the document's new status and cascades to the verification level:

Condition	Verification Status
All documents approved	Approved
All documents rejected	Rejected
Any document in double check	Double Check
Duplicated document rule triggered	Rejected
Address banned rule triggered	Rejected

The cascade only triggers when all documents in the verification have been processed. If some documents remain without a final decision, the verification stays in its current state.

Once the verification status changes away from Submitted, a VerificationFinished event fires, which triggers configured webhooks. If the canceled decision status is used, no cascade occurs.

Business Rules

• The document's verification must belong to the specified flow
• The document must not already be canceled
• Creating a decision updates the document's status to the corresponding document status

Notes

• This is the only Decisions endpoint — there is no list, get, update, or delete for decisions
• Decisions are append-only: each new decision is added to the decisions array on the document