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).

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.

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.

$
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": {}
>
    }
>
  }'

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.

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

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.

$
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"
>
      }
>
    }
>
  }'

Persona returns 202 Accepted with the Share Token in pending status while it imports the source data.

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

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.

Redeeming Share Tokens via Workflows

Destination Organizations can use 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.

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.

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.

Examples

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

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

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 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.

$
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.

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
• 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 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 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 cloned or hydrated object is ready.