Create a KYC request

Creates a KYC request.

The customer is redirected to the kycGatherer link. After the customer completes the KYC process, they are redirected back to the redirectUrl link.

Corresponding webhooks, such as: KYC document accepted and KYC document rejected, are sent to the subscribers.

When the complete list of documents is received and accepted, the KYC request fulfilled webhook is sent to subscribers.

If a credit-file-proof request is successful, it returns a decision value of single-source or dual-source. The corresponding identity-proof and address-proof documents are not requested.

SecurityAPI Key: SecretApiKey or HTTP: JWT
Request Body schema: application/json

KYC request resource.

string (CustomerId) <= 50 characters

ID of the customer resource.

Array of objects (KycRequestDocument) non-empty

Documents to request from the customer.

string or null <uri>

URL where the customer is redirected when a KYC document upload is complete. When the customer is redirected, Rebilly appends an info query parameter that has one of the following values:

  • back: Customer clicked the back to website link.
  • token_expired: Customer's token expired.
  • success: Customer uploaded KYC documents that have been analyzed.
  • manual: Customer uploaded KYC documents that require a manual review. This is because the analyzer rejected the documents or could not process them.
  • partial: Some of the customer's KYC documents have been analyzed, but other documents have not. For example, this may occur when a proof of address document is analyzed but proof of ID is not.


string or null

Reason for uploading.

integer [ 1 .. 2 ]
Default: 2

Tolerance level setting for document matches. The value of 1 is more tolerant and 2 is strict.

string <date-time>

Date and time when the request expires. The default value is one hour in the future.

Request samples

In the sandbox environment, to mark a credit-file-proof KYC document as accepted, pass the customer's first name to the accept field. If an incorrect first name is passed, the document is rejected.

{ "customerId": "123_456789", "redirectUrl": "", "documents": [ ], "reason": "registration" }


KYC request created.


Unauthorized access. Invalid credentials used.


Access forbidden.


Invalid data sent.

Response samples
{ "id": "kyc_req_0YV7JMJ3DBCGRBR7K9D4HVGPP5", "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF", "documents": [ ], "status": "gathering", "redirectUrl": "", "reason": "spend limit", "matchLevel": 2, "revision": 0, "expirationTime": "2019-08-24T14:15:22Z", "createdTime": "2019-08-24T14:15:22Z", "updatedTime": "2019-08-24T14:15:22Z", "_links": [ ], "_embedded": { "documents": [ ] } }