Every document managed through CheckHub goes through a lifecycle represented by a status. Understanding these statuses is essential for building a robust integration, as they determine what state a document is in and what actions can or should be taken.
How Statuses Work
Each document status has three components:
- Code — a numeric identifier (e.g.
100,400,901) used in the API.
- Name — a human-readable constant (e.g.
REQUESTED_BY_ADMIN,EXPIRED) that describes the specific status.
- Meta Status — a higher-level grouping (e.g.
REQUESTED,PENDING,VALIDATED,ERROR) that categorizes statuses into broad lifecycle stages.
The meta status is useful when you want to simplify your integration logic. Instead of handling every individual status code, you can branch on the meta status to cover the main document lifecycle phases.
Status Reference Table
Meta Status | Code | Name | Description |
REQUESTED | 100 | REQUESTED_BY_ADMIN | The document has been requested manually by an admin user through the CheckHub interface. |
REQUESTED | 101 | REQUESTED_BY_INTEGRATION | The document has been requested programmatically via the API or an integration. |
PENDING | 300 | WAITING_MANUAL_CHECK | The document has been uploaded and is waiting to be reviewed manually by an admin. |
PENDING | 301 | WAITING_AUTO_CHECK | The document has been uploaded and is currently being processed by an automated check. |
PENDING | 302 | WAITING_UPLOADING_END | The document file is still being uploaded and is not yet fully received. |
VALIDATED | 400 | VALIDATED_BY_ADMIN | The document has been reviewed and approved by an admin user. |
VALIDATED | 403 | VALIDATED_BY_AUTO_CHECK | The document has been automatically validated by the system's automated checks. |
ERROR | 900 | REJECTED_BY_ADMIN | The document has been reviewed and rejected by an admin user. |
ERROR | 901 | REJECTED_BY_AUTO_CHECK | The document has been rejected by the system's automated checks. |
ERROR | 905 | EXPIRED | The document has passed its validity period and is no longer considered valid. |
Meta Status Overview
REQUESTED — The document has been asked for but not yet uploaded by the collaborator. This is the initial stage of the document lifecycle.
PENDING — The document has been uploaded and is awaiting processing or review. It is not yet in a final state.
VALIDATED — The document has been accepted, either manually by an admin or automatically by the system. This is a successful final state.
ERROR — Something went wrong: the document was rejected (by an admin or automatically) or has expired. The collaborator may need to re-upload a new version.
Tips for Integrators
- When polling or receiving webhooks, use the numeric code for precise status matching and the meta status for broader lifecycle logic.
- Always handle the
EXPIREDstatus (905): documents can transition to this state automatically when their validity period ends, even if they were previously validated.
- The
PENDINGmeta status covers multiple sub-states — make sure your integration accounts for the fact that a document may remain in this state while it is being uploaded, auto-checked, or awaiting manual review.