Important Notice:

• All request and response parameters are strictly subject to the official API documentation.
• The API response may contain fields not defined in the documentation. These fields are for internal debugging purposes only and are not guaranteed to be stable or compatible. Do not rely on these fields in production environments. ZOLOZ reserves the right to modify or remove these fields at any time without prior notice.

Overview

• API URL: POST /api/v1/zoloz/sharetoken/create
• API Description: The Donor (data provider) generates a one-time ShareToken for a specified Recipient (data receiver), authorizing the Recipient to reuse the KYC data of the specified applicant in the Reusable RealID flow.

Notes:

• Before calling this API, ensure that the following conditions are met:

• The Donor has the ShareToken creation capability enabled.
• An effective data sharing partnership has been established between the Donor and the Recipient.
• The specified applicant has shareable document and face data attached.

• The ShareToken is valid for 20 minutes and can be used only once. It can only be used by the Recipient specified at creation.
• The ShareToken is an opaque string. Do not parse or modify it. The Donor should deliver the ShareToken to the Recipient through a secure server-side channel.
• For repeated requests with the same Donor, bizId, applicantId, and recipientClientId, if the original ShareToken is still valid and has not been used, the API returns the same ShareToken, meaning it is idempotent.

Request Parameters

Response Parameters

ShareToken Usage Rules

• The ShareToken is valid for 20 minutes after successful creation. The actual expiration time is determined by expireTime.
• The ShareToken can only be used by the Recipient specified by recipientClientId at creation.
• The ShareToken is immediately consumed once /api/v1/zoloz/realid/reusable/initialize is successfully called. It cannot be reused afterward.
• If the ShareToken has expired, has been used, or the Recipient does not match, subsequent data reuse requests will fail.
• The Donor should deliver the ShareToken to the Recipient through a secure server-side channel before expireTime.

Result

For different request results, different actions will be performed. See the following for details:

• When result.resultCode = SUCCESS: The ShareToken was created successfully. Use the returned shareToken and expireTime for subsequent data reuse flows.
• When result.resultStatus = F: The ShareToken creation failed. Check the returned resultCode and resultMessage to identify issues with request parameters, applicant data, or partnership status.

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-specific error codes

The error codes specific to the Reusable RealID sharetoken create API are listed in the table below.

Sample

Request Sample

{
    "bizId": "2026053000014", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "recipientClientId": "2188499706886568", 
    "sceneCode": "KYC_REUSE"
}

Response Sample

Successful Response

{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "shareToken": "st_550e8400-e29b-41d4-a716-446655440000",
  "expireTime": 1784161200000
}

Failure Response

{
  "result": {
    "resultStatus": "F",
    "resultCode": "APPLICANT_NOT_FOUND",
    "resultMessage": "The applicant does not exist or does not belong to the current donor."
  }
}