logo

KYC Documents

Request KYC documents from customers using the KYC request API which generates a signed link to the KYC document gatherer. The types of documents to request:

  • identity-proof
  • address-proof
  • purchase-proof
  • funds-proof
  • credit-file-proof

In the case that a credit-file-proof is requested in combination with identity-proof and address-proof, the credit-file-proof is attempted first. If it is successful in validating the identity and address, then the KYC request is considered instantly fulfilled. If it is not, or if you the credit-file-proof isn't requested, then redirect your customer to the KYC document gatherer to collect their KYC documents. Rebilly parses and analyzes the documents and accepts or rejects them according to a configurable scoring algorithm. When all of the document types in the KYC request are accepted, the status is considered fulfilled and the KYC request fulfilled webhook will be triggered. If a document is accepted while unreviewed documents of the same type exist, the unreviewed documents will be archived and the archived webhook will be triggered.

Retrieve a list of KYC documents

Retrieve a list of KYC documents.

SecurityCustomerJWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

Responses
200

A list of KYC documents was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

status
required
string

Status of the validation.

Enum: Description
pending

Waiting to be reviewed or analyzed

in-progress

Being analyzed by Rebilly's AI

accepted

Accepted by AI or a human

rejected

Rejected by AI or a human

archived

Archived by Rebilly's AI

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
object (KycDocumentRejection)
type
string (KycDocumentRejectionReasonTypes)
Enum: "document-unreadable" "document-expired" "document-not-matching" "document-duplicate" "document-invalid" "document-not-open" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" … 5 more
message
string

The rejection message.

requestId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

object
score
number <double>

The calculated score that represents the % of confidence that this ID represents the given customer.

object (IdentityMatches)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/kyc-documents
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/kyc-documents?limit=1000&offset=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
[
  • {
    }
]

Create a KYC Document

Create a KYC document.

SecurityCustomerJWT
Request
Request Body schema: application/json

Kyc document resource.

documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
Responses
201

Kyc document was created.

Response Schema: application/json
documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

status
required
string

Status of the validation.

Enum: Description
pending

Waiting to be reviewed or analyzed

in-progress

Being analyzed by Rebilly's AI

accepted

Accepted by AI or a human

rejected

Rejected by AI or a human

archived

Archived by Rebilly's AI

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
object (KycDocumentRejection)
type
string (KycDocumentRejectionReasonTypes)
Enum: "document-unreadable" "document-expired" "document-not-matching" "document-duplicate" "document-invalid" "document-not-open" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" … 5 more
message
string

The rejection message.

requestId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

object
score
number <double>

The calculated score that represents the % of confidence that this ID represents the given customer.

object (IdentityMatches)
containsImage
boolean

Flag that indicates if there is an image that contains a face on it.

isIdentityDocument
boolean

Flag that indicates if this looks like and ID.

isPublishedOnline
boolean

If there is an exact match found online.

firstName
string or null

The customer first name if it was matched, null otherwise.

lastName
string or null

The customer last name if it was matched, null otherwise.

dateOfBirth
string or null <date-time>

The date of birth found on the document, null if not found.

expiryDate
string or null <date-time>
Deprecated

The expiry date found on the document, null if not found.

expirationDate
string or null <date-time>

The expiration date found on the document, null if not found.

issueDate
string or null <date-time>

The issued date found on the document, null if not found.

hasMinimalAge
boolean or null

Checks the minimal age, 21+ for USA and 18+ for all other countries. Null if dateOfBirth could not be determined.

nationality
string or null <= 3 characters

The nationality found on the document, null otherwise.

documentSubtype
string or null

The interpreted subtype of the uploaded document.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/kyc-documents
Request samples
application/json
{
  • "fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileIds": [
    ],
  • "documentType": "identity-proof",
  • "documentSubtype": "passport"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileIds": [
    ],
  • "documentType": "identity-proof",
  • "documentSubtype": "passport",
  • "status": "pending",
  • "rejectionReason": {
    },
  • "requestId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "processedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "documentMatches": {
    }
}

Retrieve a KYC Document

Retrieve a KYC document with specified ID.

SecurityCustomerJWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

KYC document was retrieved successfully.

Response Schema: application/json
documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

status
required
string

Status of the validation.

Enum: Description
pending

Waiting to be reviewed or analyzed

in-progress

Being analyzed by Rebilly's AI

accepted

Accepted by AI or a human

rejected

Rejected by AI or a human

archived

Archived by Rebilly's AI

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
object (KycDocumentRejection)
type
string (KycDocumentRejectionReasonTypes)
Enum: "document-unreadable" "document-expired" "document-not-matching" "document-duplicate" "document-invalid" "document-not-open" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" … 5 more
message
string

The rejection message.

requestId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

object
score
number <double>

The calculated score that represents the % of confidence that this ID represents the given customer.

object (IdentityMatches)
containsImage
boolean

Flag that indicates if there is an image that contains a face on it.

isIdentityDocument
boolean

Flag that indicates if this looks like and ID.

isPublishedOnline
boolean

If there is an exact match found online.

firstName
string or null

The customer first name if it was matched, null otherwise.

lastName
string or null

The customer last name if it was matched, null otherwise.

dateOfBirth
string or null <date-time>

The date of birth found on the document, null if not found.

expiryDate
string or null <date-time>
Deprecated

The expiry date found on the document, null if not found.

expirationDate
string or null <date-time>

The expiration date found on the document, null if not found.

issueDate
string or null <date-time>

The issued date found on the document, null if not found.

hasMinimalAge
boolean or null

Checks the minimal age, 21+ for USA and 18+ for all other countries. Null if dateOfBirth could not be determined.

nationality
string or null <= 3 characters

The nationality found on the document, null otherwise.

documentSubtype
string or null

The interpreted subtype of the uploaded document.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/kyc-documents/{id}
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/kyc-documents/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileIds": [
    ],
  • "documentType": "identity-proof",
  • "documentSubtype": "passport",
  • "status": "pending",
  • "rejectionReason": {
    },
  • "requestId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "processedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "documentMatches": {
    }
}

Update a KYC document

Update a KYC document with predefined ID.

SecurityCustomerJWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

KYC document resource.

documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
Responses
200

KYC document was updated.

Response Schema: application/json
documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

status
required
string

Status of the validation.

Enum: Description
pending

Waiting to be reviewed or analyzed

in-progress

Being analyzed by Rebilly's AI

accepted

Accepted by AI or a human

rejected

Rejected by AI or a human

archived

Archived by Rebilly's AI

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
object (KycDocumentRejection)
type
string (KycDocumentRejectionReasonTypes)
Enum: "document-unreadable" "document-expired" "document-not-matching" "document-duplicate" "document-invalid" "document-not-open" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" … 5 more
message
string

The rejection message.

requestId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

object
score
number <double>

The calculated score that represents the % of confidence that this ID represents the given customer.

object (IdentityMatches)
containsImage
boolean

Flag that indicates if there is an image that contains a face on it.

isIdentityDocument
boolean

Flag that indicates if this looks like and ID.

isPublishedOnline
boolean

If there is an exact match found online.

firstName
string or null

The customer first name if it was matched, null otherwise.

lastName
string or null

The customer last name if it was matched, null otherwise.

dateOfBirth
string or null <date-time>

The date of birth found on the document, null if not found.

expiryDate
string or null <date-time>
Deprecated

The expiry date found on the document, null if not found.

expirationDate
string or null <date-time>

The expiration date found on the document, null if not found.

issueDate
string or null <date-time>

The issued date found on the document, null if not found.

hasMinimalAge
boolean or null

Checks the minimal age, 21+ for USA and 18+ for all other countries. Null if dateOfBirth could not be determined.

nationality
string or null <= 3 characters

The nationality found on the document, null otherwise.

documentSubtype
string or null

The interpreted subtype of the uploaded document.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

patch/kyc-documents/{id}
Request samples
application/json
{
  • "fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileIds": [
    ],
  • "documentType": "identity-proof",
  • "documentSubtype": "passport"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileIds": [
    ],
  • "documentType": "identity-proof",
  • "documentSubtype": "passport",
  • "status": "pending",
  • "rejectionReason": {
    },
  • "requestId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "processedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "documentMatches": {
    }
}

Retrieve a KYC request

Retrieve a KYC request with specified ID.

SecurityCustomerJWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

query Parameters
expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

Responses
200

KYC request was retrieved successfully.

Response Schema: application/json
required
Array of objects

Documents to be requested from customer.

Array
type
required
string

Document type to be requested from customer.

Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
subtypes
Array of strings (KycDocumentSubtypes)

Document subtype allowed for customer.

Items Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
maxAttempts
integer [ 0 .. 100 ]
Default: 3

The number of document upload attempts. 0 treated as unlimited.

faceProofRequired
boolean

If true uploading matching face photo (selfie) is required.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

status
string

Status of the request.

Enum: Description
gathering

No documents have been provided yet. Temporary state.

attempted

At least one document has been provided but is not accepted. Temporary state.

partial

At least one requested document has the accepted status, but not all of them. Temporary state.

pending-review

At least one document type has a document with the pending status and no documents with the accepted status. Temporary state (until reviewed or another accepted document is provided).

fulfilled

All requested documents are provided and accepted. Permanent state.

failed

At least one requested document exhausted all attempts and does not have the status accepted, pending or in-progress. Permanent state.

abandoned

Request expired and has at least one document provided. Permanent state.

expired

Request expired without any document uploaded. Permanent state.

redirectUrl
string <uri>

The URL to redirect the customer when an upload is completed. When the customer is redirected, Rebilly will append an info query parameter which may have one of the following values (example: https://example.com?info=success):

  • back - The customer clicked the back to website link;
  • token_expired - The customer's token expired;
  • success - The customer uploaded docs that were successfully analyzed;
  • manual - The customer uploaded docs that will require manual review because the analyzer rejected them or couldn't process them;
  • partial - The customer had success with some doc type but not with other (for example, successful proof of address but skipped proof of id).
expirationTime
string <date-time>

Expiration date-time. Default value is one hour in the future.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or KycDocumentsLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

object

Any embedded objects available that are requested by the expand querystring parameter.

Array of any (StorefrontKycDocument)
Array
documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

status
required
string

Status of the validation.

Enum: Description
pending

Waiting to be reviewed or analyzed

in-progress

Being analyzed by Rebilly's AI

accepted

Accepted by AI or a human

rejected

Rejected by AI or a human

archived

Archived by Rebilly's AI

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters
Deprecated

The resource ID. Defaults to UUID v4.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 11 more
object (KycDocumentRejection)
requestId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

object
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/kyc-requests/{id}
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/kyc-requests/{id}?expand=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "documents": [
    ],
  • "status": "gathering",
  • "redirectUrl": "http://example.com",
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": {
    }
}
➔ Next to Payment Instruments