Skip to content
Developers
Back to Steward

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

Section titled “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, so fetch it when you need it rather than caching it.

Operations

Section titled “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)
Bulk delete POST /documents/bulk/delete Soft delete up to 500 selected documents
Classification GET /documents/{id}/classification Async classification result (see below)
Download all GET /documents/download-all?applicationId=… Every document on one application, as a single zip

GET /documents/download-all streams the file bytes themselves rather than a list of signed links, so nothing in the response expires. Prefer it over walking the list and fetching each url when you want a complete set.

Bulk delete

Section titled “Bulk delete”

POST /documents/bulk/delete accepts documentIds and soft-deletes each selected document. Repeated ids are coalesced in request order. A selected parent also hides its child sides that are still visible and resolves their document tasks. When a parent and its child are both selected, each selected id appears once in the changed or skipped result; an id that was already hidden, with nothing left to hide beneath it, is skipped. Storage objects are not erased.

The request is checked before any mutation. Missing selected ids return 404, ids outside the API key’s account return a generic 403, and documents on Steward-hidden applications, or documents Steward hid, return 404. The synchronous operation does not promise one database transaction across downstream infrastructure failures.

Hidden documents

Section titled “Hidden documents”

Deleting a document hides it, and Steward records that your account hid it: the document’s hiddenSource reads CLIENT. Your team can bring it back from the Documents tab in the Steward platform, where “Show hidden documents” lists what your account hid. Documents Steward hid are never listed for you, GET /documents/{id} and its classification return 404 for them, and they cannot be brought back from the platform.

GET /documents leaves hidden documents out by default. Pass includeHidden=true to also list the ones your account hid; they come back with hidden: true and hiddenSource: "CLIENT". hiddenSource is null on a visible document.

Classification

Section titled “Classification”

Document classification is asynchronous, so 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.

A composite ID upload (both sides in one image, or ID pages inside a multi-page PDF) may also carry a split object. split is null when no split was enqueued.

split.status Meaning
pending A background split is in flight. requiresBack is null so clients must not prompt for a back image yet. Keep polling.
completed Derived front and (when present) back documents were created. frontDocument is the derived front descriptor (documentId, key, fileName, contentType); backDocumentId is the derived back; frontRows are the front’s ID-card checks as { key, isValid, label } (with explanation only on readabilityIssues).
rejected / failed The split did not produce usable sides. Treat the original upload as today’s front and prompt for a back if requiresBack is true.

otherDocumentsDetected is true when non-ID pages were set aside on the composite. multipleIdsDetected is true when more than one ID was found and the clearest one was used.

Example

Section titled “Example”
Terminal window
# 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"