Skip to Content
CerebrumDocs
GuidesAPI referenceTrust & security

ID Verification Flow

Complete guide to Cerebrum's ID verification workflow, from invite creation to verification results

Use this workflow when an applicant should complete ID verification through a hosted web or app experience. The integration creates an invite, the applicant supplies verification data, Cerebrum creates an order from that invite, and your system retrieves the exact result.

For a direct screening order with applicant data already in your system, use the Standard Order API instead.

Flow overview

flowchart TD
    Org[Create invite] --> Applicant[Applicant opens web or app invite]
    Applicant --> Submit[Applicant accepts, starts, and submits verification]
    Submit --> Order[Cerebrum creates and links order]
    Order --> Processing[Verification processing continues]
    Processing --> Notification[Compact signed webhook]
    Notification --> Retrieve[Retrieve exact order by ID]

The invite can be delivered by Cerebrum email or returned for you to distribute. A web invite works in a browser; an app invite uses the vID mobile experience. Not every integration requires an app installation.

1. Prepare the integration

You need an API key, a package available to the effective organization, and an applicant email. contactInformation.phoneNumber is optional. An HTTPS postbackWebhookUrl is recommended for completion notifications.

Only packageId and contactInformation.email are required for a minimal invite. deliveryMethod defaults to EMAIL; NONE returns the links without sending the Cerebrum invite email. web defaults to false unless package configuration selects web invites. Set web: true to explicitly select the browser flow.

The default invite expiry is 30 days, configurable through the package's invite-expiry setting. Reuse, resend, and force-new behavior is covered in Invite.

2. Create the invite

Request: POST /v1/vid/invites with Content-Type: application/json and the apikey header. See Create vID Invite.

For a no-email variant, set deliveryMethod to NONE and distribute vIDWebInviteUrl yourself. onSubmitReturnUrl can optionally redirect the applicant after submission. This correlated example sets forceNewInvite: true so its metadata and postback URL belong to a newly created invite; the flag is not an idempotency key. Without it, a reusable invite retains its earlier stored metadata and postback URL even though inviteData echoes the new request.

The endpoint returns 201 Created:

{
  "inviteId": "8faf4d07-6fec-43b8-a32c-cd549c30b5e9",
  "packageId": "81eb7401-8ff0-4404-8450-4d7508482c19",
  "packageName": "Standard ID Verification",
  "vIDInviteUrl": "https://cerebrum.app.link/EXAMPLE",
  "vIDWebInviteUrl": "https://cognition.cerebrum.com/vid/i/EXAMPLE",
  "vIDQRCode": "data:image/png;base64,iVBORw0KGgo=",
  "vIDShortCode": "ABC123",
  "inviteExpiry": "2026-12-02",
  "inviteData": {
    "contactInformation": {
      "email": "applicant@example.com",
      "firstName": "Jordan",
      "lastName": "Lee"
    },
    "metadata": {
      "clientReferenceId": "APP-1042"
    }
  }
}

The URL and QR strings are shortened synthetic placeholders. Retain inviteId; it is the public voucher ID used by the invite endpoints. Send vIDWebInviteUrl for this explicitly selected web flow. inviteExpiry is formatted YYYY-MM-DD.

3. Applicant starts and submits

The applicant opens the invite, accepts it where required, starts the flow, supplies document and biometric information, reviews the extracted data, completes required disclosures, and submits. Capture requirements vary by package and flow; do not assume every package asks for identical documents, SSN, disclosures, or extra data.

Invite lifecycle notifications are compact and use idType: "invite" with the invite UUID:

  • VOUCHER_ACCEPTED, VOUCHER_STARTED, and VOUCHER_CANCELED are optional events and are disabled unless enabled in package or organization webhook metadata.
  • VOUCHER_REDEEMED is emitted after an invite-backed order is created and its postback webhook is registered.
  • VOUCHER_EXPIRED and VOUCHER_OPTED_OUT have their own lifecycle prerequisites.

See Event types for every trigger and payload. Optional event settings do not change signature verification.

4. Correlate the invite to its exact order

Before submission, Get vID Invite returns orderId: null and omits order:

{
  "inviteId": "8faf4d07-6fec-43b8-a32c-cd549c30b5e9",
  "status": "PENDING",
  "orderId": null
}

Order creation atomically links the order to the voucher and marks the voucher COMPLETE. Afterward, GET /v1/vid/invites/{inviteId} returns the order UUID:

{
  "inviteId": "8faf4d07-6fec-43b8-a32c-cd549c30b5e9",
  "status": "COMPLETE",
  "orderId": "0bb0f6f8-459f-482a-952e-7caf029517f6",
  "order": {
    "id": "0bb0f6f8-459f-482a-952e-7caf029517f6",
    "backgroundReportUrl": "https://cognition.cerebrum.com/user/e4b7d1c3-9a2f-4f6e-8d1b-3c5a7e9f2b64?tab=Documents",
    "additionalMetadata": {},
    "status": "PENDING",
    "score": null,
    "alert": null,
    "createdAt": "2026-11-03T16:20:00.000Z",
    "updatedAt": "2026-11-03T16:20:00.000Z"
  }
}

COMPLETE on the invite means the order exists, not that verification processing is complete. Persist orderId for exact retrieval. The nested order.additionalMetadata is currently always {}; fetch the order for the metadata copied from the invite.

5. Accept notifications durably

A completion-related order notification has idType: "order" and the order UUID, not the invite UUID:

{
  "id": "0bb0f6f8-459f-482a-952e-7caf029517f6",
  "idType": "order",
  "organizationId": "a3f1c9d2-6b4e-4c8a-b7e5-2d9f0e1a3c47",
  "additionalMetadata": {
    "clientReferenceId": "APP-1042"
  },
  "event": "ORDER_STATUS_CHANGE",
  "eventDate": "2026-11-03T16:27:41.000Z",
  "svixAppId": "app_2z7K9synthetic000000000001"
}

This example has no pre-update snapshot, so metadata is omitted. When a delta is present, it can also be an empty array. See Webhook Payload Deltas.

Always verify the Svix signature with the receiving endpoint's secret and exact raw body. Store svix-id with a uniqueness constraint, return 2xx promptly after durable acceptance (targeting under 10 seconds), and process duplicates idempotently. Do not perform slow resource retrieval before acknowledging. The signed receiver example implements this sequence.

Notifications do not contain the full order, all searches, or all results. Retrieve authoritative current state after accepting the message.

6. Retrieve the exact order

Use Get Order Details:

curl --request GET "https://api.cerebrum.com/v1/orders/0bb0f6f8-459f-482a-952e-7caf029517f6" \
  --header "apikey: $CEREBRUM_API_KEY"

A completed synthetic response is:

{
  "id": "0bb0f6f8-459f-482a-952e-7caf029517f6",
  "applicantContactDetails": {
    "email": "applicant@example.com",
    "phoneNumber": ""
  },
  "backgroundReportUrl": "https://cognition.cerebrum.com/user/e4b7d1c3-9a2f-4f6e-8d1b-3c5a7e9f2b64?tab=Documents",
  "reportDisputeUrl": "https://cognition.cerebrum.com/dispute/northwind-staffing/auth/0bb0f6f8-459f-482a-952e-7caf029517f6?email=applicant%40example.com",
  "additionalMetadata": {
    "clientReferenceId": "APP-1042"
  },
  "status": "COMPLETE",
  "score": "ID_VERIFIED",
  "customScore": null,
  "orderDeliveryType": "vIDWeb",
  "alert": "NO_ALERTS_FOUND",
  "createdAt": "2026-11-03T16:20:00.000Z",
  "updatedAt": "2026-11-03T16:27:41.000Z",
  "reportCompletedAt": "2026-11-03T16:27:41.000Z"
}

status, score, and alert are independent fields. Score values use raw uppercase enum values such as ID_VERIFIED, ID_NOT_VERIFIED, or NO_ALERTS, not display text such as No Alerts.

Repeat expand to request multiple related values:

curl --request GET "https://api.cerebrum.com/v1/orders/0bb0f6f8-459f-482a-952e-7caf029517f6?expand=id_verification_data&expand=verification_check_results" \
  --header "apikey: $CEREBRUM_API_KEY"
Expand tokenResponse field
id_verification_dataidVerificationData
reportable_resultsreportableResults
background_report_pdfbackgroundReportPdf
signed_disclosuresignedDisclosurePdf
vid_reportvIDReportPdf
verification_check_resultsverificationCheckResults
credentialscredentials
selfieselfieUrl
ip_address_detailsipAddressDetails

The legacy idVerificationData token is also accepted for idVerificationData. Expansion fields can be absent when no related data exists. Processing and search completion time varies by package and vendor; no fixed completion SLA is implied by this workflow.

On this page