Rebilly API Docs

Create a KYC document

Creates a KYC document.

SecuritySecretApiKey or JWT

Request

Request Body schema: application/json

Kyc document resource.

customerId

required

string (CustomerId) <= 50 characters

Customer resource ID.

documentType

required

string

Document type submitted for validation. Only the identity-proof and address-proof types are analyzed automatically.

fileId

string <= 50 characters

Deprecated

ID of the linked file object.

fileIds

Array of strings

IDs of linked file objects.

Uploaded identity-proof files must have the following tags attached to be used for KYC purposes: ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'].

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" … 16 more

notes

string or null

Reviewer notes.

reason

string

Reason for uploading.

matchLevel

integer [ 1 .. 2 ]

Tolerance level setting for document matches.

object or null

Settings used to score the document.

object

Property weights that are used for the KYC document verification process.

All KYC documents start the verification process with a score of 100. If a check fails, the score is reduced by the corresponding weight. For example, if the firstName check weight is set to 5, and the check fails, the KYC document score becomes 95.

containsImage	integer [ 0 .. 100 ] Weight added if the document does not include an image that contains a face.
isIdentityDocument	integer [ 0 .. 100 ] Weight added if the document does not resemble an ID.
isPublishedOnline	integer [ 0 .. 100 ] Weight added if an exact match of the document is not found online.
firstName	integer [ 0 .. 100 ] Weight added if the customer's first name is not matched.
lastName	integer [ 0 .. 100 ] Weight added if the customer's last name is not matched.
expirationDate	integer [ 0 .. 100 ] Weight added if an expiration date is not detected on the document.
dateOfBirth	integer [ 0 .. 100 ] Weight added if a date of birth is not detected on the document.
matchesDateOfBirth	integer [ 0 .. 100 ] Weight added if an identity document does not have a matching date of birth.
issueDate	integer [ 0 .. 100 ] Weight added if an issue date is not detected on the document.
hasMinimalAge	integer [ 0 .. 100 ] Weight added if the document does not verify the minimal age limit. Minimal age is 21+ the for USA and 18+ for all other countries.
hasMatchingFaceProof	integer [ 0 .. 100 ] Weight added if an identity document does not have matching face proof.
nationality	integer [ 0 .. 100 ] Weight added if a nationality is not detected on the document.
documentSubtype	integer [ 0 .. 100 ] Weight added if the document is not one of the recognized document subtypes.

object

Pass and fail threshold definition for the document verification process.

rejectBelow	integer [ 0 .. 100 ] Overall score by which an identity proof document fails the verification process.
acceptAbove	integer [ 0 .. 100 ] Overall score by which an identity proof document passes the verification process.

Responses

201

KYC document 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.

documentType

required

string

Document type submitted for validation. Only the identity-proof and address-proof types are analyzed automatically.

status

required

string

Status of the validation.

Enum:	Description
pending	Waiting to be reviewed or analyzed.
in-progress	Being analyzed by the Rebilly AI.
accepted	Accepted by AI or a human.
rejected	Rejected by AI or a human.
archived	Archived by the Rebilly AI.

string <= 50 characters

Unique resource ID. Defaults to UUID v4.

fileId

string <= 50 characters

Deprecated

ID of the linked file object.

fileIds

Array of strings

IDs of linked file objects.

Uploaded identity-proof files must have the following tags attached to be used for KYC purposes: ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'].

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" … 16 more

object (KycDocumentRejection)

Reason the document is rejected.

type	string (KycDocumentRejectionReasonTypes) Reason the document is rejected. 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 KYC document rejection message.

requestId

string or null <= 50 characters

ID of the KYC request.

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.

processedTime

string <date-time>

Date and time when the KYC document is processed.

reviewerId

string or null <= 50 characters

ID of the KYC document reviewer.

reviewerName

string or null

First and last name of the KYC document reviewer.

reviewStartTime

string or null <date-time>

Date and time when the manual review starts.

reviewTime

string or null <date-time>

Date and time of manual review.

notes

string or null

Reviewer notes.

Array of objects (Tag)

List of KYC document tags.

Array

name required	string <= 255 characters ^[@~\-\.\w\s]+$ Unique name for the tag. Tag names are not case-sensitive.
type required	string Type of tag. Tags of a specific type can only be assigned to corresponding entity types. For example, you can only use customer tags on customers. Enum: "customer" "kyc-document"
id	string <= 50 characters ID of the tag.
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 (SelfLink) Related links.

reason

string

Reason for uploading.

matchLevel

integer [ 1 .. 2 ]

Tolerance level setting for document matches.

object or null

Settings used to score the document.

object

Property weights that are used for the KYC document verification process.

containsImage	integer [ 0 .. 100 ] Weight added if the document does not include an image that contains a face.
isIdentityDocument	integer [ 0 .. 100 ] Weight added if the document does not resemble an ID.
isPublishedOnline	integer [ 0 .. 100 ] Weight added if an exact match of the document is not found online.
firstName	integer [ 0 .. 100 ] Weight added if the customer's first name is not matched.
lastName	integer [ 0 .. 100 ] Weight added if the customer's last name is not matched.
expirationDate	integer [ 0 .. 100 ] Weight added if an expiration date is not detected on the document.
dateOfBirth	integer [ 0 .. 100 ] Weight added if a date of birth is not detected on the document.
matchesDateOfBirth	integer [ 0 .. 100 ] Weight added if an identity document does not have a matching date of birth.
issueDate	integer [ 0 .. 100 ] Weight added if an issue date is not detected on the document.
hasMinimalAge	integer [ 0 .. 100 ] Weight added if the document does not verify the minimal age limit. Minimal age is 21+ the for USA and 18+ for all other countries.
hasMatchingFaceProof	integer [ 0 .. 100 ] Weight added if an identity document does not have matching face proof.
nationality	integer [ 0 .. 100 ] Weight added if a nationality is not detected on the document.
documentSubtype	integer [ 0 .. 100 ] Weight added if the document is not one of the recognized document subtypes.

object

Pass and fail threshold definition for the document verification process.

rejectBelow	integer [ 0 .. 100 ] Overall score by which an identity proof document fails the verification process.
acceptAbove	integer [ 0 .. 100 ] Overall score by which an identity proof document passes the verification process.

revision

integer

Number of times the KYC document data has been modified.

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

object

Proof of identity document matches.

score

number <double>

Calculated score that represents the percentage of confidence that this ID represents the customer.

object (IdentityMatches)

Matched identity data.

containsImage	boolean Specifies if the document includes an image that contains a face.
isIdentityDocument	boolean Specifies if the document resembles an ID.
isPublishedOnline	boolean Specifies if an exact match of the document has been found online.
matchingImages	Array of strings <= 3 items URLs where matching images have been found online.
firstName	string or null First name of the customer. This value is null if no match is found.
lastName	string or null Last name of the customer. This value is null if no match is found.
dateOfBirth	string or null <date-time> Date of birth detected on the document. This value is null if no match is detected.
expirationDate	string or null <date-time> Expiration date detected on the document. This value is null if no expiration date is detected.
issueDate	string or null <date-time> Issue date detected on the document. This value is null if no issue date is detected.
hasMinimalAge	boolean or null Specifies that the individual is older than the minimal age limit. The minimal age is 21+ the for USA and 18+ for all other countries. This value is null if `dateOfBirth` is not determined.
nationality	string or null <= 3 characters Nationality detected on a passport or citizenship document. This value is null if no nationality is detected.
issuanceCountry	string or null = 2 characters Country that issued the document.
issuanceRegion	string or null Region, state, province, or territory that issued the document.
documentNumber	string or null Unique number on the identity document. This value may contain alphanumeric characters.
documentSubtype	string or null Interpreted subtype of the uploaded document. Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 16 more
hasMatchingFaceProof	boolean Specifies if an identity document has matching face proof.
expiryDate	string or null <date-time> Deprecated Use `expirationDate` field instead.

object

Parsed data.

score

number <double>

Calculated score that represents the percentage of confidence that this ID represents the customer.

object (IdentityMatches)

Matched identity data.

containsImage	boolean Specifies if the document includes an image that contains a face.
isIdentityDocument	boolean Specifies if the document resembles an ID.
isPublishedOnline	boolean Specifies if an exact match of the document has been found online.
matchingImages	Array of strings <= 3 items URLs where matching images have been found online.
firstName	string or null First name of the customer. This value is null if no match is found.
lastName	string or null Last name of the customer. This value is null if no match is found.
dateOfBirth	string or null <date-time> Date of birth detected on the document. This value is null if no match is detected.
expirationDate	string or null <date-time> Expiration date detected on the document. This value is null if no expiration date is detected.
issueDate	string or null <date-time> Issue date detected on the document. This value is null if no issue date is detected.
hasMinimalAge	boolean or null Specifies that the individual is older than the minimal age limit. The minimal age is 21+ the for USA and 18+ for all other countries. This value is null if `dateOfBirth` is not determined.
nationality	string or null <= 3 characters Nationality detected on a passport or citizenship document. This value is null if no nationality is detected.
issuanceCountry	string or null = 2 characters Country that issued the document.
issuanceRegion	string or null Region, state, province, or territory that issued the document.
documentNumber	string or null Unique number on the identity document. This value may contain alphanumeric characters.
documentSubtype	string or null Interpreted subtype of the uploaded document. Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 16 more
hasMatchingFaceProof	boolean Specifies if an identity document has matching face proof.
expiryDate	string or null <date-time> Deprecated Use `expirationDate` field instead.

Array of objects

Related links.

Array

href	string Link URL.
rel	string Type of link. Enum: "self" "customer"

object

Embedded objects that are requested by the expand query parameter.

customer

object

401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

422

Invalid data sent.

post/kyc-documents

Request samples

application/json

{"fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"fileIds": ["4f6cf35x-2c4y-483z-a0a9-158621f77a21"
],
"documentType": "identity-proof",
"documentSubtype": "passport",
"customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
"notes": "string",
"reason": "string",
"matchLevel": 2,
"settings": {"weights": {"containsImage": 100,
"isIdentityDocument": 100,
"isPublishedOnline": 100,
"firstName": 100,
"lastName": 100,
"expirationDate": 100,
"dateOfBirth": 100,
"matchesDateOfBirth": 100,
"issueDate": 100,
"hasMinimalAge": 100,
"hasMatchingFaceProof": 100,
"nationality": 100,
"documentSubtype": 100
},
"thresholds": {"rejectBelow": 100,
"acceptAbove": 100
}
}
}

Response samples

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"fileId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"fileIds": ["4f6cf35x-2c4y-483z-a0a9-158621f77a21"
],
"documentType": "identity-proof",
"documentSubtype": "passport",
"status": "pending",
"rejectionReason": {"type": "document-unreadable",
"message": "Provided document is unreadable"
},
"requestId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"processedTime": "2019-08-24T14:15:22Z",
"customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
"reviewerId": "44433322-2c4y-483z-a0a9-158621f77a21",
"reviewerName": "string",
"reviewStartTime": "2019-08-24T14:15:22Z",
"reviewTime": "2019-08-24T14:15:22Z",
"notes": "string",
"tags": [{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"name": "New",
"type": "customer",
"createdTime": "2019-08-24T14:15:22Z",
"updatedTime": "2019-08-24T14:15:22Z",
"_links": [{"href": "string",
"rel": "self"
}
]
}
],
"reason": "string",
"matchLevel": 2,
"settings": {"weights": {"containsImage": 100,
"isIdentityDocument": 100,
"isPublishedOnline": 100,
"firstName": 100,
"lastName": 100,
"expirationDate": 100,
"dateOfBirth": 100,
"matchesDateOfBirth": 100,
"issueDate": 100,
"hasMinimalAge": 100,
"hasMatchingFaceProof": 100,
"nationality": 100,
"documentSubtype": 100
},
"thresholds": {"rejectBelow": 100,
"acceptAbove": 100
}
},
"revision": 0,
"documentMatches": {"score": 0.75,
"data": {"containsImage": true,
"isIdentityDocument": true,
"isPublishedOnline": false,
"matchingImages": ["string"
],
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "2019-08-24T14:15:22Z",
"expirationDate": "2019-08-24T14:15:22Z",
"issueDate": "2019-08-24T14:15:22Z",
"hasMinimalAge": true,
"nationality": "US",
"issuanceCountry": "CA",
"issuanceRegion": "Ontario",
"documentNumber": "1234567890",
"documentSubtype": "passport",
"hasMatchingFaceProof": false,
"expiryDate": "2019-08-24T14:15:22Z"
}
},
"parsedData": {"score": 0.75,
"data": {"containsImage": true,
"isIdentityDocument": true,
"isPublishedOnline": false,
"matchingImages": ["string"
],
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "2019-08-24T14:15:22Z",
"expirationDate": "2019-08-24T14:15:22Z",
"issueDate": "2019-08-24T14:15:22Z",
"hasMinimalAge": true,
"nationality": "US",
"issuanceCountry": "CA",
"issuanceRegion": "Ontario",
"documentNumber": "1234567890",
"documentSubtype": "passport",
"hasMatchingFaceProof": false,
"expiryDate": "2019-08-24T14:15:22Z"
}
},
"_links": [{"href": "string",
"rel": "self"
}
],
"_embedded": {"customer": { }
}
}

➔ Next to Retrieve a KYC document