attach

2026-08-26 08:47

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/applicant/attach
API Description: This API is used to attach a successfully completed RealID transaction data to a specified applicant. After successful attachment, the applicant can use the corresponding document and face data in KYC data sharing scenarios.

Notes:

Both the specified applicant and the RealID transaction must belong to the current merchant.
The RealID transaction must have been successfully completed, and the product type must be RealID.
This API supports idempotent calls with the same applicantId and transactionId. Repeated calls will not result in duplicate data.
When attaching data of the same document type, the document data from the new transaction will overwrite the existing document data of the same type for the applicant. Document data of other types will be appended to the applicant.
The face in the new transaction must belong to the same person as the applicant's existing face. If the verification passes, the newly attached face result will be used. If the verification fails, FACE_MISMATCH is returned.

Request Parameters

Field Name	Data Type	Max Length	Required	Default Value	Description	Example
bizId	String	32	Yes	-	A unique business ID for tracing purposes. For example, the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness checks on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID.	2026053000015
applicantId	String	50	Yes	-	The ZOLOZ applicant ID to which the KYC data will be attached. The applicant must belong to the current merchant.	APHK_a1b2c3d4e5f6
transactionId	String	64	Yes	-	The RealID transaction ID to be attached. The transaction must belong to the current merchant, have been successfully completed, and have the product type RealID.	G000000005FID2020030400000000000157****

Response Parameters

Field Name

Data Type

Always Returned

Description

Example

result

Result

Yes

The API request result, which contains the result status, result code, and result message.

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

The transaction ID for this API call, which can be used for business tracking and troubleshooting.

Note: The system will only return the transactionId after the transaction enters the processing stage. If an error occurs before the transaction begins processing, the system will not return a transactionId. This includes, but is not limited to, the following situations:

Invalid request parameters, such as incorrect input format or missing required parameters.
The request fails to reach the server successfully, such as due to network issues or gateway failures.
The request is denied due to system rate limiting.

G000000005FID2020030400000000000157****

Response Rules

Processing Result	Returned Content
Attachment Successful	Returns `result` with `resultCode=SUCCESS` and the `transactionId` for this API call.
Idempotent Hit	Returns `result` with `resultCode=SUCCESS` and the `transactionId` for this API call. No duplicate document or face data is created.
Attachment Failed	Returns `result` and the `transactionId` for this API call, with the failure reason described by `resultCode` and `resultMessage`. The transaction data is not attached to the applicant.

Data Attachment Rules

Scenario	Processing Result
Repeated call with the same `applicantId` and `transactionId`	Returns idempotent success. No duplicate data is created.
New transaction contains a document of the same type as an existing document for the applicant	The document data from the new transaction overwrites the existing document of the same type.
New transaction contains a document type that the applicant does not yet have	The document data is appended to the applicant.
The face in the new transaction belongs to the same person as the applicant's existing face	The newly attached face result is used.
The face in the new transaction does not belong to the same person as the applicant's existing face	Returns `FACE_MISMATCH`. The transaction data is not attached.

Result

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

When result.resultCode = SUCCESS: The RealID transaction data has been successfully attached to the applicant, or the idempotent request matched an existing attachment result.
When result.resultCode = APPLICANT_NOT_FOUND: The applicant corresponding to the provided applicantId does not exist or does not belong to the current merchant.
When result.resultCode = TRANSACTION_NOT_FOUND: The transaction corresponding to the provided transactionId does not exist or does not belong to the current merchant.
When result.resultStatus = F: The attachment failed. Check the returned resultCode and resultMessage to identify issues with the applicant, transaction status, product type, face consistency, or request parameters.

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 attach API are listed in the table below.

resultCode	resultStatus	Description
SUCCESS	S	The RealID transaction data was attached successfully, or the idempotent request matched an existing attachment result.
APPLICANT_NOT_FOUND	F	The applicant corresponding to the provided `applicantId` does not exist or does not belong to the current merchant.
TRANSACTION_NOT_FOUND	F	The transaction corresponding to the provided `transactionId` does not exist or does not belong to the current merchant.
TRANSACTION_NOT_SUCCESS	F	The specified RealID transaction has not been successfully completed and cannot be attached to the applicant.
TRANSACTION_NOT_REALID	F	The specified transaction is not a RealID product transaction.
FACE_MISMATCH	F	The face in the new transaction does not belong to the same person as the applicant's existing face. The transaction data was not attached.
INVALID_ARGUMENT	F	Invalid input parameters. Possible causes include missing required parameters, field length exceeded, etc. For detailed error information, check the returned `resultMessage`.
SYSTEM_ERROR	F	Internal system error. For error details, check the returned `resultMessage`.

Sample

Request Sample

copy
{
    "bizId": "2026053000015", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "transactionId": "G000000005FID20200304000000000001570702"
}

Response Sample

Successful Response

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G000000005FID20200304000000000001570703"
}

Failure Response

copy
{
    "result": {
        "resultStatus": "F", 
        "resultCode": "TRANSACTION_NOT_SUCCESS", 
        "resultMessage": "The RealID transaction is not successful."
    }, 
    "transactionId": "G000000005FID20200304000000000001570704"
}