Create and manage verification cases — documents, conversations, decisions, and reports

Cases

A case is a verification session tied to a specific agent goal. Documents are uploaded into a case; the agent classifies, extracts, and validates each one. Cases progress through statuses: collecting → completed / review / denied / failed. A case left untouched past the session TTL is swept to expired, which is terminal too.

Case Object

session_idstring

UUID of the case.

tenant_idstring

Tenant that owns this case.

goalstring

Agent goal this case is running against (e.g. "kyc_verification").

client_reference_idstring

Your own unique reference for this case, if you supplied one at creation. Echoed back so you can correlate the case with your records. null when not provided.

statusstring

Current status: collecting, completed, review, denied, failed, expired.

completed, review, denied, failed and expired are terminal — poll until you see one of those, or use the completed flag on GET /v1/cases/{id}/status, which is true for exactly that set. expired means the case was swept for inactivity before it was completed; it cannot be completed afterwards, but its report is still generated on demand.

extractionsobject

Merged extraction results keyed by document type.

resultobject

Final result including decision, cross-match outcome, and validation summary.

execution_idstring

UUID of the associated execution record, if present.

documentsobject[]

Array of document records uploaded to this case.

progressobject

Goal progress showing which document types have been collected and which are still needed.

created_atstring
updated_atstring

Document Record Object

doc_idstring
UUID of the document.
doc_indexnumber
Position of this document in the case.
filenamestring
Original filename.
object_keystring
Object storage key.
file_urlstring
Relative URL to download the file: /v1/cases/{session_id}/documents/{doc_id}/file
mime_typestring
File MIME type.
size_bytesnumber
File size in bytes.
labelstring
Optional label provided at upload time.
document_typestring
Classified document type ID.
confidencestring
Classification confidence score.
extractedobject
Extracted field values.
coordinatesobject
Field bounding-box coordinates if available.
statusstring
pending, processing, done, failed
errorstring
Error message if status is failed.
created_atstring

Endpoints

Create Case

POST /v1/cases

Requires scope: write. Creates a new case and routes it to the named agent. For intelligence level 2+ agents, the agent's configured greeting is stored as the first assistant message.

Request body:

goalstringrequired

Agent goal to run this case against. The agent must be deployed.

tenant_idstring

Tenant to associate this case with.

client_reference_idstring

Optional. Your own unique identifier for this case (max 255 characters), unique per tenant. Supply it so you hold a handle to the case before the response returns — if the create call errors after the case was created, you can still recover it via List Cases (?client_reference_id=…).

It is also an idempotency key: creating a case again with the same client_reference_id returns the existing case (HTTP 200) instead of creating a duplicate, so a blind retry after an error is safe. Echoed back on the case object.

Example request:

{
  "goal": "kyc_verification",
  "tenant_id": "acme-corp",
  "client_reference_id": "order-8f21c"
}

Response (201): Case object with empty documents array and initial progress.

Response (200): returned instead of 201 when client_reference_id matches an existing case for the tenant — the existing case is returned unchanged (idempotent replay; no new case is created).

List Cases

GET /v1/cases

Requires scope: read.

Query parameters:

tenant_idstring

Filter by tenant. Returns all tenants if empty.

limitnumber

Number of records to return. Default 50, max 200.

client_reference_idstring

Filter by the client-supplied reference passed at creation. Returns at most one case (the reference is unique per tenant) — use this to recover a case by your own identifier, e.g. after a create call errored.

Response (200): Array of Case objects (without document details).

Get Case

GET /v1/cases/{session_id}

Requires scope: read. Returns the full case including all document records.

session_idstringrequired
UUID of the case.

Add Document to Case

POST /v1/cases/{session_id}/documents

Requires scope: write. Uploads a document file (multipart/form-data). The file is stored in encrypted object storage and processed immediately by the agent pipeline (classify → extract → validate).

Accepted MIME types: image/jpeg, image/png, image/webp, image/tiff, image/bmp, image/gif, application/pdf

Maximum file size: 20 MB

session_idstringrequired
UUID of the case.

Form fields:

filefilerequired

The document file.

labelstring

Optional label for this document (e.g. "front", "back").

Response (200):

doc_idstring
UUID of the created document record.
document_typestring
Classified document type.
confidencestring
Classification confidence.
extractedobject
Extracted field values.
statusstring
done or failed
progressobject
Updated goal progress after this document.

Complete Case

POST /v1/cases/{session_id}/complete

Requires scope: write. Triggers final processing — runs cross-matching, governance checks, and generates the output package. This is an atomic DB transaction.

session_idstringrequired
UUID of the case.

Response (200):

session_idstring
statusstring
completed, review, or failed
resultobject
Final result with cross-match outcome, validation summary, and any flags.

Decision (Approve / Deny)

PATCH /v1/cases/{session_id}/decision

Requires scope: write. Human reviewer approves or denies a case that is in review status.

session_idstringrequired
UUID of the case.

Request body:

decisionstringrequired

"approve" or "deny".

reasonstring

Reviewer notes.

Response (200):

{
  "session_id": "...",
  "status": "completed",
  "decision": "approve",
  "reason": "Documents verified manually"
}

Returns 409 if the case is not in review status.

Send Message

POST /v1/cases/{session_id}/message

Requires scope: write. Conversational turn for intelligence level 2+ agents. The assistant processes the message (and any attached documents) and returns a reply.

session_idstringrequired
UUID of the case.

Request body:

messagestringrequired

User message text.

attachmentsobject[]

Optional document attachments. Each object: { "data": "<base64>", "mime_type": "image/jpeg", "filename": "id_front.jpg" }.

Response (200):

message_idstring
UUID of the stored user message.
replystring
Assistant reply text.
doc_resultsobject[]
Results for any attached documents processed in this turn.
progressobject
Updated goal progress.
session_statusstring
Current case status after this turn.

Get Messages

GET /v1/cases/{session_id}/messages

Requires scope: read. Returns the full conversation history for a case.

session_idstringrequired
UUID of the case.

Response (200): Array of message objects.

idstring
UUID of the message.
session_idstring
rolestring
"user" or "assistant"
contentstring
Message text.
attachmentsobject[]
Attachments included with this message.
metadataobject
Arbitrary metadata.
created_atstring

Get Report

GET /v1/cases/{session_id}/report

Requires scope: read. Returns the investigation report for a completed case. The report is cached after first generation.

session_idstringrequired
UUID of the case.

Query parameters:

regenerateboolean

Force report regeneration even if a cached version exists. Default false.

formatstring

"json" (default) or "pdf". The PDF response has Content-Disposition: attachment; filename="report_{id}.pdf".

Returns 422 if the case is still in collecting or processing status.

Download Document File

GET /v1/cases/{session_id}/documents/{doc_id}/file

Requires scope: read. Streams the original document file from storage.

session_idstringrequired
UUID of the case.
doc_idstringrequired
UUID of the document.

Response headers include Cache-Control: private, max-age=3600 and Content-Disposition: inline; filename="<filename>".

Replay Case

POST /v1/cases/{session_id}/replay

Requires scope: write. Creates a new case by re-downloading and re-processing all documents from an existing case against the current agent version. Useful for regression testing after an agent update.

session_idstringrequired
UUID of the original case to replay.

Response (201): New Case object.

PreviousAgentsNextDocument Types