Rebilly API Docs

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.

SecuritySecretApiKey or JWT

Request

Request Body schema: application/json

KYC request resource.

customerId

required

string (CustomerId) <= 50 characters

Customer resource ID.

required

Array of objects (KycRequestDocuments)

Documents to request from the customer.

Array

type required	string Type of document to request from the customer. Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
subtypes	Array of strings or null (KycDocumentSubtypes) Permitted document subtype. Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 16 more
maxAttempts	integer [ 0 .. 100 ] Default: 3 Total number of allowed document upload attempts. Use `0` to allow unlimited upload attempts.
faceProofRequired	boolean Specifies if the customer must upload a photo of their face (selfie) that matches a provided KYC document.

redirectUrl

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

Example: https://example.com?info=success.

reason

string

Reason for uploading.

matchLevel

integer [ 1 .. 2 ]

Default: 2

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

expirationTime

string <date-time>

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

Responses

201

KYC request created.

Response Headers
Location	string <uri> Location of the related resource. Example: "https://api.rebilly.com/example"

Response Schema: application/json

customerId

required

string (CustomerId) <= 50 characters

Customer resource ID.

required

Array of objects (KycRequestDocuments)

Documents to request from the customer.

Array

type required	string Type of document to request from the customer. Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
subtypes	Array of strings or null (KycDocumentSubtypes) Permitted document subtype. Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 16 more
maxAttempts	integer [ 0 .. 100 ] Default: 3 Total number of allowed document upload attempts. Use `0` to allow unlimited upload attempts.
faceProofRequired	boolean Specifies if the customer must upload a photo of their face (selfie) that matches a provided KYC document.

string <= 50 characters

Unique resource ID. Defaults to UUID v4.

status

string

Status of the request.

Enum:	Description
gathering	No documents have been provided yet. This is a temporary state.
attempted	At least one document has been provided but none were assigned the `accepted` status. This is a temporary state.
partial	At least one requested document has the `accepted` status, but not all requested documents have been assigned the `accepted` status. This is a temporary state.
pending-review	At least one requested document has the `pending` status, and no requested documents have been assigned the `accepted` status. This is a temporary state, until the document is reviewed, or another `accepted` document is provided.
fulfilled	All requested documents are provided and have been assigned the `accepted` status. This is a permanent state.
failed	At least one requested document has exhausted all attempts, and has not been assigned a `accepted`, `pending`, or `in-progress` status. This is a permanent state.
abandoned	One or more documents provided but the request expired. This is a permanent state.
expired	No documents were provided and the request expired. This is a permanent state.

redirectUrl

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

Example: https://example.com?info=success.

reason

string

Reason for uploading.

matchLevel

integer [ 1 .. 2 ]

Default: 2

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

revision

integer

Number of times the KYC request data has been modified.

Use this value when analyzing webhook data to determine if a change must take precedence over the current representation.

expirationTime

string <date-time>

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

createdTime

string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime

string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

Array of objects