Redeeming Share Tokens

Closed Beta

Connect is in Closed Beta. The information in this guide is subject to change during the beta period. Please reach out to your Persona account team or connect@withpersona.com to request access or additional information.

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

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

The /redeem endpoint’s destination-id requires an Inquiry ID. To get an Inquiry ID, you can create an Inquiry before redeeming 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_ABC123"
>       }
>     }
>   }'

Share Token

1 {
2   "data": {
3     "type": "connect/share-token",
4     "id": "cnst_ABC123",
5     "attributes": {
6       "status": "redeemed",
7       "source-id": "act_DEF456",
8       "created-at": "2023-08-17T23:18:13.000Z",
9       "updated-at": "2023-08-17T23:18:13.000Z",
10       "expires-at": "2023-08-18T23:18:13.000Z"
11     }
12   }
13 }

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

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’re interested in using Workflows to automate Share Token creation, please reach out to your Persona account team or connect@withpersona.com for additional information.

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 view the destination Inquiry in their dashboard, as well as fetch it via API.

Redeeming Logic

Inquiry Outcomes

If the source Inquiry has all of the fields required by the Destination Organization’s Inquiry Template, the destination Inquiry will automatically reach a terminal status (e.g., completed or failed). The specific terminal status depends on the Destination Organization’s Inquiry Template. Alternatively, if the destination Inquiry requires any fields that the source Inquiry does not have, the destination Inquiry will get stuck with status: created or status: pending.

For example, if the destination Inquiry Template requires a Proof of Address document, but the source Inquiry only collected Government ID and Selfie – the Inquiry will get stuck. See below for details on how to handle stuck Inquiries.

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 (e.g., having them resume the stuck Inquiry, or falling back to a new Inquiry).

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.

Share Tokens must have status: created to redeem. Redeemed Share Tokens will move to status: pending while the redemption is in process, and status: redeemed after the redemption completes.

Closed Beta