> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.withpersona.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server. # Redeeming Share Tokens Destination Organizations can redeem Share Tokens from Source Organizations to import KYC/KYB data and, as needed, run additional Verifications and Reports. Customers can redeem Share Tokens via API, Dashboard, Workflows, or Inquiries (client-side). > **Note** > > Share Tokens can only be redeemed between matching environment types: Sandbox > to Sandbox and Production to Production. --- ## Redeem Modes When redeeming Share Tokens, Destination Organizations can either clone existing KYC/KYB results or hydrate another object with the shared data. Customers that clone existing results can still run additional Verifications and Reports as needed. ### Clone Objects Use cloning when you want a copy of the existing KYC/KYB results—for example, for KYC Reliance or auditing. You can clone Inquiries and Verifications, and you have the option to run additional Verifications and Reports as needed. * **Inquiry:** Copies the Inquiry and its related Verifications. * **Verification:** Copies an individual Verification. * **Additional checks:** After cloning, you can run additional Verifications or Reports as needed. > **Note** > > Persona currently supports cloning Government ID, Selfie, Database, Generic > Document, Email Address, and Phone Number Verifications. ### Hydrate Objects Use hydration to import fields into a new or existing Account, Inquiry, or Transaction. Choose this mode when you want to run your own Verifications and Reports through an Inquiry or Transaction, or when you need a direct copy of the shared PII fields. Hydration does not copy Verifications or Reports from the source object. * **Source and destination types:** Accounts, Inquiries, and Transactions can hydrate one another in any combination. * **Inquiry destination:** Persona runs the Inquiry using the Destination Organization's Inquiry Template, including its configured Verifications and Reports. If required information is missing, the Inquiry may remain `created` or `pending`. * **Account or Transaction destination:** Persona copies the source fields into the destination object. You can use Workflows to run additional Verifications, Reports, or other logic. --- ## Redeeming Share Tokens via API Destination Organizations can use the Connect API to redeem Share Tokens. Omit `destination-id` to clone the source object. Provide `destination-id` to hydrate that destination object. ### Clone via API To clone an Inquiry or Verification, call the `/redeem` endpoint without a `destination-id`. You can omit the request body or send empty `attributes`. **`Clone an Inquiry`** ```bash title="Clone an Inquiry" curl -X POST https://api.withpersona.com/api/v1/connect/share-tokens/cnst_ABC123/redeem \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": { "attributes": {} } }' ``` Persona returns `202 Accepted` with the Share Token in `pending` status while it creates the new object. The new object's ID is available after cloning finishes. **`Pending Share Token`** ```json title="Pending Share Token" { "data": { "type": "connect/share-token", "id": "cnst_ABC123", "attributes": { "status": "pending", "direction": "inbound", "created-at": "2023-08-17T23:18:13.000Z", "updated-at": "2023-08-17T23:25:00.000Z", "pending-at": "2023-08-17T23:25:00.000Z", "redeemed-at": null, "expires-at": null, "failed-at": null, "failure-reason": null, "redeem-mode": "clone" }, "relationships": { "connection": { "data": { "type": "connect/connection", "id": "cxn_ABC123" } }, "destination": { "data": null } } } } ``` ### Hydrate via API To hydrate an Inquiry, Transaction, or Account, provide its ID as `destination-id`. When hydrating an Inquiry, the `/redeem` endpoint also automatically runs that Inquiry in the Destination Organization's Persona environment. > **Note** > > 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`** ```bash title="Redeem a Share Token" curl -X POST https://api.withpersona.com/api/v1/connect/share-tokens/cnst_ABC123/redeem \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": { "attributes": { "destination-id": "inq_XYZ789" } } }' ``` Persona returns `202 Accepted` with the Share Token in `pending` status while it imports the source data. **`Pending Share Token`** ```json title="Pending Share Token" { "data": { "type": "connect/share-token", "id": "cnst_ABC123", "attributes": { "status": "pending", "direction": "inbound", "created-at": "2023-08-17T23:18:13.000Z", "updated-at": "2023-08-17T23:25:00.000Z", "pending-at": "2023-08-17T23:25:00.000Z", "redeemed-at": null, "expires-at": null, "failed-at": null, "failure-reason": null, "redeem-mode": "hydrate" }, "relationships": { "connection": { "data": { "type": "connect/connection", "id": "cxn_ABC123" } }, "destination": { "data": { "type": "inquiry", "id": "inq_XYZ789" } } } } } ``` --- ## Redeeming Share Tokens via Dashboard 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. Choose whether to clone or hydrate when redeeming the Share Token. To clone, select the clone option and Persona creates a copy of the source object. To hydrate, select a destination object type and the corresponding Inquiry Template, Transaction Type, or Account Type. ![Persona Dashboard UI for redeeming a Share Token](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/connect-redeem-share-token-dashboard.png) --- ## Redeeming Share Tokens via Workflows Destination Organizations can use [Workflows](../workflows) to automate Share Token redemption. In the **Redeem Share Token** action, leave the destination blank to clone the source object, or provide a destination object to hydrate it. For example, the Destination Organization can use a Workflow to automatically redeem a Share Token upon creation by the Source Organization. ![Workflow diagram for automatic Share Token redemption](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/connect-redeem-share-token-workflow.png) --- ## Redeeming Share Tokens via Inquiry (Client-Side) 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. > **Note** > > 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: 1. The end user sees a consent screen describing the data being shared. 2. Once the user accepts, Persona redeems the Share Token against the Inquiry. 3. If the Source Inquiry has all the data the Destination Inquiry Template requires, the Inquiry completes automatically. 4. 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](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/connect-client-side.png) ### Examples #### Hosted Flow Append `share-token` and `inquiry-template-id` to the hosted flow URL to create and redeem the Share Token in a new Inquiry. ```text https://inquiry.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. ```text https://inquiry.withpersona.com/verify?share-token=cnst_ABC123&inquiry-id=inq_XYZ789 ``` #### Embedded Flow Pass the Share Token via the `shareToken` parameter when instantiating `Persona.Client` from the [`persona`](https://www.npmjs.com/package/persona) JavaScript SDK. ```javascript import Persona from 'persona'; const client = new Persona.Client({ templateId: 'itmpl_ABC123', environmentId: 'env_ABC123', shareToken: 'cnst_ABC123', onReady: () => client.open(), onComplete: ({ inquiryId, status, fields }) => { console.log('Inquiry ' + inquiryId + ' completed with status ' + status); }, }); ``` To redeem against an existing Inquiry, pass `inquiryId` instead of `templateId`. #### Inlined Flow Pass the Share Token via the `shareToken` parameter when setting up the inlined flow with the [`persona`](https://www.npmjs.com/package/persona) JavaScript SDK. The same parameter is supported in the [`persona-react`](https://www.npmjs.com/package/persona-react) and [`persona-vue`](https://www.npmjs.com/package/persona-vue) wrappers. ```javascript Persona.setupEvents(containerId, { templateId: 'itmpl_ABC123', environmentId: 'env_ABC123', shareToken: 'cnst_ABC123', onComplete: ({ inquiryId, status, fields }) => { console.log('Inquiry ' + inquiryId + ' completed with status ' + status); }, }); Persona.setupIframe(personaIframe, containerId, 'inline', { templateId: 'itmpl_ABC123', shareToken: 'cnst_ABC123', }); ``` To redeem against an existing Inquiry, pass `inquiryId` instead of `templateId`. #### iOS SDK Pass the Share Token via the `shareToken` builder method on `InquiryBuilder` or `InquiryTemplateBuilder`. Available in persona-ios v2.46.0 and later. ```swift let inquiry = Inquiry.from(templateId: "itmpl_ABC123", delegate: delegate) .shareToken("cnst_ABC123") .build() ``` To redeem against an existing Inquiry, use `Inquiry.from(inquiryId:,delegate:)` instead. #### Android SDK Pass the Share Token via the `shareToken` builder method. Available in persona-android v2.40.0 and later. Supported on `Inquiry.fromTemplate(...)`, `Inquiry.fromTemplateVersion(...)`, `Inquiry.fromInquiry(...)`, and `Inquiry.fromOneTimeLinkCode(...)`. ```kotlin val inquiry = Inquiry.fromTemplate("itmpl_ABC123") .shareToken("cnst_ABC123") .build() ``` To redeem against an existing Inquiry, use `Inquiry.fromInquiry("inq_EXAMPLE")` instead. #### React Native SDK Pass the Share Token via the `shareToken` builder method on the builder returned by `Inquiry.fromTemplate(...)`, `Inquiry.fromTemplateVersion(...)`, or `Inquiry.fromInquiry(...)`. ```ts import { Environment, Inquiry } from 'react-native-persona'; Inquiry.fromTemplate('itmpl_ABC123') .environment(Environment.SANDBOX) .shareToken('cnst_ABC123') .build() .start(); ``` To redeem against an existing Inquiry, use `Inquiry.fromInquiry('inq_EXAMPLE')` instead. --- ## Mapping Fields During Redemption When a Share Token hydrates an existing destination, 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 hydration. They are not used when cloning. Persona applies them to source fields that do not already match destination fields by name. Providing them can help prevent [stuck Inquiries](#hydrating-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`** ```bash title="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 " \ -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](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/connect-redeem-share-token-field-mappings-dashboard.png) --- ## Viewing Redeemed Share Tokens Once the Share Token is `redeemed`, the cloned or hydrated object is ready. The Destination Organization can view it in the Dashboard or retrieve it via API. --- ## Redeeming Logic ### Share Token Statuses Share Tokens can have the following statuses: * `created`: Share Token is new, and the Destination Organization can redeem it * `ready`: Persona has prefetched and cached the source data snapshot, 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 ### Hydrating Inquiries 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](#redeeming-share-tokens-via-inquiry-client-side) sidesteps stuck Inquiries entirely — end users are already in the flow, so any missing fields are collected dynamically. ### Hydrating Transactions and Accounts Redeeming a Share Token into a Transaction or Account hydrates the destination object with data from the source object. Customers often trigger Workflows upon Share Token redemption to run additional Verifications, Reports, or logic as needed. 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, including cloning, happen in the background. Hydrating an Inquiry usually takes the longest because it runs Verifications and Reports. Hydrating a Transaction or Account only copies fields, so it typically finishes much faster, though running additional Verifications and Reports will add latency. --- ## Inbound Share Token Events Destination Organizations receive the following events related to Share Tokens. These events can be used to trigger [Webhooks](/webhooks) and [Workflows](/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.ready` — Occurs in the Destination Organization when the source data snapshot for the Share Token is ready, meaning Persona has prefetched and cached the source data. At this point, `status` is `ready`. * `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 cloned or hydrated object is ready.