Verification Tokens

Verification tokens

A verification token is the unit of data shared between the Donor and Recipient. It represents one approved customer record at a specific point in time.

Key characteristics

  • Immutable: A token is a snapshot. Changes made to the Donor's record after token creation do not update it.
  • Long-lived: Tokens do not expire, including tokens waiting in a manual import queue.
  • Scoped: Each token belongs to one Donor, one Recipient, and one agreement version.
  • Traceable: The token ID, agreement context, and import activity provide a reference for audit and troubleshooting.

What's inside a token?

A token contains the data permitted by the agreement, along with the metadata needed to trace the share.

Token informationPurpose
Token IDProvides a unique reference for the shared record.
Agreement ID and versionIdentifies the agreement terms that governed the share.
Agreement snapshotPreserves the agreement terms at the time the token was created.
Donor template snapshotProvides context about the Donor's template configuration.
Donor-side entity referenceLinks the token to the original Donor-side case for routing follow-ups.
Consent informationRecords the end customer's consent to share.
Shared customer dataContains the inputs and documents permitted by the agreement.
Token stateShows the token's import lifecycle state.

The information available to the Recipient depends on the selected trust level:

  • No Reliance: Shares inputs and documents.
  • Smart Reliance: Allows selected data and verification information to be reused.
  • Full Reliance: Shares the complete verification information covered by the agreement.

Token lifecycle

The token lifecycle tracks its progress from creation to import into the Recipient's account.

stateDiagram-v2
    direction LR
    [*] --> READY_TO_BE_EXPORTED: Customer approved and agreement matched
    READY_TO_BE_EXPORTED --> READY_TO_BE_IMPORTED: Settle window ends and eligibility passes again
    READY_TO_BE_IMPORTED --> IMPORTING: Automatic import or import action
    IMPORTING --> IMPORTED: Record created and template processed
    IMPORTING --> IMPORT_FAILED: Import could not complete
    IMPORTED --> [*]
    IMPORT_FAILED --> [*]
StateWhat it meansSeen by
READY_TO_BE_EXPORTEDThe Donor approved the customer and a live agreement matched. AiPrise waits out a short settle window, then checks eligibility again before sending the token.Donor
READY_TO_BE_IMPORTEDThe token has been sent and is waiting in the Recipient's import queue. With automatic import, it moves on straight away.Donor and Recipient
IMPORTINGAn import is running.Donor and Recipient
IMPORTEDThe Recipient's own profile or session has been created from the token.Donor and Recipient
IMPORT_FAILEDThe import could not complete. The failure reason is recorded on the token.Donor and Recipient
TOKEN_EXPORT_FAILEDThe token could not be sent. Contact AiPrise support.Donor

An import runs once. A failed import is not retried automatically, and calling import again on a failed token does nothing. If the customer no longer qualifies when the settle window ends, no token is sent.

To work with tokens through the API, see Token Sharing API Integration.


Did this page help you?