Quickstart
Create one web invite, retain its invite ID, correlate it to the exact order, and read the completed verification result. The identifiers and responses below are synthetic but internally consistent.
Prerequisites
You need:
- A Cerebrum API key in a supported environment. See API key authentication.
- A package available to your organization and its
packageId. Use List Package Sets or ask your Cerebrum administrator. - An applicant who can complete the web verification flow.
- Optionally, an HTTPS webhook receiver. This tutorial also shows the invite-status lookup used to find the order.
No public sandbox, pre-provisioned test identity, or fixed completion time is assumed. Set values for your own environment:
export CEREBRUM_BASE_URL="https://api.cerebrum.com"
export CEREBRUM_API_KEY="REPLACE_WITH_YOUR_API_KEY"
export PACKAGE_ID="81eb7401-8ff0-4404-8450-4d7508482c19"
export ORGANIZATION_ID="a3f1c9d2-6b4e-4c8a-b7e5-2d9f0e1a3c47"1. Create the invite
This minimal request selects a web invite, suppresses Cerebrum email delivery so you can distribute the URL yourself, and attaches an internal correlation value. Only contactInformation.email is required in contactInformation; a phone number is optional.
curl --request POST "$CEREBRUM_BASE_URL/v1/vid/invites" \
--header "apikey: $CEREBRUM_API_KEY" \
--header 'content-type: application/json' \
--data '{
"packageId": "'"$PACKAGE_ID"'",
"organizationId": "'"$ORGANIZATION_ID"'",
"contactInformation": {
"email": "applicant@example.com",
"firstName": "Jordan",
"lastName": "Lee"
},
"deliveryMethod": "NONE",
"web": true,
"forceNewInvite": true,
"metadata": {
"clientReferenceId": "APP-1042"
}
}'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"
}
}
}URL and QR values are shortened synthetic placeholders. The real response contains generated values in the same fields.
Persist inviteId and metadata.clientReferenceId in your system. inviteId is the public voucher identifier used by the invite endpoints. Send vIDWebInviteUrl to the applicant; this web flow does not require a mobile app. Use deliveryMethod: "EMAIL" instead if Cerebrum should send the invitation email. Use vIDInviteUrl when intentionally selecting the app/deep-link experience.
The default invite lifetime is 30 days, configurable per package. This worked example sets forceNewInvite: true so each run intentionally creates a distinct voucher and stores the request's metadata on that new invite. Do not treat that flag as an idempotency key or use it when reuse is your goal.
Without forceNewInvite (or an internal reorder reason), the default behavior reuses an invite only when it has the same package, case-insensitive email, and effective organization, has no order, and is PENDING or STARTED. Reuse retains the returned inviteId, renews expiry, and updates explicitly supplied names, but does not update stored metadata, postback URL, or phone number. inviteData in the response echoes the current request, so it does not prove that changed metadata was persisted on reuse. Use forceNewInvite: true only when you intentionally need a separate invite and fresh correlation values. See Invite.
2. Find the order created from that invite
The applicant follows the web flow and submits verification. Before an order exists, GET /v1/vid/invites/{inviteId} returns orderId: null and omits order:
export INVITE_ID="8faf4d07-6fec-43b8-a32c-cd549c30b5e9"
curl --request GET "$CEREBRUM_BASE_URL/v1/vid/invites/$INVITE_ID" \
--header "apikey: $CEREBRUM_API_KEY"{
"inviteId": "8faf4d07-6fec-43b8-a32c-cd549c30b5e9",
"status": "PENDING",
"orderId": null
}After the applicant submits, the same invite has an attached order:
{
"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"
}
}Invite COMPLETE means the invite has been redeemed into an order. It does not prove that processing has finished; the nested order can still be PENDING. The nested order.additionalMetadata is currently always an empty object, so retrieve the exact order for authoritative metadata.
Store orderId. Do not substitute a package-wide order list when several applicants can use the same package.
3. Observe completion
A configured webhook sends a compact notification when order state changes. Verify and durably accept it as described in Verify webhook signatures.
{
"id": "0bb0f6f8-459f-482a-952e-7caf029517f6",
"idType": "order",
"organizationId": "a3f1c9d2-6b4e-4c8a-b7e5-2d9f0e1a3c47",
"additionalMetadata": {
"clientReferenceId": "APP-1042"
},
"metadata": {
"delta": [
{
"op": "replace",
"path": "/status",
"before": "PENDING",
"after": "COMPLETE"
}
]
},
"event": "ORDER_STATUS_CHANGE",
"eventDate": "2026-11-03T16:27:41.000Z",
"svixAppId": "app_2z7K9synthetic000000000001"
}The notification is not the full order. Use its id with idType: "order" to fetch that exact order. If you are polling instead, use the orderId already obtained from the invite.
4. Retrieve the exact result
export ORDER_ID="0bb0f6f8-459f-482a-952e-7caf029517f6"
curl --request GET "$CEREBRUM_BASE_URL/v1/orders/$ORDER_ID" \
--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"
}Interpret these fields independently: status is order lifecycle, score is the verification or screening outcome, and alert reports whether alerts were found. The invite's metadata is available here as additionalMetadata, matching APP-1042 throughout the workflow.
For additional verification data, repeat expand for each value:
curl --request GET "$CEREBRUM_BASE_URL/v1/orders/$ORDER_ID?expand=id_verification_data&expand=verification_check_results" \
--header "apikey: $CEREBRUM_API_KEY"id_verification_data populates idVerificationData; verification_check_results populates verificationCheckResults. Other expansion options are documented in Get Order Details.