Skip to content
Developers
Back to Steward

Get the latest ID-document classification job for this document

GET
/api/v1/documents/{documentId}/classification

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
documentId
required
string

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”
Media type application/json
object
status
required
string
Allowed values: PENDING PROCESSING COMPLETED FAILED
classifiedType

Classified document subtype. Null if classification was inconclusive or not yet complete.

string
Allowed values: PASSPORT DRIVING_LICENSE ID_CARD
requiresBack

Whether this document type requires a back image upload (true for driving licence and national ID)

boolean
nullable
isGovernmentId

True iff the validator classified the document as one of the accepted subtypes (passport, driving licence, national ID). Equivalent to classifiedType !== null. Null while classification is still in flight.

boolean
nullable
invalid

True when the validator clearly identified the document as a government-issued document of a TYPE WE DO NOT ACCEPT (e.g. residence permit, work permit, birth certificate). False when accepted or when the type is unclear. Null while classification is still in flight. Drives an upload-time hard rejection (the user must re-upload).

boolean
nullable
invalidReason

Short name of the unaccepted document type, when invalid is true. Used for the rejection copy (e.g. “residence permit”). Null otherwise.

string
nullable
mismatchedFront

For back-of-ID documents (parentDocumentId set): true when the back’s classified type doesn’t match the front’s. Null for fronts or when comparison isn’t possible (front still classifying, no parent, etc.).

boolean
nullable
split

Composite-upload split state. Null when this document was not enqueued for a split. While status is pending, requiresBack is null so clients do not prompt for a back mid-split.

object
status
required

Background split of a composite ID upload. Absent (the parent split is null) when no split was enqueued.

string
Allowed values: pending completed rejected failed
frontDocument

Derived front descriptor once the split completed. Null while pending, rejected, or failed.

object
documentId
required

Derived front document id after a completed split.

string
key
required

S3 key of the derived front file.

string
fileName
required

Derived front file name, e.g. “passport – front.png”.

string
contentType
required

MIME type of the derived front file.

string
backDocumentId

Derived back document id (child of the front) once the split completed. Null when no back was derived or the split is not completed.

string
nullable
multipleIdsDetected
required

True when the layout detector reported more than one ID in the upload.

boolean
otherDocumentsDetected
required

True when non-ID pages were set aside on the composite (the planner flag persisted at enqueue).

boolean
frontRows

Derived front’s ID-card rows as { key, isValid, label }. explanation is carried only for isValidDocument, readabilityIssues and hasFrontSide. Null unless the split completed.

Array<object>
nullable
object
key
required

ID-card attribute key, e.g. “isValidDocument” / “readabilityIssues”.

string
label
required

Server display label for this attribute, e.g. “First Name”.

string
isValid
required

Normalized pass/fail for this attribute.

boolean
explanation

Present only for isValidDocument, readabilityIssues and hasFrontSide: the keys the applicant already sees explained on the sync upload path. Null or omitted for every other key.

string
nullable
derivedBackDocumentId

This document’s derived back child (metadata.splitRole=back), including hidden pre-adoption rows. Null when this document has no such child. Bounded to an id, the same contract as split.backDocumentId.

string
nullable
frontRows

This document’s own ID-card rows as { key, isValid, label }. explanation is carried only for isValidDocument, readabilityIssues and hasFrontSide: the keys the applicant already sees on the sync upload path. Null while classification is not completed.

Array<object>
nullable
object
key
required

ID-card attribute key, e.g. “isValidDocument” / “readabilityIssues”.

string
label
required

Server display label for this attribute, e.g. “First Name”.

string
isValid
required

Normalized pass/fail for this attribute.

boolean
explanation

Present only for isValidDocument, readabilityIssues and hasFrontSide: the keys the applicant already sees explained on the sync upload path. Null or omitted for every other key.

string
nullable
splitRole

This document’s metadata.splitRole when it is a derived split child. Null for an ordinary upload that was never split.

string
nullable
Allowed values: front back
Examples
{
  "status": "COMPLETED",
  "classifiedType": "PASSPORT",
  "requiresBack": false,
  "isGovernmentId": true,
  "invalid": false,
  "invalidReason": null,
  "mismatchedFront": null,
  "split": null,
  "derivedBackDocumentId": null,
  "frontRows": [
    {
      "key": "isValidDocument",
      "label": "Valid Document",
      "isValid": true
    }
  ],
  "splitRole": null
}

404

Section titled “ 404 ”

Document or classification not found