Skip to Content
CerebrumDocs
GuidesAPI referenceTrust & security

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 orderId once it exists; until then orderId is null.
  • 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.

ValueMeaning
PENDINGOrder created, awaiting processing or review
IN_PROGRESSVerification is actively being processed
IN_DISPUTEResults are under review or dispute
INCOMPLETEVerification was not completed
COMPLETEOrder 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.

ValueMeaning
ID_VERIFIEDIdentity document successfully verified
ID_NOT_VERIFIEDIdentity document could not be verified
NO_ALERTSNo alerts found during verification
ALERTS_FOUNDAlerts were detected during verification
PENDINGAwaiting processing
REVIEW_REQUIREDAdditional review needed
CLIENT_REVIEWManual review required by client
REVIEW_PASSOrder passed the review process
SCREENING_ALERTScreening detected potential issues
SCREENING_NO_ALERTScreening completed without alerts
SCREENING_PENDINGScreening results are pending
ON_HOLDCRA is internally checking the document - an intermediate state, not final
PRE_ADVERSEPre-adverse action indicated
ADVERSE_ACTIONAdverse action required based on results
WITHDRAWNUser 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.

ValueMeaning
nullNo alert value has been set yet
NO_ALERTS_FOUNDNo alerts were detected
ALERTS_FOUNDOne 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_CHANGE and ORDER_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_KEY

Accepted 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.

On this page