Order
An Order is the record of a verification or screening request for one applicant. It holds the applicant's information, the searches performed, their results, and the outcome fields described below.
Orders are created in two main ways:
- From an invite. When an applicant submits the ID verification flow started by an invite, Cerebrum creates the order. Get vID Invite returns its
orderIdonce it exists; until thenorderIdisnull. - Directly. Create Standard Order creates a screening order from applicant data you send, without an invite.
An order is not necessarily finished. It starts as PENDING and moves through the statuses below. Use Score, Status and Alert to decide when an order is complete and what its outcome means.
Order Lifecycle
An order can include:
- User information (name, email, address)
- Submitted identity documents
- Verification checks performed (ID verification, liveness detection, background checks)
- Final verification outcome and risk assessment
Searches can be added to an existing order with Add Search to Order. When a search is dispatched for an order whose status is COMPLETE, the order's status returns to PENDING until the new work is reported. Adding the search does not change its score or alert, so an order can be PENDING while still showing the score and alert from its earlier completion. Status, score and alert are independent fields.
Order Statuses
The API returns these exact values in status. An order without a stored status is returned as PENDING.
| Value | Meaning |
|---|---|
PENDING | Order created, awaiting processing or review |
IN_PROGRESS | Verification is actively being processed |
IN_DISPUTE | Results are under review or dispute |
INCOMPLETE | Verification was not completed |
COMPLETE | Order has been reviewed - either by automation or a human processor |
Order Scores
The order score provides a standardized assessment of the verification outcome. Responses return the same enum values that Update Order and Update Order Score accept, for example NO_ALERTS, not a display label such as "No Alerts". score is null until a score is set.
| Value | Meaning |
|---|---|
ID_VERIFIED | Identity document successfully verified |
ID_NOT_VERIFIED | Identity document could not be verified |
NO_ALERTS | No alerts found during verification |
ALERTS_FOUND | Alerts were detected during verification |
PENDING | Awaiting processing |
REVIEW_REQUIRED | Additional review needed |
CLIENT_REVIEW | Manual review required by client |
REVIEW_PASS | Order passed the review process |
SCREENING_ALERT | Screening detected potential issues |
SCREENING_NO_ALERT | Screening completed without alerts |
SCREENING_PENDING | Screening results are pending |
ON_HOLD | CRA is internally checking the document - an intermediate state, not final |
PRE_ADVERSE | Pre-adverse action indicated |
ADVERSE_ACTION | Adverse action required based on results |
WITHDRAWN | User has withdrawn from the verification |
The API can also return SCREENING_CLEAR and NO_DRUG_TEST. Store any score you do not recognize and handle it as described in Score, Status and Alert.
Order Alert
A simple binary signal that indicates whether any alerts were found on the order.
| Value | Meaning |
|---|---|
null | No alert value has been set yet |
NO_ALERTS_FOUND | No alerts were detected |
ALERTS_FOUND | One or more alerts were detected |
Custom Scores
Assign custom risk scores or decisioning outcomes based on your internal rules and criteria. Custom scores allow you to evaluate orders using additional data points beyond standard verification results, enabling tailored risk assessment aligned with your business requirements. customScore is free text, or null when not set.
Metadata
Orders inherit metadata from their originating invite and support additional key-value pairs for tracking and reconciliation. Metadata is:
- Automatically copied from the invite
- Included in the payloads of order events such as
ORDER_STATUS_CHANGEandORDER_SCORE_CHANGE. Some events carry event-specific metadata instead; see Event Types for each event's payload - Accessible via API when retrieving order details
- Preserved throughout the order lifecycle
Common use cases include storing transaction IDs, internal user references, or application-specific context.
For detailed information about Metadata, see the Attaching Custom Data to Orders documentation.
Webhooks
Configure webhook notifications during invite creation to receive real-time order updates at your postback URL.
Supported Events
- ORDER_STATUS_CHANGE - Triggered when order status changes
- ORDER_SCORE_CHANGE - Triggered when order score updates
- ORDER_CUSTOM_SCORE_CHANGE - Triggered when custom score is modified
- ORDER_DISPUTE_RESOLVED - Triggered when dispute is resolved
For detailed information about webhook payloads and security, see the Webhooks documentation.
Retrieving Orders
Get Order Details
Retrieve one order with Get Order Details. The response includes status, score, alert, custom score, metadata and report links.
Related data is included only when you request it with expand. Repeat the parameter for each value:
GET /v1/orders/0bb0f6f8-459f-482a-952e-7caf029517f6?expand=reportable_results&expand=vid_report
apikey: $CEREBRUM_API_KEYAccepted values are id_verification_data, reportable_results, background_report_pdf, signed_disclosure, vid_report, verification_check_results, credentials, selfie and ip_address_details. idVerificationData is accepted as a legacy alias of id_verification_data. Comma-separated values such as expand=reportable_results,vid_report are not split, and unknown values are ignored, so check the spelling of each value.
List Orders
Retrieve a page of orders with List Orders. Filter by:
- Package ID (
packageId) - Order status (
status) - Metadata (
metadata, a URL-encoded JSON object matched by containment)
The default page size is 10 and the maximum is 30. Follow links.next until it is null to read every page. List Orders accepts the same expand values.