Documents

A document is a file attached to an application — a proof of address, incorporation certificate, ID, and so on — typed by a DocumentType. Steward runs AI validations against uploaded documents and exposes the results.

Upload flow

Uploads are not multipart. The file itself is placed in Steward-provided S3 storage out of band; POST /documents then registers a document record pointing at that object. The request carries the applicationId, the type (a DocumentType), and the object’s fileName, key (S3 key), and contentType.

When you read a document, its url is freshly signed on each request and is short-lived — fetch it when you need it rather than caching it.

Operations

Operation	Endpoint	Notes
List	GET /documents?applicationId=…	Paginated, includes validations and notes
Upload	POST /documents	Registers a document (see above)
Get	GET /documents/{id}	Details + validation status
Delete	DELETE /documents/{id}	Soft delete — the document is hidden, not erased
Classification	GET /documents/{id}/classification	Async classification result (see below)

Classification

Document classification is asynchronous — poll GET /documents/{id}/classification until its status is COMPLETED. Until then the other fields are null.

status	Meaning
PENDING / PROCESSING	Classification in progress
COMPLETED	Result available
FAILED	Classification could not complete

Once complete, the response reports the detected identity-document type (classifiedType, one of PASSPORT, DRIVING_LICENSE, ID_CARD), whether a back image is required (requiresBack), whether the document is an accepted government ID (isGovernmentId), and rejection details (invalid, invalidReason) when the type is recognised but not accepted.

Example

# Register a document that has been uploaded to Steward storage
curl -X POST https://api.getsteward.ai/api/v1/documents \
  -H "Authorization: Bearer stw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "applicationId": "{id}", "type": "PROOF_OF_ADDRESS", "fileName": "utility-bill.pdf", "key": "uploads/abc123.pdf", "contentType": "application/pdf" }'

# List an application's documents
curl "https://api.getsteward.ai/api/v1/documents?applicationId={id}" \
  -H "Authorization: Bearer stw_live_your_api_key_here"

Environment: Examples use Production (https://api.getsteward.ai) with an stw_live_… key. For Sandbox, use https://api.steward-sandbox.com with an stw_test_… key.