Skip to Content
CerebrumDocs
GuidesAPI referenceTrust & security

Invite

An invite starts an applicant-hosted ID verification flow. It carries the package, organization, applicant contact details, delivery settings, expiry, optional metadata, and postback URL. The public inviteId returned by the API is the voucher ID used by the invite endpoints.

When the applicant submits and Cerebrum creates an order, the invite is marked COMPLETE and linked to that order. Processing can still be pending, so invite completion and order-result completion are separate milestones.

Creating invites

Create through:

  1. API — Create vID Invite.
  2. Dashboard — use Cognition's Create Invite workflow.
  3. Self-service — where enabled for your organization.

Only packageId and contactInformation.email are required for a minimal invite. Phone number is optional. deliveryMethod defaults to EMAIL; use NONE to distribute the returned link yourself. Set web: true for the browser flow or use the app/deep-link experience when intended.

The default expiry is 30 days, configurable per package with its invite-expiry setting. It is not a universal 180-day default. Expiry is evaluated when the applicant uses the invite.

Reuse and force-new behavior

By default, create reuses an invite only when all of these match:

  • the same packageId;
  • the same applicant email, case-insensitively;
  • the same effective organization;
  • no attached order;
  • status PENDING or STARTED.

An expired timestamp does not by itself prevent reuse. Reuse retains the public inviteId, renews expiry using the package setting or 30-day default, and updates explicitly supplied name fields while preserving omitted or null name fields. Stored metadata, postback URL, and phone number are not updated. inviteData in a response echoes the current request and does not prove those values changed on a reused invite.

Set forceNewInvite: true only when you intentionally need a separate invite and fresh stored values. It bypasses voucher and account-invite reuse without canceling or changing the old invite. It is not an idempotency key.

Bulk deduplication

POST /v1/vid/multiple-invites first keeps only the first request entry for each [effectiveOrganizationId, lowercasedEmail] pair. Package ID, metadata, names, and forceNewInvite are not part of this request-level key. Two entries for the same organization and email therefore collapse even if they request different packages or set forceNewInvite: true.

Surviving entries are processed in parallel. The response contains one element per surviving entry, either an invite response or { "error": "...", "email": "..." }; removed duplicates have no response element. An empty request array is a 400 error. Per-item errors do not necessarily fail the entire bulk request.

Bulk request deduplication and cross-request invite reuse are different behaviors. Neither replaces retaining each returned inviteId and correlating it through GET /v1/vid/invites/{inviteId}.

Resend and cancel

Resend is available for a PENDING or STARTED invite with no attached order. It reuses the same invite, renews expiry, and sends a new delivery; it does not create a replacement order or reset the start timestamp. Use Resend vID Invite.

Cancel is likewise limited to a PENDING or STARTED invite with no attached order. A canceled invite cannot be used to start verification. See Cancel vID Invite.

Statuses

  • PENDING — the applicant has not started.
  • STARTED — the applicant started the flow; start information is retained on resend.
  • ACCEPTED — the applicant accepted where that lifecycle applies.
  • COMPLETE — an order was created and linked; results may still be pending.
  • CANCELED — the organization canceled before order creation.
  • OPT_OUT — the applicant opted out of the verification flow.

Use GET /v1/vid/invites/{inviteId} to read status and orderId. Before an order exists, orderId is null and order is omitted. Afterward, use that UUID with GET /v1/orders/{orderId} for the exact result.

Metadata

Invite metadata is copied to order additionalMetadata at order creation. Listed invites expose stored metadata through GET /v1/vid/invites. The single-invite status response's nested order.additionalMetadata is currently always {}, so use the exact order endpoint for authoritative order metadata.

Ordinary invite and order webhook payloads include the stored object as additionalMetadata, with event-specific exceptions documented in the event catalog. See Attaching Custom Data to Orders.

Invite webhook events

  • VOUCHER_REDEEMED — an invite-backed order was created and its postback webhook registered. This is not merely an acceptance event.
  • VOUCHER_ACCEPTED — optional acceptance notification.
  • VOUCHER_STARTED — optional notification for the eligible transition to STARTED.
  • VOUCHER_CANCELED — optional cancellation notification.
  • VOUCHER_EXPIRED — expiry was reached for an eligible invite with a postback URL.
  • VOUCHER_OPTED_OUT — an eligible invite transitioned to opt-out.

Accepted, started, and canceled events are disabled unless enabled in package or organization webhook metadata. Every notification uses idType: "invite" and the invite UUID, not an order UUID. See Event types and Verify webhook signatures.

On this page