📌 A note on terminology — CheckHub's newer web interface (Admin) uses the term contact to be more generic, while the API still uses the term candidate from the original version. The two refer to the same entity. This article uses candidate to stay consistent with the API, where these status codes appear.
Every candidate 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 candidate profile is in and what actions can or should be taken.
How Statuses Work
Each candidate status has three components:
- Code — a numeric identifier (e.g.
100,201,900) used in the API payloads.
- Name — a human-readable constant (e.g.
NEW_CANDIDATE,VALIDATION_IN_PROGRESS) that describes the specific status.
- Meta Status — a higher-level grouping (e.g.
NEW_CANDIDATE,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 workflow phases of a candidate.
Status Reference Table
Meta Status | Code | Name | Description |
NEW_CANDIDATE | 100 | CREATED_BY_ADMIN | The candidate profile has been manually created by an admin user through the CheckHub interface. |
NEW_CANDIDATE | 101 | CREATED_BY_INTEGRATION | The candidate profile has been created programmatically via the API or a third-party integration. |
PENDING | 200 | DOCUMENT_OR_RESOURCE_NEEDED | The candidate profile is awaiting required documentation, files, or external resources before it can proceed. |
PENDING | 201 | COMPLETE | All required information and documentation have been provided; the profile is ready for review. |
PENDING | 202 | VALIDATION_IN_PROGRESS | The candidate's files or profile details are currently undergoing manual or automated validation. |
VALIDATED | 300 | VALIDATED_BY_ADMIN | The candidate profile and all associated data have been reviewed and successfully approved by an admin. |
VALIDATED | 301 | VALIDATED_BY_AUTO_CHECK | The candidate profile has passed all automated verification checks and is successfully validated. |
ERROR | 900 | REJECTED_BY_ADMIN | The candidate profile has been manually reviewed and rejected by an admin. |
ERROR | 901 | REJECTED_BY_INTEGRATION | An external integration or API process flagged an issue and rejected the candidate profile. |
ERROR | 902 | REJECTED_BY_AUTO_CHECK | The system's automated check rules failed, resulting in an automatic rejection of the candidate. |
Meta Status Overview
NEW_CANDIDATE — The initial stage of the candidate lifecycle. The profile has been successfully provisioned in the system but no verification work has started yet.
PENDING — The active operational stage. The candidate is either uploading required assets, waiting to be processed, or currently in the review queue.
VALIDATED — The successful final state. The candidate has passed all criteria (either via automated rules or human eyes) and is fully cleared.
ERROR — Something went wrong. The profile has been rejected by an admin, an automation routine, or an external system. Active intervention or re-submission is typically required to move the candidate out of this state.
Tips for Integrators
- When polling or receiving webhooks, use the numeric code for precise status matching and the meta status for broader lifecycle logic.
- Remember that the
PENDINGmeta status covers multiple sub-states (200,201,202) — make sure your integration accounts for a candidate moving through resource collection, completion, and validation while still under the same meta status.
- Both the
NEW_CANDIDATEandERRORmeta statuses distinguish between admin-driven and integration/automated actions via their codes — branch on the specific code when you need to know the origin of a status change.
- A candidate created via your integration will start at code
101(CREATED_BY_INTEGRATION), which is a useful signal for reconciling records on your side.