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. Redeeming a Share Token automatically runs an Inquiry in the Destination Organization’s Persona environment. This process verifies the end user’s data against the Destination Organization’s requirements, running any Verifications and Reports required by the Inquiry.

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

Destination Organizations can use the Connect API to redeem Share Tokens. The /redeem endpoint automatically runs the Inquiry (set in the destination-id) in the Destination Organization’s Persona environment.

The /redeem endpoint’s destination-id requires an Inquiry ID. Redeeming the Share Token will automatically run that Inquiry. To get an Inquiry ID, you can create an Inquiry. The inquiry-template-id used to create the Inquiry determines which Inquiry Template to use when using the /redeem endpoint 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": "pending",
7       "source-id": "inq_ABC123",
8       "created-at": "2025-10-14T22:36:51.907Z",
9       "updated-at": "2025-10-14T22:39:23.224Z",
10       "pending-at": "2025-10-14T22:39:23.213Z",
11       "redeemed-at": null,
12       "expires-at": null
13     },
14     "relationships": {
15       "destination": {
16         "data": { "type": "inquiry", "id": "inq_XYZ789" }
17       }
18     }
19   }
20 }

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 an Inquiry Template.

connect-redeem-share-token — Redeem a Share Token via the Dashboard

Destination Organizations can use Workflows to automate Share Token redemption. 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 developement work.

If you have an existing Inquiry integration, you can redeem Share Tokens client-side. To do this, you can add the Redeem Share Token Action Step to your Inquiry Template. When your end user is inside the Inquiry, Persona will redeem the Share Token and dyanmically collect any additionally-required data (if any). This can be advantageous if you have an existing Inquiry integration, or your Inquiry Template is complex and will typically require end users provide additional data. To do this, you will pass the Share Token ID into the Inquiry upon instantiation, and the Inquiry itself will handle Share Token redemption and fallback logic.

Once the Share Token is redeemed, the destination Inquiry will have the end user’s data and verification results attached. This gives the Destination Organization full access to end user’s KYC data. The Destination Organization can view the destination Inquiry 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

Destination Inquiry Statuses

Once the Share Token is redeemed, the destination Inquiry will have either reached a terminal status (e.g., completed), or gotten stuck (created or pending). The destination Inquiry will reach a terminal status if the source Inquiry has all of the fields that the destination Inquiry requires (e.g., PII, images, documents). Note that the specific terminal status depends on the Destination Organization’s Inquiry Template.

The destination Inquiry will get stuck with status created or pending if the destination Inquiry requires any fields that the source Inquiry does not have. For example, if the destination Inquiry Template requires a Proof of Address document, but the source Inquiry only collected Government ID and Selfie – the destination Inquiry will get stuck. See below for details on handling stuck Inquiries.

The Destination Organization can fetch the destination Inquiry to check its status once the Share Token has finished processing and is redeemed.

Stuck Inquiries

Preventing stuck Inquiries requires aligning the Source Organziation’s and Destination Organization’s Inquiry Templates as closely as possible. For example, if the Destination Organization’s Inquiry Template collects a Proof of Address document, the Source Organization’s Inquiry Template will also need to collect that document for destination Inquiries to automatically reach a terminal status.

To handle cases where Inquiries do get stuck, Persona recommends providing end users with a fallback flow: users can resume stuck Inquiries, or complete a new Inquiry altogether.

Redeeming Latency

Share Token redemptions are asynchronous. Completion time depends on the Destination Organization’s Inquiry Template. A simple example is that an Inquiry Template with many Verification types will take longer to run Inquiries than a template with fewer.

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.