Redeeming Share Tokens

Destination Organizations can redeem Share Tokens from their data sharing partners (Source Organizations) to copy and verify an end user’s data. Share Tokens can be redeemed into an Inquiry, Transaction, or Account in the Destination Organization’s Persona environment. Redeeming into an Inquiry automatically runs that Inquiry against the Destination Organization’s template, executing any Verifications and Reports it requires. Redeeming into a Transaction or Account hydrates the object with the shared data — there is no automated run, and any fields the source object does not have are simply left unset.

Destination Organizations can redeem Share Tokens via API, Dashboard, or Workflows.

Supported Destination Types

Inquiry — hydrates Inquiry fields, and runs Verifications and Reports using the Destination Organization’s Inquiry Template; reaches a terminal status (e.g., completed) or gets stuck if required fields are missing.
Transaction — hydrates Transaction fields with the shared data.
Account — hydrates Account fields with the shared data.

Destination Organizations can use the Connect API to redeem Share Tokens. The /redeem endpoint hydrates the destination object (set in the destination-id) with data from the source object. When the destination is an Inquiry, the /redeem endpoint also automatically runs that Inquiry in the Destination Organization’s Persona environment.

The /redeem endpoint’s destination-id accepts an Inquiry, Transaction, or Account ID (e.g., inq_XYZ789, txn_XYZ789, or act_XYZ789). To get a destination ID, first create the destination object via API. When the destination is an Inquiry, redeeming the Share Token will automatically run that Inquiry, and the inquiry-template-id used to create the Inquiry determines which Inquiry Template the /redeem endpoint uses to verify the end user’s data from the Share Token.

Redeem a Share Token

$ curl -X POST https://api.withpersona.com/api/v1/connect/share-tokens/cnst_ABC123/redeem \
>   -H "Authorization: Bearer <token>" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "data": {
>       "attributes": {
>         "destination-id": "inq_XYZ789"
>       }
>     }
>   }'

Share Token

1 {
2   "data": {
3     "type": "connect/share-token",
4     "id": "cnst_ABC123",
5     "attributes": {
6       "status": "redeemed",
7       "direction": "inbound",
8       "created-at": "2023-08-17T23:18:13.000Z",
9       "updated-at": "2023-08-17T23:18:13.000Z",
10       "expires-at": "2023-08-31T23:18:13.000Z",
11       "pending-at": "2023-08-17T23:18:13.000Z",
12       "redeemed-at": "2023-08-17T23:18:13.000Z"
13     },
14     "relationships": {
15       "connection": {
16         "data": {
17           "type": "connect/connection",
18           "id": "cxn_ABC123"
19         }
20       },
21       "destination": {
22         "data": {
23           "type": "inquiry",
24           "id": "inq_XYZ789"
25         }
26       }
27     }
28   }
29 }

Destination Organizations can also redeem Share Tokens using their Dashboard under the Connect > Share Tokens page. This can be helpful for testing and one-off data shares. Redeeming the Share Token requires providing the Share Token and selecting a destination object type along with the corresponding Inquiry Template, Transaction Type, or Account Type.

Persona Dashboard UI for redeeming a Share Token — Redeem a Share Token via the Dashboard

Destination Organizations can use Workflows to automate Share Token redemption into any destination type — Inquiry, Transaction, or Account. For example, the Destination Organization can use a Workflow to automatically redeem a Share Token upon creation by the Source Organization. This can be helpful for integrating into Connect with minimal development work.

Workflow diagram for automatic Share Token redemption — Redeem a Share Token via a Workflow

Destination Organizations with an Inquiry integration can redeem Share Tokens client-side by passing a Share Token ID as a parameter when instantiating Inquiries. The Inquiry will surface a consent screen to the end user, redeem the Share Token, and dynamically collect any additional data required by the Destination Organization’s Inquiry Template. This approach can minimize the development work associated with integrating into Connect and redeeming Share Tokens.

Client-side redemption supports Inquiry destinations only — the consent and dynamic-collection flow described below is Inquiry-specific. To redeem into a Transaction or Account, use the API, Dashboard, or Workflows.

How It Works

Pass in a Share Token ID as a parameter when instantiating Inquiries, alongside either inquiry-template-id (to create a new Inquiry) or inquiry-id (to resume an existing Inquiry).

Persona handles the rest:

The end user sees a consent screen describing the data being shared.
Once the user accepts, Persona redeems the Share Token against the Inquiry.
If the Source Inquiry has all the data the Destination Inquiry Template requires, the Inquiry completes automatically.
If any data is missing, the Inquiry dynamically collects it from the end user as a fallback.

Client-side Share Token redemption flow within an Inquiry — Redeem a Share Token via Inquiry (Client-Side)

Examples

Hosted Flow

Embedded Flow

Inlined Flow

iOS SDK

Android SDK

React Native SDK

Append share-token and inquiry-template-id to the hosted flow URL to create and redeem the Share Token in a new Inquiry.

https://withpersona.com/verify?share-token=cnst_ABC123&inquiry-template-id=itmpl_ABC123

To redeem against an existing Inquiry, append share-token and inquiry-id instead.

https://withpersona.com/verify?share-token=cnst_ABC123&inquiry-id=inq_XYZ789

Mapping Fields During Redemption

When a Share Token is redeemed, the source object’s fields are imported into the destination object. By default, Persona matches source fields to destination fields by name. When the two organizations use different field names for the same data (e.g., source salary vs. destination income), Destination Organizations can provide field mappings during redemption to explicitly pair source field names with destination field names.

Field mappings are optional and only apply to fields that don’t already match by name. Providing them can help prevent stuck Inquiries when redeeming into an Inquiry, and can improve hydrated coverage when redeeming into a Transaction or Account.

Field mappings support dot notation for nested destination fields — for example, mapping a flat source field name_first to a nested destination field name.first.

Mapping Fields via API

Pass field-mappings under meta when calling the /redeem endpoint. Each mapping requires a source-field-name and destination-field-name.

Redeem a Share Token with Field Mappings

$ curl -X POST https://api.withpersona.com/api/v1/connect/share-tokens/cnst_ABC123/redeem \
>   -H "Authorization: Bearer <token>" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "data": {
>       "attributes": {
>         "destination-id": "inq_XYZ789"
>       }
>     },
>     "meta": {
>       "field-mappings": [
>         {
>           "source-field-name": "salary",
>           "destination-field-name": "income"
>         }
>       ]
>     }
>   }'

Mapping Fields via Dashboard

When redeeming a Share Token from the Dashboard, open the Field mappings (optional) tab in the Redeem Share Token modal. Add a row for each source-to-destination field pair, then click Redeem Share Token.

Persona Dashboard Redeem Share Token modal with the Field mappings tab open, showing one source-to-destination field mapping row and an Add mapping button — Map fields when redeeming a Share Token via the Dashboard

Once the Share Token is redeemed, the destination object (Inquiry, Transaction, or Account) will have the end user’s shared data attached — and, in the case of an Inquiry destination, any verification results from the run. This gives the Destination Organization full access to the end user’s KYC data. The Destination Organization can view the destination object in their Dashboard, as well as fetch it via API.

Redeeming Logic

Share Tokens can have the following statuses:

created: Share Token is new, and the Destination Organization can redeem it
pending: Share Token redemption is currently processing
redeemed: Share Token redemption has finished processing
expired: Share Token is expired and unable to be redeemed
failed: Share Token redemption could not complete and is not retryable

When the Destination Is an Inquiry

Redeeming a Share Token into an Inquiry automatically runs that Inquiry against the Destination Organization’s Inquiry Template, executing any Verifications and Reports it requires.

Once redeemed, the destination Inquiry has either reached a terminal status (e.g., completed) or gotten stuck (created or pending). It reaches a terminal status if the source Inquiry has all the fields the destination Inquiry requires (e.g., PII, images, documents); it gets stuck if any required fields are missing — for example, the destination Inquiry Template requires a Proof of Address document but the source Inquiry only collected Government ID and Selfie. The specific terminal status depends on the Destination Organization’s Inquiry Template, and the Destination Organization can fetch the destination Inquiry to check its status.

To prevent stuck Inquiries, align the source and destination Inquiry Templates as closely as possible. When Inquiries do get stuck, Persona recommends providing end users with a fallback flow: users can resume stuck Inquiries, or complete a new Inquiry altogether. Client-side redemption sidesteps stuck Inquiries entirely — end users are already in the flow, so any missing fields are collected dynamically.

When the Destination Is a Transaction or Account

Redeeming a Share Token into a Transaction or Account hydrates the destination object with data from the source object. There is no automated run, no Verifications, and no terminal-status concept — the redemption simply populates the destination object’s fields.

Any fields the source object does not have are left unset on the destination object. To maximize hydrated coverage, align the source and destination schemas as closely as possible.

Redeeming Latency

Share Token redemptions are asynchronous. Completion time depends on the destination type. Inquiry destinations take the longest because they run Verifications and Reports — a template with many Verification types will take longer than one with fewer. Transaction and Account destinations only hydrate fields, so they typically complete much faster.

Destination Organizations receive the following events related to Share Tokens. These events can be used to trigger Webhooks and Workflows.

connect/share-token.inbound-created — Occurs in the Destination Organization when a Source Organization creates a Share Token for it. Use this event to automatically trigger Share Token redemption without polling or manual exchange.
connect/share-token.inbound-redeemed — Occurs in the Destination Organization when its Share Token redemption has finished. At this point, status is redeemed and the destination Inquiry is ready to fetch to check its status.

Supported Destination Types