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

Create a KYC Request

Create a KYC Request. Then, redirect the customer to the kycGatherer link. After the customer completes the KYC process, they will be redirected back to the redirectUrl. Corresponding webhooks (such as KYC document accepted, KYC document rejected) are sent to webhooks subscribers. When the complete list of documents is received and accepted, the KYC request fulfilled webhook will be sent to subscribers. If a credit-file-proof is successful with the decision single-source, then corresponding identity-proof and address-proof documents are not requested. If a credit-file-proof is successful with the decision dual-source, then one of the corresponding identity-proof and address-proof documents are required.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

KYC request resource.

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.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

The level of strictness for the document matches. The value of 1 is less strict and 2 is strict.

Responses
201

KYC request was created.

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.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

The level of strictness for the document matches. The value of 1 is less strict and 2 is strict.

revision
integer

The number of times the KYC request data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

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

The links related to the 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 objects (KycDocument)
Array
customerId
required
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

documentType
required
string

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

Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
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 Recursive

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters Recursive
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 Recursive

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.

reviewerId
string or null <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

reviewerName
string or null

Reviewer's first and last name.

reviewStartTime
string or null <date-time>

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

reviewTime
string or null <date-time>

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

notes
string or null

Reviewer notes.

Array of objects (Tag)

A list of kyc document tags.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

settings
object or null

The settings used to score the document.

revision
integer

The number of times the KYC document data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/kyc-requests
Request samples
application/json
{
  • "customerId": "123_456789",
  • "redirectUrl": "https://example.com/return-here/",
  • "documents": [
    ],
  • "reason": "registration"
}
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",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "reason": "spend limit",
  • "matchLevel": 2,
  • "revision": 0,
  • "_links": [
    ],
  • "_embedded": {
    }
}

Retrieve a list of KYC requests

Retrieve a list of KYC requests.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

A list of KYC requests 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
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.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

The level of strictness for the document matches. The value of 1 is less strict and 2 is strict.

revision
integer

The number of times the KYC request data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

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

The links related to the 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 objects (KycDocument)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/kyc-requests
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/organizations/unknown/kyc-requests?limit=1000&offset=0&filter=string&sort=string' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Retrieve a KYC request

Retrieve a KYC request with specified identifier string.

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

The resource identifier string.

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.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

The level of strictness for the document matches. The value of 1 is less strict and 2 is strict.

revision
integer

The number of times the KYC request data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

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

The links related to the 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 objects (KycDocument)
Array
customerId
required
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

documentType
required
string

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

Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
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 Recursive

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters Recursive
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 Recursive

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.

reviewerId
string or null <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

reviewerName
string or null

Reviewer's first and last name.

reviewStartTime
string or null <date-time>

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

reviewTime
string or null <date-time>

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

notes
string or null

Reviewer notes.

Array of objects (Tag)

A list of kyc document tags.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

settings
object or null

The settings used to score the document.

revision
integer

The number of times the KYC document data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

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/organizations/unknown/kyc-requests/{id}' \
  -H 'REB-APIKEY: YOUR_API_KEY_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",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "reason": "spend limit",
  • "matchLevel": 2,
  • "revision": 0,
  • "_links": [
    ],
  • "_embedded": {
    }
}

Update a KYC request

Update a KYC request.

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

The resource identifier string.

Request Body 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.

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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

The level of strictness for the document matches. The value of 1 is less strict and 2 is strict.

Responses
200

KYC request was updated.

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.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

The level of strictness for the document matches. The value of 1 is less strict and 2 is strict.

revision
integer

The number of times the KYC request data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

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

The links related to the 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 objects (KycDocument)
Array
customerId
required
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

documentType
required
string

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

Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
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 Recursive

The resource ID. Defaults to UUID v4.

fileId
string <= 50 characters Recursive
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 Recursive

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.

reviewerId
string or null <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

reviewerName
string or null

Reviewer's first and last name.

reviewStartTime
string or null <date-time>

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

reviewTime
string or null <date-time>

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

notes
string or null

Reviewer notes.

Array of objects (Tag)

A list of kyc document tags.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

settings
object or null

The settings used to score the document.

revision
integer

The number of times the KYC document data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

patch/kyc-requests/{id}
Request samples
application/json
{
  • "documents": [
    ],
  • "redirectUrl": "http://example.com",
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "reason": "spend limit",
  • "matchLevel": 2
}
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",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "reason": "spend limit",
  • "matchLevel": 2,
  • "revision": 0,
  • "_links": [
    ],
  • "_embedded": {
    }
}

Delete the KYC request

Delete the KYC request with the predefined identifier string.

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

The resource identifier string.

Responses
204

The KYC request was deleted.

401

Unauthorized access, invalid credentials were used.

404

Resource was not found.

delete/kyc-requests/{id}
Request samples
curl -i -X DELETE \
  'https://api-sandbox.rebilly.com/organizations/unknown/kyc-requests/{id}' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "status": 401,
  • "type": "http://example.com",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Retrieve a list of KYC documents

Retrieve a list of KYC documents.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

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
customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" "dob-mismatch" "name-mismatch" "other"
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 objects or objects or objects >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

reviewerId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

reviewerName
string or null

Reviewer's first and last name.

reviewStartTime
string or null <date-time>

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

reviewTime
string or null <date-time>

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

notes
string or null

Reviewer notes.

Array of objects (Tag)

A list of kyc document tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters Recursive

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.

Array of SelfLink (object) non-empty

The links related to resource.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

object or null

The settings used to score the document.

object

The weights of all matched properties.

object

The thresholds to determine the document status.

revision
integer

The number of times the KYC document data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object
score
number <double>

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

object (IdentityMatches)
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
// all parameters are optional
const firstCollection = await api.kycDocuments.getAll();

// alternatively you can specify one or more of them
const params = {limit: 20, offset: 100, sort: '-createdTime'};
const secondCollection = await api.kycDocuments.getAll(params);

// access the collection items, each item is a Member
secondCollection.items.forEach(document => console.log(document.fields.documentType));
Response samples
application/json
[
  • {
    }
]

Create a KYC Document

Create a KYC Document.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Kyc document resource.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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
notes
string or null

Reviewer notes.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

object or null

The settings used to score the document.

object

The weights of all matched properties.

containsImage
integer [ 0 .. 100 ]

The weight of containsImage.

isIdentityDocument
integer [ 0 .. 100 ]

The weight of isIdentityDocument.

isPublishedOnline
integer [ 0 .. 100 ]

The weight of isPublishedOnline.

firstName
integer [ 0 .. 100 ]

The weight of firstName.

lastName
integer [ 0 .. 100 ]

The weight of lastName.

expirationDate
integer [ 0 .. 100 ]

The weight of expirationDate.

dateOfBirth
integer [ 0 .. 100 ]

The weight of dateOfBirth.

matchesDateOfBirth
integer [ 0 .. 100 ]

The weight of matchesDateOfBirth.

issueDate
integer [ 0 .. 100 ]

The weight of issueDate.

hasMinimalAge
integer [ 0 .. 100 ]

The weight of hasMinimalAge.

hasMatchingFaceProof
integer [ 0 .. 100 ]

The weight of hasMatchingFaceProof.

nationality
integer [ 0 .. 100 ]

The weight of nationality.

object

The thresholds to determine the document status.

rejectBelow
integer [ 0 .. 100 ]

The weight of rejectBelow.

acceptAbove
integer [ 0 .. 100 ]

The weight of acceptAbove.

Responses
201

Kyc document was created.

Response Schema: application/json
customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" "dob-mismatch" "name-mismatch" "other"
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 objects or objects or objects >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

reviewerId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

reviewerName
string or null

Reviewer's first and last name.

reviewStartTime
string or null <date-time>

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

reviewTime
string or null <date-time>

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

notes
string or null

Reviewer notes.

Array of objects (Tag)

A list of kyc document tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters Recursive

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.

Array of SelfLink (object) non-empty

The links related to resource.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

object or null

The settings used to score the document.

object

The weights of all matched properties.

containsImage
integer [ 0 .. 100 ]

The weight of containsImage.

isIdentityDocument
integer [ 0 .. 100 ]

The weight of isIdentityDocument.

isPublishedOnline
integer [ 0 .. 100 ]

The weight of isPublishedOnline.

firstName
integer [ 0 .. 100 ]

The weight of firstName.

lastName
integer [ 0 .. 100 ]

The weight of lastName.

expirationDate
integer [ 0 .. 100 ]

The weight of expirationDate.

dateOfBirth
integer [ 0 .. 100 ]

The weight of dateOfBirth.

matchesDateOfBirth
integer [ 0 .. 100 ]

The weight of matchesDateOfBirth.

issueDate
integer [ 0 .. 100 ]

The weight of issueDate.

hasMinimalAge
integer [ 0 .. 100 ]

The weight of hasMinimalAge.

hasMatchingFaceProof
integer [ 0 .. 100 ]

The weight of hasMatchingFaceProof.

nationality
integer [ 0 .. 100 ]

The weight of nationality.

object

The thresholds to determine the document status.

rejectBelow
integer [ 0 .. 100 ]

The weight of rejectBelow.

acceptAbove
integer [ 0 .. 100 ]

The weight of acceptAbove.

revision
integer

The number of times the KYC document data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

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.

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",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "notes": "string",
  • "reason": "string",
  • "matchLevel": 2,
  • "settings": {
    }
}
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": [
    ],
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "reviewerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "reviewerName": "string",
  • "reviewStartTime": "2019-08-24T14:15:22Z",
  • "reviewTime": "2019-08-24T14:15:22Z",
  • "notes": "string",
  • "tags": [
    ],
  • "reason": "string",
  • "matchLevel": 2,
  • "settings": {
    },
  • "revision": 0,
  • "documentMatches": {
    },
  • "parsedData": {
    }
}

Retrieve a KYC Document

Retrieve a KYC document with specified identifier string.

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

The resource identifier string.

Responses
200

KYC document was retrieved successfully.

Response Schema: application/json
customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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" "underage-person" "third-party-or-mismatch" "expiration-date-missing" "issue-date-missing" "dob-mismatch" "name-mismatch" "other"
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 objects or objects or objects >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

reviewerId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

reviewerName
string or null

Reviewer's first and last name.

reviewStartTime
string or null <date-time>

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

reviewTime
string or null <date-time>

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

notes
string or null

Reviewer notes.

Array of objects (Tag)

A list of kyc document tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters Recursive

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.

Array of SelfLink (object) non-empty

The links related to resource.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]

The level of strictness for the document matches.

object or null

The settings used to score the document.

object

The weights of all matched properties.

containsImage
integer [ 0 .. 100 ]

The weight of containsImage.

isIdentityDocument
integer [ 0 .. 100 ]

The weight of isIdentityDocument.

isPublishedOnline
integer [ 0 .. 100 ]

The weight of isPublishedOnline.

firstName
integer [ 0 .. 100 ]

The weight of firstName.

lastName
integer [ 0 .. 100 ]

The weight of lastName.

expirationDate
integer [ 0 .. 100 ]

The weight of expirationDate.

dateOfBirth
integer [ 0 .. 100 ]

The weight of dateOfBirth.

matchesDateOfBirth
integer [ 0 .. 100 ]

The weight of matchesDateOfBirth.

issueDate
integer [ 0 .. 100 ]

The weight of issueDate.

hasMinimalAge
integer [ 0 .. 100 ]

The weight of hasMinimalAge.

hasMatchingFaceProof
integer [ 0 .. 100 ]

The weight of hasMatchingFaceProof.

nationality
integer [ 0 .. 100 ]

The weight of nationality.

object

The thresholds to determine the document status.

rejectBelow
integer [ 0 .. 100 ]

The weight of rejectBelow.

acceptAbove
integer [ 0 .. 100 ]

The weight of acceptAbove.

revision
integer

The number of times the KYC document data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object
score
number <double>

The calculated score that repr