Documents API

Overview

The Documents API manages document images attached to a verification. Each verification can have one document per document type (e.g., one photo ID, one proof of address). Documents are uploaded as base64-encoded images, stored in S3, and returned via temporary signed URLs.

Try it live

Upload and manage documents in the Playground → — add your API token to get started.

Document Types

Context Type	Label	Description
`PHOTO_ID`	Photo ID	Government-issued photo identification (e.g., Passport, Driver License, ID Card)
`PROOF_OF_ADDRESS`	Proof of Address	Utility bill, bank statement, or other address verification document
`SELFIE`	Selfie	Live selfie for face-match verification

Document Status Lifecycle

Status	API Value	Label	Description
Uploaded	`1`	Uploaded	Image uploaded to S3, awaiting processing
In progress	`2`	In progress	Document is being processed
Approved	`3`	Approved	All validation rules passed
Rejected	`4`	Rejected	One or more validation rules failed
Double check	`5`	Double check	Needs manual review
Canceled	`6`	Canceled	Document was canceled
Extracted	`7`	Extracted	data has been extracted from the document

Create Document

POST /api/v1/{flow}/documents

Description

Upload a document image for an existing verification. Accepts base64-encoded images, stores them and begins the verification pipeline.

Each verification can have at most one document per document type. The back_side_data field is excluded entirely for single-sided document types — omit it.

Path Parameters

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

Request Body

Parameter	Type	Required	Description
`verification`	`string`	Yes	The verification ID to attach the document to
`document`	`object`	Yes	Document details wrapper
`document.context_type`	`string`	Yes	Document context type. One of: `PHOTO_ID`, `PROOF_OF_ADDRESS`, `SELFIE`
`document.type`	`integer`	Yes	Document type ID from the flow's configured types
`document.country`	`string`	Yes	ISO3 country code of the issuing country
`document.front_side_data`	`string`	Yes	Base64-encoded image data for the front of the document
`document.back_side_data`	`string`	Conditional	Base64-encoded image data for the back. Excluded for single-sided document types in the selected country.

Example Request

http

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

{
  "verification": "ver_xxxxx",
  "document": {
    "context_type": "PHOTO_ID",
    "type": 5,
    "country": "USA",
    "front_side_data": "/9j/4AAQ...base64_encoded_image_data..."
  }
}

Response (`201 Created`)

json

{
  "data": {
    "id": "doc_xxxxx",
    "url_front": "https://...",
    "url_back": "https://...",
    "status_label": "Uploaded",
    "verification_id": "ver_xxxxx",
    "document_type": {
      "id": 5,
      "name": "Uniformed Service ID",
      "type_label": "Photo ID"
    },
    "country": {
      "name": "United States of America",
      "iso2": "US",
      "iso3": "USA"
    },
    "created_at": "2026-06-11T02:42:50.000000Z",
    "updated_at": "2026-06-11T02:42:50.000000Z",
    "extracted_data": []
  }
}

Possible Errors

Status	Meaning
`400`	Flow mismatch, verification canceled, verification not in Started status, document type not allowed for flow, duplicate document type, or missing/invalid image data
`401`	Missing or invalid authentication
`404`	Verification not found
`422`	Validation error

Business Rules

The verification must belong to the specified flow
The verification must be in Started status (not yet submitted)
The verification must not be Canceled
The document type must be configured for this flow
Each verification can have at most one document per document type (e.g., one photo ID, one proof of address)
The back_side_data is excluded (not just optional) for single-sided document types based on per-country configuration
Image data must be valid base64
On success, a DocumentUploaded event is fired to begin processing

Get Document

GET /api/v1/{flow}/documents/{document}

Description

Retrieve a single verification document with its extracted data, decisions, and document type/country information.

Path Parameters

Parameter	Type	Description
`flow`	`string`	The flow path name
`document`	`string`	The document ID (e.g. `doc_xxxxx`)

Example Request

http

GET /api/v1/usps1583/documents/doc_xxxxx
Authorization: Bearer {token}
Accept: application/json

Example Response

json

{
  "data": {
    "id": "doc_xxxxx",
    "url_front": "https://...",
    "url_back": "https://...",
    "status_label": "Rejected",
    "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": "Rejected",
        "validation_workflow": "Automatic",
        "created_at": "2026-06-11T17:15:25.000000Z",
        "updated_at": "2026-06-11T17:15:25.000000Z"
      }
    ]
  }
}

Possible Errors

Status	Meaning
`400`	Document's verification does not belong to the specified flow
`401`	Missing or invalid authentication
`404`	Document not found

Business Rules

Document images are served via temporary signed URLs (30-minute expiry)
Extracted data is only available after the document has been processed
Decisions are only available after a decision has been made

Update Document

PATCH /api/v1/{flow}/documents/{document}

Description

Update an existing verification document's metadata or image files. Only provided fields are updated; omitted fields retain their current values. Accepts base64-encoded images for replacement.

Path Parameters

Parameter	Type	Description
`flow`	`string`	The flow path name
`document`	`string`	The document ID

Request Body

Parameter	Type	Required	Description
`verification`	`string`	Yes	The verification ID this document belongs to
`status`	`integer`	No	New document status (1–7). Only valid when current status is Uploaded
`document`	`object`	No	Document details to update
`document.context_type`	`string`	No	One of: `PHOTO_ID`, `PROOF_OF_ADDRESS`, `SELFIE`
`document.type`	`integer`	No	Document type ID from the flow's configured types
`document.country`	`string`	No	ISO3 country code
`document.front_side_data`	`string`	No	Base64-encoded image data to replace the front image
`document.back_side_data`	`string`	No	Base64-encoded image data to replace the back image

Example Request

http

PATCH /api/v1/usps1583/documents/doc_xxxxx
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "verification": "ver_xxxxx",
  "document": {
    "context_type": "PHOTO_ID",
    "type": 5,
    "country": "USA",
    "front_side_data": "/9j/4AAQ...new_base64_image..."
  }
}

Example Response

json

{
  "data": {
    "id": "doc_xxxxx",
    "url_front": "https://...",
    "url_back": "https://...",
    "status_label": "Uploaded",
    "verification_id": "ver_xxxxx",
    "created_at": "2026-06-11T02:42:50.000000Z",
    "updated_at": "2026-06-11T03:41:52.000000Z",
    "extracted_data": []
  }
}

Possible Errors

Status	Meaning
`400`	Flow mismatch, document already verified (not in Uploaded status), parent verification not in Started status, or document type not allowed
`401`	Missing or invalid authentication
`404`	Document not found
`422`	Validation error

Business Rules

The document must still have status Uploaded — documents that have entered the extraction pipeline cannot be modified
The parent verification must still have status Started — submitted verifications cannot have their documents replaced
Image data replaces the existing image in S3
On success, a DocumentUploaded event is fired

Delete Document

DELETE /api/v1/{flow}/documents/{document}

Description

Delete a verification document. Once deleted, a new document of the same type can be uploaded.

Path Parameters

Parameter	Type	Description
`flow`	`string`	The flow path name
`document`	`string`	The document ID

Example Request

http

DELETE /api/v1/usps1583/documents/doc_xxxxx
Authorization: Bearer {token}
Accept: application/json

Response (`204 No Content`)

No response body.

Possible Errors

Status	Meaning
`400`	Document's verification does not belong to the specified flow
`401`	Missing or invalid authentication
`404`	Document not found

Business Rules

After deletion, a new document of the same type can be uploaded
Useful when a user provides the wrong document or a low-quality image

Download Document PDF

GET /api/v1/{flow}/documents/{document}/pdf

Description

Generate a PDF containing the document images. Returns a JSON object with the PDF content as a base64-encoded string.

The verification must be in Approved status.

Path Parameters

Parameter	Type	Description
`flow`	`string`	The flow path name
`document`	`string`	The document ID

Example Request

http

GET /api/v1/usps1583/documents/doc_xxxxx/pdf
Authorization: Bearer {token}
Accept: application/json

Example Response

json

{
  "data": "JVBERi0xLjQKMSAwIG9iago8PCA..."
}

Possible Errors

Status	Meaning
`400`	Document's verification does not belong to the specified flow
`400`	The verification is not in Approved status
`401`	Missing or invalid authentication
`404`	Document not found

Business Rules

The parent verification must be in Approved status
The response is a JSON object containing the PDF as a base64-encoded string — NOT a binary stream
Useful for record-keeping and audit purposes

Business Rules Summary

Documents are scoped to a flow via their parent verification
Documents can only be uploaded while the verification is in Started status
At most one document per document type per verification
A DocumentUploaded event is fired after successful create or update
Image URLs are temporary signed URLs with a 30-minute expiry
The PDF download endpoint requires the verification to be Approved

Notes

For decisions and extracted data updates after processing, use the dedicated Decisions and Extracted Data endpoints

Documents API ​

Overview ​

Document Types ​

Document Status Lifecycle ​

Create Document ​

Description ​

Path Parameters ​

Request Body ​

Example Request ​

Response (201 Created) ​

Possible Errors ​

Business Rules ​

Get Document ​

Description ​

Path Parameters ​

Example Request ​

Example Response ​

Possible Errors ​

Business Rules ​

Update Document ​

Description ​

Path Parameters ​

Request Body ​

Example Request ​

Example Response ​

Possible Errors ​

Business Rules ​

Delete Document ​

Description ​

Path Parameters ​

Example Request ​

Response (204 No Content) ​

Possible Errors ​

Business Rules ​

Download Document PDF ​

Description ​

Path Parameters ​

Example Request ​

Example Response ​

Possible Errors ​

Business Rules ​

Business Rules Summary ​

Notes ​

Documents API

Overview

Document Types

Document Status Lifecycle

Create Document

Description

Path Parameters

Request Body

Example Request

Response (`201 Created`)

Possible Errors

Business Rules

Get Document

Description

Path Parameters

Example Request

Example Response

Possible Errors

Business Rules

Update Document

Description

Path Parameters

Request Body

Example Request

Example Response

Possible Errors

Business Rules

Delete Document

Description

Path Parameters

Example Request

Response (`204 No Content`)

Possible Errors

Business Rules

Download Document PDF

Description

Path Parameters

Example Request

Example Response

Possible Errors

Business Rules

Business Rules Summary

Notes