Reusable KYC integration

Reusable KYC lets one account share an existing verified Profile with a partner account.
The recipient checks the donor's stored data against its own verification Level and copies
eligible data into a Profile in its account. The reuse response is synchronous and returns
the recipient Profile; no verification Application is created by these endpoints.

Accounts and prerequisites

The donor owns the source Profile. The recipient receives the copied data and pays
for successful reuse. Each account authenticates using its own Bearer access token;
see Authentication.

Before integrating:

• Establish an active partnership in the donor → recipient direction. A partnership
  in the reverse direction does not grant access to this flow.
• Enable Reusable KYC for the recipient account.
• Choose a recipient-owned Level with Document, Face, or both, and no AML step.
• Use a donor Profile that is ACTIVE and has a recorded verification Level.
  It must also contain the records required by the recipient Level.

Ask the recipient to supply its numeric account ID and intended Level ID before the donor
creates a token. The account ID is not an access key, organization ID, or Profile ID.
Level IDs are available under Level Management; see Getting started.
If the partnership or recipient access is not configured, contact your AdvanGuard support
representative with both account IDs, the donor → recipient direction, and the recipient
Level ID. Ask them to confirm the partnership and recipient Reusable KYC access before
starting API integration. The three endpoints below do not configure these prerequisites.

The sharing token is separate from the Bearer access token. The donor creates it for a
specific recipient, and only that recipient can use it. Handle it as a credential:
transfer it through your secure server-to-server channel and pass it unchanged.

1. Donor creates a sharing token

Authenticate as the donor and specify the recipient account. These examples use donor
account 10001 and recipient account 20001. IDs and tokens are illustrative; substitute
your own values.

curl --request POST \
  'https://openapi.advance.ai/v1/individual/reusable_kyc/share_tokens' \
  --header "Authorization: Bearer ${DONOR_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "profileId": "donor-profile-001",
    "forAccountId": 20001,
    "expiresIn": 1200
  }'

HTTP 200:

{
  "shareToken": "<opaque-share-token>",
  "forAccountId": 20001
}

expiresIn is a positive integer in seconds. Omit it or pass null to use the
service-configured default, which is 1200 seconds unless overridden. Pass it explicitly
when your integration needs a specific lifetime.

Creating a token validates the recipient account and partnership. It does not establish
that the source Profile exists, is active, or meets the recipient's Level requirements.
Those checks happen during preview and reuse.

2. Recipient checks eligibility (optional)

Authenticate as the recipient. Use its Level ID and a stable recipient-side user identifier.
Set SHARE_TOKEN to the exact value returned in step 1.

curl --include --request POST \
  'https://openapi.advance.ai/v1/individual/reusable_kyc/reuse/preview' \
  --header "Authorization: Bearer ${RECIPIENT_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data "{
    \"shareToken\": \"${SHARE_TOKEN}\",
    \"levelId\": \"recipient-level-001\",
    \"externalUserId\": \"customer-001\"
  }"

Success is HTTP 200 with an empty body, not {} or a Profile object. Do not call a
JSON parser on the successful preview response.

Preview uses the same eligibility checks as reuse without saving a Profile, charging for
reuse, or consuming the token. It does not reserve anything. Reuse checks eligibility again,
so a successful preview can be followed by a failure if the token expires, another call
consumes it, or the Profile, partnership, permissions, or Level settings change.

Preview still runs account and product access checks. It can return 402 for the calling
account's balance or test quota, or 403 for the recipient's product access, balance, or quota,
even though preview itself does not charge for reuse. See Error handling.

externalUserId is accepted for parity with the reuse request. Preview does not look up,
create, reserve, or check whether the recipient Profile can be updated.

3. Recipient performs reuse

Call reuse with the same recipient credentials and request fields:

curl --request POST \
  'https://openapi.advance.ai/v1/individual/reusable_kyc/reuse' \
  --header "Authorization: Bearer ${RECIPIENT_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data "{
    \"shareToken\": \"${SHARE_TOKEN}\",
    \"levelId\": \"recipient-level-001\",
    \"externalUserId\": \"customer-001\"
  }"

Example HTTP 200 response for a Document-and-Face Level:

{
  "profileId": "recipient-profile-001",
  "accountId": 10001,
  "externalUserId": "customer-001",
  "status": "ACTIVE",
  "info": {
    "firstName": "Alex",
    "lastName": "Example",
    "dob": "1990-01-01",
    "nationality": "IDN",
    "country": "IDN",
    "documentNumber": "EXAMPLE123"
  },
  "idDocs": ["recipient-doc-001", "recipient-selfie-001"],
  "createdAt": "2026-09-23T08:00:00Z"
}

Store the returned profileId and externalUserId as the recipient's identifiers.
idDocs contains document IDs, not full document records. info contains the
recipient Profile's verified identity information; unavailable fields are omitted.
A newly created Face-only Profile can omit info entirely.

How the recipient Level affects reuse

Available donor fixed information is copied in all three cases. Face eligibility uses the
stored SELFIE record; reuse does not run a new liveness capture or face comparison.

For a Document Level, donor documents must cover every applicable country/type requirement
in the recipient's document scope. A two-sided requirement needs at least two file entries.
For example, if the scope requires an IDN passport and an SGP national ID, the donor must
have both; one document does not satisfy the other country/type requirement.
The matching documents are checked against enabled age, expiration/remaining-validity, and
nationality rules. Missing inputs required by an enabled check can make the Profile ineligible.

New and existing recipient Profiles

A non-blank externalUserId selects the visible Profile with that identifier in the recipient
account. If none exists, reuse creates one. Omitting it, passing null, or passing a blank
value generates an identifier for the new Profile.

Reuse binds the selected Profile to the recipient Level and applies these update rules:

Addresses follow the separate address rule above even when shown under fixedInfo or
verifiedInfo in Profile responses. They are excluded from the information-field replacement:
Document reuse appends donor addresses and keeps existing addresses; Face-only reuse leaves
all recipient addresses unchanged, including addresses shown under fixedInfo.

Copied documents and files receive recipient-owned identifiers. Do not use donor document
IDs to access the copied files. Where your account has Profile query access, retrieve
GET /v1/individual/profiles/{profileId} with the returned recipient profileId to see full
records and available files download URLs.

For example, suppose a recipient already has a passport, a national ID, a selfie and an
address. A Document-only reuse of a donor passport and address replaces the recipient's
passport, retains its national ID and selfie, and adds a new address. If the donor has a
verifiedInfo block, its non-address fields replace the recipient's corresponding fields; a donor null
middleName clears the recipient's old middle name.

The selected recipient Profile's lifecycle state determines the resulting status:

Check the returned status: HTTP 200 means reuse completed, not necessarily that the
recipient Profile is active. Deleted Profiles are not selected as visible destinations;
do not use reuse as a deleted-Profile recovery operation.

The response describes the resulting Profile, so idDocs can include retained records
and createdAt is the original creation time when updating an existing Profile.

Failures and retries

Errors have this shape; requestId is included when available:

{
  "error": {
    "type": "invalid_share_token",
    "message": "share token already consumed"
  },
  "requestId": "req-example"
}

Branch on HTTP status and error.type, not the diagnostic message. The preview and reuse
API reference pages list the eligibility error types. Checks stop at the first failure;
resolving it can expose a different failure on the next attempt.

A token is consumed by successful reuse. Reusing a consumed token returns
invalid_share_token; it does not return the earlier success result. Eligibility failures
do not consume the token, although it may expire before the next attempt.

Send at most one reuse request at a time for a token. A stable externalUserId helps locate
the destination Profile but does not make repeated writes or fresh-token attempts a
safe replay of the first request. Where Profile query access is available, resolve the
recipient Profile using GET /v1/individual/profiles?externalUserId=.... Otherwise, retain
your request details and ask support to reconcile the outcome before requesting another token.