Guides
API integration
2. The applicant is filling the form and submits data to the customer server.
3. The customer server is sending applicant’s data to the KYCAID server using Create applicant API.
4. The customer server is receiving a response of Create applicant request.
5. The customer Create verification.
6. The customer server is receiving a response of Create verification request.
7. Within 2 minutes to 6 hours, the KYCAID server sends the verification callback to the customer's server.
8. The customer server is sending a success response (http status 200) as a sign of getting a successful verification result.
Notes
- Verification takes from 2 minutes to 6 hours
- To update applicant data can be used Update applicant API.
- To update applicant document data can be used Update document API.
- The customer can check the verification status after receiving a response to the Create verification request.
- The verification fee is withdrawn after Create verification request or when applicant has submitted a form.
Forms integration

2. The customer server sends a request for Get form URL.
3. The customer server receives a response of Get form URL request.
4. The applicant opens KYCAID form by URL that was received in response.
5. The applicant fills the form and submits data to the KYCAID server.
6. The KYCAID form receives response and shows a success message to the applicant. Also there is a possibility to redirect the applicant to the customer page.
7. Within 2 minutes to 6 hours, KYCAID server sends the verification callback to the customer's server.
8. The customer server sends success response (http status 200) as a sign of getting a successful verification result.
Notes
- Verification takes from 2 minutes to 6 hours
- There is no need to Create form each time if a form already exists with the appropriate verification types.
- Also, the form can be created manually in the customer's personal account on the kycaid.com.
Single link integration
head
of the page where you would like to place a link to KYC:<script src="https://api.kycaid.com/websdk/js?key=WEB_SDK_KEY"></script>
2. The next link should be placed in whatever you want on the page:
<a href="https://api.kycaid.com/websdk/forms/FORM_ID?key=WEB_SDK_KEY" target="_blank">KYC verification</a>
Notes
- Please contact to customer support for whitelist your domain and get personal
WEB_SDK_KEY
. - The URL parameter
external_applicant_id
can be added for linking the customer's internal user id and KYCAID applicant id.external_applicant_id
will come in callbackVERIFICATION_COMPLETED
.
URL format<a href="https://api.kycaid.com/websdk/forms/FORM_ID?key=WEB_SDK_KEY&applicant=APPLICANT_ID" target="_blank">KYC verification</a>
- The URL parameter
applicant_id
should be added to recheck exist applicant:
URL format<a href="https://api.kycaid.com/websdk/forms/FORM_ID?key=WEB_SDK_KEY&applicant_id=APPLICANT_ID" target="_blank">KYC verification</a>
General
Introduction
- All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
- Authentication to the API is performed via token-based auth.
- JSON is returned on all our API responses, including errors, with a consistent structure for all messages.
- Response codes are used to indicate the status of the message and any error codes.
- All requests must use TLS 1.2 or above.
- Text fields support UTF-8, but do not allow certain special characters that could be used maliciously.
Authentication
# Example just show how to pass the correct header with each request
curl https://api.kycaid.com/applicants \
-H 'Authorization: Token <API_TOKEN>'
Test mode
Limits
Auto verify
Type | Status | Values |
---|---|---|
KYC | Approve | first_name : John last_name : Snow |
KYC | Decline | first_name : John last_name : Doe |
KYB | Approve | company_name : SpaceX |
KYB | Decline | company_name : Roscosmos |
Errors
Error codes
Code | Type | Description |
---|---|---|
400 | bad_request | Your request could not be processed, there should be more details in the response. |
infected_file | The antivirus has identified the file as not trustworthy. | |
limit_file_size | The file is too large. | |
401 | unauthorized | Invalid authorization token. |
inactive_account | Account was blocked. | |
402 | insufficient_funds | Funds are not enough to do some action. |
403 | forbidden_duplicates_retries | Block retries for duplicates. |
forbidden_age_restricted_retries | Block retries for restricted by age. | |
forbidden_country_restricted_retries | Block retries for restricted by country. | |
forbidden_compromised_person_retries | Block retries for compromised person. | |
forbidden_fake_document_retries | Block retries for for cases where applicant provided fake or edited documents. | |
404 | not_found | URL or some entry not found |
408 | request_timeout | The server timed out waiting for the request. |
409 | duplicate_data | For instance when verification request has been submitted already. |
flow | Some action that contradicts the functional flow. | |
edit_denied | The entry can not be edited. | |
delete_denied | The entry can not be deleted. | |
422 | validation | Response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions or parameters. |
applicant_exists | Application already exists. | |
incompatible_file_for_recognition | File can not be recognized. | |
verification_exists | Verification already exists. | |
insufficient_data | Insufficient applicant data for current verification. | |
broken_file | The file is damaged. | |
incompatible_file_format | The file format does not match the following formats: BMP , BMP2 , BMP3 , GIF , HEIC , JPEG , JPG , PNG , PNG8 , PNG00 , PNG24 , PNG32 , PNG48 , PNG64 , WEBP , PDF , MP4 , WEBM . | |
image_small_resolution | The image resolution is too small. Minimal resolution is 480 px. | |
image_huge_resolution | The image resolution is too huge. The maximum resolution is 7000 px. | |
429 | limit_exceeded | Exceeding of some limits. (Example: The limit for creating documents has been exceeded) |
500 | internal_server | An unexpected error occurred on the server without a specific message. |
503 | service_unavailable | The current service is temporarily unavailable. |
{
"type": "validation",
"errors": [
{
"parameter": "residence_country",
"message": "Country of residence has incorrect format"
}
]
}
Applicants
Applicant types
Type | Description |
---|---|
PERSON | Applicant type using for KYC verification. |
COMPANY | Applicant type using for KYB verification. |
Applicant object
Parameter | Description |
---|---|
applicant_id PERSON COMPANY | string (36) Required The applicant’s unique identificator. |
type PERSON COMPANY | string (7) Required The applicant type. Valid values are PERSON or COMPANY. |
first_name PERSON | string (50) The applicant’s first name. |
middle_name PERSON | string (50) The applicant’s middle name. |
last_name PERSON | string (50) The applicant’s last name. |
dob PERSON | string (10) The applicant’s date of birth date. (ISO 8601, YYYY-MM-DD) |
residence_country PERSON | string (2) The applicant’s current nationality. Example: GB (ISO 3166-2) |
gender PERSON | string (1) The applicant’s gender. International regulations require either "M" or "F". |
wallet_address PERSON | string (50) The applicant’s cryptocurrency wallet address. |
telegram_username PERSON | string (32) The applicant’s Telegram username. |
pep PERSON | boolean Define if applicant is politically exposed person. |
custom_field_1 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_2 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_3 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_4 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_5 PERSON | string (2048) Custom field can be used for storing any customer data. |
company_name COMPANY | string (255) Required for COMPANY The applicant’s company name. |
business_activity_id COMPANY | string (36) Required for COMPANY The business activity of applicant’s company. API for getting business activities. |
registration_country COMPANY | string (2) Required for COMPANY The registration country of applicant’s company. Example: GB (ISO 3166-2) |
email PERSON COMPANY | string (254) The applicant’s email address. |
phone PERSON COMPANY | string (15) The phone number of applicant. |
external_applicant_id PERSON COMPANY | string (50) Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems. |
addresses PERSON COMPANY | list Address object Required The addresses associated with the matched applicant. |
documents PERSON COMPANY | list Document object Required The documents associated with the matched applicant. |
profile_status PERSON COMPANY | enum (pending, valid, invalid) Required The status of profile verification. |
decline_reasons PERSON COMPANY | list Decline reason Required List of decline reasons receiving only for profile has invalid status. |
verification_status PERSON COMPANY | enum (pending, valid, invalid) Required The status of applicant's last verification. |
created_at PERSON COMPANY | string Required Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
{
"applicant_id": "{applicant_id}",
"type": "PERSON",
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"dob": "1970-10-25",
"residence_country": "GB",
"gender": "M",
"email": "john.doe@mail.com",
"phone": "+44 1632 960615",
"wallet_address": "1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX",
"telegram_username": "johndoe",
"pep": false,
"profile_status": false,
"decline_reasons": [
"WRONG_NAME",
"WRONG_DOB"
],
"addresses": [
{
"address_id": "{address_id}",
"type": "REGISTERED",
"status": "valid",
"full_address": null,
"country": "GB",
"state_or_province": "Westminster",
"city": "London",
"postal_code": "SW1A 2AB",
"street_name": "Downing St",
"building_number": "10",
"unit_number": null,
"created_at": "2020-11-22 14:15:15",
"decline_reasons": []
}
],
"documents": [
{
"document_id": "{document_id}",
"type": "PASSPORT",
"status": "invalid",
"document_number": "00000000001",
"issue_date": "2000-01-01",
"expiry_date": "2020-01-01",
"income_sources": [],
"annual_income": null,
"transaction_amount": null,
"transaction_purpose": null,
"origin_funds": null,
"card_number": null,
"account_number": null,
"front_side_id": "{front_side_id}",
"front_side": "{front_side_url}",
"back_side_id": null,
"back_side": null,
"created_at": "2020-11-22 14:14:56",
"decline_reasons": [
"EXPIRED_DOCUMENT"
]
}
],
"verification_status": "invalid",
"created_at": "2020-01-31 13:52:36"
}
Create applicant
Request
URL: https://api.kycaid.com/applicants
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
type PERSON COMPANY | string (7) Required The applicant type. Valid values are PERSON or COMPANY. |
first_name PERSON | string (50) The applicant’s first name. |
middle_name PERSON | string (50) The applicant’s middle name. |
last_name PERSON | string (50) The applicant’s last name. |
dob PERSON | string (10) The applicant’s date of birth. (ISO 8601, YYYY-MM-DD) |
residence_country PERSON | string (2) The applicant’s current nationality. Example: GB (ISO 3166-2) |
gender PERSON | string (1) The applicant’s gender. International regulations require either "M" or "F". |
wallet_address PERSON | string (50) The applicant’s cryptocurrency wallet address. |
telegram_username PERSON | string (32) The applicant’s Telegram username. |
pep PERSON | boolean Define if applicant is politically exposed person. |
custom_field_1 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_2 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_3 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_4 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_5 PERSON | string (2048) Custom field can be used for storing any customer data. |
company_name COMPANY | string (255) Required for COMPANY The applicant’s company name. |
business_activity_id COMPANY | string (36) Required for COMPANY The business activity of applicant’s company. API for getting business activities. |
registration_country COMPANY | string (2) Required for COMPANY The registration country of applicant’s company. Example: GB (ISO 3166-2) |
email PERSON COMPANY | string (254) The applicant’s email address. |
phone PERSON COMPANY | string (15) The phone number of applicant. |
external_applicant_id PERSON COMPANY | string (50) Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems. |
With a new version of the verification, a new profile will be created using the data from the new identity document if profile was not updated for current verification version.
curl https://api.kycaid.com/applicants \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "PERSON",
"first_name": "John",
"last_name": "Doe",
"dob": "1970-10-25",
"residence_country": "GB",
"email": "john.doe@mail.com"
}'
Response
Parameter | Description |
---|---|
applicant_id | string (36) Required The unique identifier of the applicant, which must be saved in the client's database and used to bind the client's user to the KYCAID applicant. |
{
"applicant_id": "{applicant_id}"
}
Update applicant
Request
URL: https://api.kycaid.com/applicants/{applicant_id}
Method: PATCH
Content-Type: application/json
Parameter | Description |
---|---|
first_name PERSON | string (50) The applicant’s first name. |
middle_name PERSON | string (50) The applicant’s middle name. |
last_name PERSON | string (50) The applicant’s last name. |
dob PERSON | string (10) The applicant’s date of birth. (ISO 8601, YYYY-MM-DD) |
residence_country PERSON | string (2) The applicant’s current nationality. Example: GB (ISO 3166-2) |
gender PERSON | string (1) The applicant’s gender. International regulations require either "M" or "F". |
wallet_address PERSON | string (50) The applicant’s cryptocurrency wallet address. |
telegram_username PERSON | string (32) The applicant’s Telegram username. |
pep PERSON | boolean Define if applicant is politically exposed person. |
custom_field_1 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_2 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_3 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_4 PERSON | string (2048) Custom field can be used for storing any customer data. |
custom_field_5 PERSON | string (2048) Custom field can be used for storing any customer data. |
company_name COMPANY | string (255) The applicant’s company name. |
business_activity_id COMPANY | string (36) The business activity of applicant’s company. API for getting business activities. |
registration_country COMPANY | string (2) The registration country of applicant’s company. Example: GB (ISO 3166-2) |
email PERSON COMPANY | string (254) The applicant’s email address. |
phone PERSON COMPANY | string (15) The phone number of applicant. |
curl https://api.kycaid.com/applicants/{applicant_id} \
-H 'Authorization: Token <API_TOKEN>'
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"first_name": "John",
"last_name": "Doe",
"dob": "1970-10-25",
"residence_country": "GB"
}'
Response
Parameter | Description |
---|---|
applicant_id | string (36) Required The applicant’s unique identificator. |
{
"applicant_id": "{applicant_id}"
}
Get applicant
Request
URL: https://api.kycaid.com/applicants/{applicant_id}
Method: GET
Parameter | Description |
---|---|
verification_id | string (36) The verification’s unique identificator. It can be used for fetch specific version of applicant data which is correspond was created verification. |
curl https://api.kycaid.com/applicants/{applicant_id} \
-H 'Authorization: Token <API_TOKEN>'
-X GET
Response
Parameter | Description |
---|---|
applicant_id PERSON COMPANY | string (36) Required The applicant’s unique identificator. |
type PERSON COMPANY | string (7) Required The applicant type. Valid values are PERSON or COMPANY. |
first_name PERSON | string (50) The applicant’s first name. |
middle_name PERSON | string (50) The applicant’s middle name. |
last_name PERSON | string (50) The applicant’s last name. |
dob PERSON | string (10) The applicant’s day of birth date. (ISO 8601, YYYY-MM-DD) |
residence_country PERSON | string (2) The applicant’s current nationality. Example: GB (ISO 3166-2) |
gender PERSON | string (1) The applicant’s gender. International regulations require either "M" or "F". |
pep PERSON | boolean Define if applicant is politically exposed person. |
company_name COMPANY | string (255) Required for COMPANY The applicant’s company name. |
business_activity_id COMPANY | string (36) Required for COMPANY The business activity of applicant’s company. API for getting business activities. |
registration_country COMPANY | string (2) Required for COMPANY The registration country of applicant’s company. Example: GB (ISO 3166-2) |
email PERSON COMPANY | string (254) The applicant’s email address. |
phone PERSON COMPANY | string (15) The phone number of applicant. |
addresses PERSON COMPANY | list Address object Required The addresses associated with the matched applicant. |
documents PERSON COMPANY | list Document object Required The documents associated with the matched applicant. |
profile_status PERSON COMPANY | enum (pending, valid, invalid) Required The status of profile verification. |
decline_reasons PERSON COMPANY | list Decline reason Required List of decline reasons receiving only for profile has invalid status. |
created_at PERSON COMPANY | string Required Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
{
"applicant_id": "{applicant_id}",
"type": "PERSON",
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"dob": "1970-10-25",
"residence_country": "GB",
"gender": null,
"email": "john.doe@mail.com",
"phone": null,
"pep": null,
"profile_status: false,
"decline_reasons": [
"WRONG_NAME",
"WRONG_DOB"
],
"addresses": [],
"documents": [],
"verification_status": "invalid",
"created_at": "2020-01-31 13:52:36"
}
Documents
Document types
Type | Description |
---|---|
GOVERNMENT_ID | A formal document issued by a country's government to prove a person's identity, which is usually issued in a form of a small card and includes your photo, full name, date of birth, gender and other identity information. |
PASSPORT | A document issued by a country's government to its citizens, that certifies the identity and nationality of its holder primarily for the purpose of international travel. |
DOMESTIC_PASSPORT | An internal identity document used by a country to control and monitor the internal movement and residence of its citizens. |
DRIVERS_LICENSE | An official document permitting a specific individual to operate one or more types of vehicle and may be accepted as proof of identity. |
PERMANENT_RESIDENCE_PERMIT | A document which confirms a person's resident status in a country of which they are not citizen but where they have the right to reside on a permanent basis( usually for a permanent period). |
REFUGEE_CARD | Identity certificate that refugees use as proof of identity. Issued by UNHCR or by the State of asylum. |
FOREIGN_CITIZEN_PASSPORT | A document which identifies the person as a citizen of a foreign country. |
SELFIE_IMAGE | A self-portrait photo which you made by yourself. |
SELFIE_WITH_DOCUMENT | A self-made portrait photo of yourself holding your identity document in a hand. |
SELFIE_WITH_CREDIT_CARD | A self-made portrait photo of yourself holding your credit card in a hand required to confirm the cardholder. |
ADDRESS_DOCUMENT | A legal document that confirms a person's living address, like a bank statement or utility bill with the date of issue and the person's full name, and any identity documents that have an address stated in them. |
FINANCIAL_DOCUMENT | The formal records of the financial activities and position of a business, person, or other entity which include a balance sheet, an income statement, and a cash flow statement. |
TAX_ID_NUMBER | A unique combination of characters assigned by a country’s tax authority to a person and used to identify that person for the purposes of administering the country’s tax laws. |
CREDIT_CARD | A plastic payment card issued by financial institutions, way to you access to the funds at your bank account. |
BANK_STATEMENT | A list of all transactions for a bank account over a set period, which includes deposits, charges, withdrawals, as well as the beginning and ending balance for the period. |
REGISTRATION_COMPANY | A legal registration statement which confirms that a company was formed and registered with the appropriate statutory authority of the country in accordance with the corporate and securities law of that country. |
COMPANY_LEGAL_ADDRESS | A legal document which contains the official registered address of the company. |
AUTHORISED_PERSON | A legal written notice which states that a person has been designated from Customer or its designated agent to act on behalf of Customer hereunder. |
COMPANY_OWNERSHIP | An official document with the legit information about the ownership of a specific company or organization, like the articles of organization, business certificate, stock certificates and share ledgers. |
VIDEO | A video on which the applicant should verify his identity. |
Document object
Parameter | Description |
---|---|
document_id | string (36) The unique identificator of applicant document. |
type | string (7) The document type. Valid values are: |
document_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) The unique number associated with document (e.g. passport number). |
additional_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) Some additional unique number (e.g. tax id on government id). |
issue_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) The issue date of the document. (ISO 8601, YYYY-MM-DD) |
expiry_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) The expiry date of the document. (ISO 8601, YYYY-MM-DD) |
issuing_authority GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (255) The authority that issued a document. |
card_number CREDIT_CARD | string (19) Payment credit card number with a minimum length of 12 and a maximum length of 19. Also can be used for determinate mask of credit card number. Example 4540********1265. |
account_number CREDIT_CARD | string (50) Any payment account number like IBAN, etc. |
income_sources FINANCIAL_DOCUMENT BANK_STATEMENT | array One or many income sources. Possible values: SALARY , DIVIDENDS , SALE_PROPERTY , SAVINGS , DIVORCE_SETTLEMENTS , INHERITANCE , LOAN , INVESTMENTS , OTHER . |
annual_income FINANCIAL_DOCUMENT BANK_STATEMENT | string (21) One of annual income group.ANNUAL_INCOME_GROUP_1 - below 50000 EURANNUAL_INCOME_GROUP_2 - 50000 - 100000 EURANNUAL_INCOME_GROUP_3 - 100000 - 300000 EURANNUAL_INCOME_GROUP_4 - above 300000 EUR. |
transaction_amount FINANCIAL_DOCUMENT BANK_STATEMENT | float Amount of transaction. |
transaction_currency FINANCIAL_DOCUMENT BANK_STATEMENT | string (3) Currency code of transaction. Example USD, BTC, etc. (ISO 4217). |
transaction_datetime FINANCIAL_DOCUMENT BANK_STATEMENT | string(19) Date and time of transaction. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
transaction_purpose FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Description of transaction purpose. |
origin_funds FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Description of origin funds. |
front_side_id | string (36) The file unique identificator that received in response of Create file. |
back_side_id | string (36) The file unique identificator that received in response of Create file. |
other_side_1_id | string (36) The file unique identificator that received in response of Create file. |
other_side_2_id | string (36) The file unique identificator that received in response of Create file. |
created_at | string Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
status | string (7) Status of document verification. Possible values:null - status of verification is not availablevalid - the document is validinvalid - the document is not valid |
comment | string (1000) The comment is about reasons of decline. It can be used as error message. |
decline_reasons | list Decline reason List of decline reasons receiving only for document has invalid status. |
{
"document_id": "{document_id}",
"applicant_id": "{applicant_id}",
"type": "PASSPORT",
"document_number": "00000000001",
"additional_number": "00000000002",
"issue_date": "2000-01-01",
"expiry_date": "2020-01-01",
"income_sources": [],
"annual_income": null,
"transaction_amount": null,
"transaction_purpose": null,
"transaction_currency": null,
"transaction_datetime": null,
"origin_funds": null,
"card_number": null,
"account_number": null,
"front_side_id": "{front_side_id}",
"front_side": "{front_side_url}",
"back_side_id": null,
"back_side": null,
"other_side_1_id": null,
"other_side_1": null,
"other_side_2_id": null,
"other_side_2": null,
"created_at": "2020-11-22 14:14:56",
"status": "invalid",
"comment": "some comment about reason of decline",
"decline_reasons": [
"EXPIRED_DOCUMENT"
]
}
Create document
Request
URL: https://api.kycaid.com/documents
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
applicant_id APPLICANT | string (36) Required for applicant The applicant’s unique identificator that received in response of Create applicant. |
affiliated_person_id AFFILIATED PERSON | string (36) Required for affiliated person The affiliated person’s unique identificator that received in response of Create affiliated person. |
type | string (7) Required The document type. Valid values are: |
document_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) The unique number associated with document (e.g. passport number). |
additional_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) Some additional unique number (e.g. tax id on government id). |
issue_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) The issue date of the document. (ISO 8601, YYYY-MM-DD) |
expiry_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) The expiry date of the document. (ISO 8601, YYYY-MM-DD) |
issuing_authority GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (255) The authority that issued a document. |
card_number CREDIT_CARD | string (19) Payment credit card number with a minimum length of 12 and a maximum length of 19. Also can be used for determinate mask of credit card number. Example 4540********1265. |
account_number CREDIT_CARD | string (50) Any payment account number like IBAN, etc. |
income_sources FINANCIAL_DOCUMENT BANK_STATEMENT | array One or many income sources. Possible values: SALARY , DIVIDENDS , SALE_PROPERTY , SAVINGS , DIVORCE_SETTLEMENTS , INHERITANCE , LOAN , INVESTMENTS , OTHER . |
annual_income FINANCIAL_DOCUMENT BANK_STATEMENT | string (21) One of annual income group.ANNUAL_INCOME_GROUP_1 - below 50000 EURANNUAL_INCOME_GROUP_2 - 50000 - 100000 EURANNUAL_INCOME_GROUP_3 - 100000 - 300000 EURANNUAL_INCOME_GROUP_4 - above 300000 EUR. |
transaction_amount FINANCIAL_DOCUMENT BANK_STATEMENT | float Amount of transaction. |
transaction_currency FINANCIAL_DOCUMENT BANK_STATEMENT | string (3) Currency code of transaction. Example USD, BTC, etc. (ISO 4217). |
transaction_datetime FINANCIAL_DOCUMENT BANK_STATEMENT | string(19) Date and time of transaction. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
transaction_purpose FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Description of transaction purpose. |
origin_funds FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Description of origin funds. |
front_side_id | string (36) The file unique identificator that received in response of Create file. |
back_side_id | string (36) The file unique identificator that received in response of Create file. |
other_side_1_id | string (36) The file unique identificator that received in response of Create file. |
other_side_2_id | string (36) The file unique identificator that received in response of Create file. |
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "{applicant_id}",
"type": "PASSPORT",
"document_number": "2367823468",
"issue_date": "2010-10-25",
"expiry_date": "2020-07-10",
"front_side_id": "{file_id}",
"back_side_id": "{file_id}"
}'
Response
Parameter | Description |
---|---|
document_id | string (36) Required The document unique identificator. |
{
"document_id": "{document_id}"
}
Document count limits
Document type | Limit per verification |
---|---|
GOVERNMENT_ID / PASSPORT / DRIVERS_LICENSE / DOMESTIC_PASSPORT / PERMANENT_RESIDENCE_PERMIT / REFUGEE_CARD / FOREIGN_CITIZEN_PASSPORT | 1 |
SELFIE_IMAGE / SELFIE_WITH_DOCUMENT / SELFIE_WITH_CREDIT_CARD | 1 |
ADDRESS_DOCUMENT | 1 |
TAX_ID_NUMBER | 1 |
CREDIT_CARD | 1 |
REGISTRATION_COMPANY | 1 |
COMPANY_LEGAL_ADDRESS | 1 |
AUTHORISED_PERSON | 1 |
COMPANY_OWNERSHIP | 1 |
VIDEO | 1 |
FINANCIAL_DOCUMENT / BANK_STATEMENT | 5 |
Parameter
duplicate_document_ids
can be used for updating existing document instead on creation.Update document
Request
URL: https://api.kycaid.com/documents/{document_id}
Method: PATCH
Content-Type: application/json
Parameter | Description |
---|---|
type | string (7) The document type. Valid values are: |
document_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) The unique number associated with document (e.g. passport number). |
additional_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) Some additional unique number (e.g. tax id on government id). |
issue_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) The issue date of the document. (ISO 8601, YYYY-MM-DD) |
expiry_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) The expiry date of the document. (ISO 8601, YYYY-MM-DD) |
issuing_authority GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (255) The authority that issued a document. |
card_number CREDIT_CARD | string (19) Payment credit card number with a minimum length of 12 and a maximum length of 19. Also can be used for determinate mask of credit card number. Example 4540********1265. |
account_number CREDIT_CARD | string (50) Any payment account number like IBAN, etc. |
income_sources FINANCIAL_DOCUMENT BANK_STATEMENT | array One or many income sources. Possible values: SALARY , DIVIDENDS , SALE_PROPERTY , SAVINGS , DIVORCE_SETTLEMENTS , INHERITANCE , LOAN , INVESTMENTS , OTHER . |
annual_income FINANCIAL_DOCUMENT BANK_STATEMENT | string (21) One of annual income group.ANNUAL_INCOME_GROUP_1 - below 50000 EURANNUAL_INCOME_GROUP_2 - 50000 - 100000 EURANNUAL_INCOME_GROUP_3 - 100000 - 300000 EURANNUAL_INCOME_GROUP_4 - above 300000 EUR. |
transaction_amount FINANCIAL_DOCUMENT BANK_STATEMENT | float Amount of transaction. |
transaction_currency FINANCIAL_DOCUMENT BANK_STATEMENT | string (3) Currency code of transaction. Example USD, BTC, etc. (ISO 4217). |
transaction_datetime FINANCIAL_DOCUMENT BANK_STATEMENT | string(19) Date and time of transaction. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
transaction_purpose FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Description of transaction purpose. |
origin_funds FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Description of origin funds. |
front_side_id | string (36) | null The file unique identificator that received in response of Create file. Also, the file id can be set to null for remove a file from a document. |
back_side_id | string (36) | null The file unique identificator that received in response of Create file. Also, the file id can be set to null for remove a file from a document. |
other_side_1_id | string (36) | null The file unique identificator that received in response of Create file. Also, the file id can be set to null for remove a file from a document. |
other_side_2_id | string (36) | null The file unique identificator that received in response of Create file. Also, the file id can be set to null for remove a file from a document. |
curl https://api.kycaid.com/documents/{document_id} \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"type": "PASSPORT",
"document_number": "2367823468",
"issue_date": "2010-10-25",
"expiry_date": "2020-07-10",
"front_side_id": "{file_id}",
"back_side_id": "{file_id}"
}'
Response
Parameter | Description |
---|---|
document_id | string (36) Required The document unique identificator. Received document_id parameter may differ from the initial value if the document is already under verification. In this case copy of document is created automatically. |
{
"document_id": "{document_id}"
}
Get document
Request
URL: https://api.kycaid.com/documents/{document_id}
Method: GET
Parameter | Description |
---|---|
document_id | string (36) The document’s unique identificator. |
curl https://api.kycaid.com/documents/{document_id} \
-H 'Authorization: Token <API_TOKEN>'
-X GET
Response
Parameter | Description |
---|---|
applicant_id PERSON COMPANY | string (36) Required The applicant’s unique identificator. |
document_id | string (36) Required The unique identificator of applicant document. |
type | string (7) Required The document type. Valid values are: |
provider | string Required The document provider. Valid values are:MANUAL - a document provided by applicantRECOGNITION - a document created during recognition of some imageADMIN - a document created by managerUA_BANK_ID - a document provided by Ukraine Bank ID serviceUA_DIIA - a document provided by Ukraine Diia service |
document_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) Required The unique number associated with document (e.g. passport number). |
additional_number GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT TAX_ID_NUMBER | string (50) Required Some additional unique number (e.g. tax id on government id). |
issue_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) Required The issue date of the document. (ISO 8601, YYYY-MM-DD) |
expiry_date GOVERNMENT_ID PASSPORT DRIVERS_LICENSE DOMESTIC_PASSPORT PERMANENT_RESIDENCE_PERMIT REFUGEE_CARD FOREIGN_CITIZEN_PASSPORT | string (10) Required The expiry date of the document. (ISO 8601, YYYY-MM-DD) |
card_number CREDIT_CARD | string (19) Required Payment credit card number with a minimum length of 12 and a maximum length of 19. Also can be used for determinate mask of credit card number. Example 4540********1265. |
account_number CREDIT_CARD | string (50) Required Any payment account number like IBAN, etc. |
income_sources FINANCIAL_DOCUMENT BANK_STATEMENT | array Required One or many income sources. Possible values: SALARY , DIVIDENDS , SALE_PROPERTY , SAVINGS , DIVORCE_SETTLEMENTS , INHERITANCE , LOAN , INVESTMENTS , OTHER . |
annual_income FINANCIAL_DOCUMENT BANK_STATEMENT | string (21) Required One of annual income group.ANNUAL_INCOME_GROUP_1 - below 50000 EURANNUAL_INCOME_GROUP_2 - 50000 - 100000 EURANNUAL_INCOME_GROUP_3 - 100000 - 300000 EURANNUAL_INCOME_GROUP_4 - above 300000 EUR. |
transaction_amount FINANCIAL_DOCUMENT BANK_STATEMENT | float Required Amount of transaction. |
transaction_currency FINANCIAL_DOCUMENT BANK_STATEMENT | string (3) Required Currency code of transaction. Example USD, BTC, etc. (ISO 4217). |
transaction_datetime FINANCIAL_DOCUMENT BANK_STATEMENT | string(19) Required Date and time of transaction. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
transaction_purpose FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Required Description of transaction purpose. |
origin_funds FINANCIAL_DOCUMENT BANK_STATEMENT | string (255) Required Description of origin funds. |
front_side_id | string (36) Required The file unique identificator that received in response of Create file. |
back_side_id | string (36) Required The file unique identificator that received in response of Create file. |
other_side_1_id | string (36) Required The file unique identificator that received in response of Create file. |
other_side_2_id | string (36) Required The file unique identificator that received in response of Create file. |
decline_reasons | list Decline reason Required List of decline reasons receiving only for document has invalid status. |
created_at | string Required Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42". |
{
"document_id": "{document_id}",
"applicant_id": "{applicant_id}",
"type": "PASSPORT",
"provider": "MANUAL",
"status": "invalid",
"document_number": "00000000001",
"additional_number": "00000000002",
"issue_date": "2000-01-01",
"expiry_date": "2020-01-01",
"income_sources": [],
"annual_income": null,
"transaction_amount": null,
"transaction_purpose": null,
"transaction_currency": null,
"transaction_datetime": null,
"origin_funds": null,
"card_number": null,
"account_number": null,
"front_side_id": "{front_side_id}",
"front_side": "{front_side_url}",
"back_side_id": null,
"back_side": null,
"other_side_1_id": null,
"other_side_1": null,
"other_side_2_id": null,
"other_side_2": null,
"created_at": "2020-11-22 14:14:56",
"decline_reasons": [
"EXPIRED_DOCUMENT"
]
}
Remove document
Request
URL: https://api.kycaid.com/documents/{document_id}
Method: DELETE
Documents can be deleted only if they are not under verification.
curl https://api.kycaid.com/documents/{document_id} \
-H 'Authorization: Token <API_TOKEN>' \
-X DELETE
Response
Parameter | Description |
---|---|
document_id | string (36) Required The document unique identificator. |
{
"document_id": "{document_id}"
}
Files
Create file
Request
URL: https://api.kycaid.com/files
Method: POST
Content-Type: multipart/form-data
Parameter | Description |
---|---|
file | binary Required File for upload. |
File requirements
- Supported file formats:
BMP
,GIF
,HEIC
,JPEG
,PNG
,WEBP
andPDF
. - Minimum resolution for image is 480 px.
- Maximum resolution for image is 7000 px.
- Maximum file size is 50 Mb.
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
Response
Parameter | Description |
---|---|
file_id | string (36) Required The file unique identificator. |
{
"file_id": "{file_id}"
}
Update file
Request
URL: https://api.kycaid.com/files/{file_id}
Method: PUT
Content-Type: multipart/form-data
Parameter | Description |
---|---|
file | binary Required File for upload. Supported file formats: BMP , GIF , HEIC , JPEG , PNG , WEBP and PDF . Maximum file size is 50 Mb. |
curl https://api.kycaid.com/files/{file_id} \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X PUT \
-F 'file=@./my_file.jpg'
Response
Parameter | Description |
---|---|
file_id | string (36) Required The file unique identificator. |
{
"file_id": "{file_id}"
}
Remove file
Please do not worry about deleting files, this will happen automatically after 1 month if the file is not used in any of your documents.
Addresses
Address object
Parameter | Description |
---|---|
address_id | string (36) Required The unique identificator of applicant address. |
type | string (7) Required The address type. Valid values are:REGISTERED BUSINESS ADDITIONAL |
full_address | string (255) The applicant’s full address. |
country | string (2) The country of the applicants’s address. Example: GB (ISO 3166-2) |
state_or_province | string (50) The county, state or province of the applicant’s address. |
city | string (50) The city or town of the applicant’s address. |
postal_code | string (20) The post or zip code of the applicant’s address. |
street_name | string (50) The street name for applicant’s address. |
building_number | string (20) The building number for applicant’s address. |
unit_number | string (20) The unit number for applicant’s address. |
{
"address_id": "{address_id}",
"type": "REGISTERED",
"status": "valid",
"full_address": null,
"country": "GB",
"state_or_province": "Westminster",
"city": "London",
"postal_code": "SW1A 2AB",
"street_name": "Downing St",
"building_number": "10",
"unit_number": null,
"created_at": "2020-11-22 14:15:15",
"decline_reasons": []
}
Create address
Request
URL: https://api.kycaid.com/addresses
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
applicant_id APPLICANT | string (36) Required The applicant’s unique identificator that received in response of Create applicant. |
affiliated_person_id AFFILIATED PERSON | string (36) Required The affiliated person’s unique identificator that received in response of Create affiliated person. |
type | string (10) Required The address type. Valid values are:REGISTERED BUSINESS ADDITIONAL |
full_address | string (255) The applicant’s full address. |
country | string (2) The country of the applicants’s address. Example: GB (ISO 3166-2) |
state_or_province | string (50) The county, state or province of the applicant’s address. |
city | string (50) The city or town of the applicant’s address. |
postal_code | string (20) The post or zip code of the applicant’s address. |
street_name | string (50) The street name for applicant’s address. |
building_number | string (20) The building number for applicant’s address. |
unit_number | string (20) The unit number for applicant’s address. |
curl https://api.kycaid.com/addresses \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "{applicant_id}",
"type": "REGISTERED",
"country": "GB",
"state_or_province": "Westminster",
"city": "London",
"postal_code": "SW1A 2AB",
"street_name": "Downing St",
"building_number": "10"
}'
Response
Parameter | Description |
---|---|
address_id | string (36) Required The unique identificator of applicant's address. |
{
"address_id": "{address_id}"
}
Update address
Request
URL: https://api.kycaid.com/addresses/{address_id}
Method: PATCH
Content-Type: application/json
Parameter | Description |
---|---|
type | string (10) The address type. Valid values are:REGISTERED BUSINESS ADDITIONAL |
full_address | string (255) The applicant’s full address. |
country | string (2) The country of the applicants’s address. Example: GB (ISO 3166-2) |
state_or_province | string (50) The county, state or province of the applicant’s address. |
city | string (50) The city or town of the applicant’s address. |
postal_code | string (20) The post or zip code of the applicant’s address. |
street_name | string (50) The street name for applicant’s address. |
building_number | string (20) The building number for applicant’s address. |
unit_number | string (20) The unit number for applicant’s address. |
curl https://api.kycaid.com/addresses/{address_id} \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"country": "GB",
"state_or_province": "Westminster",
"city": "London",
"postal_code": "SW1A 2AB",
"street_name": "Downing St",
"building_number": "10"
}'
Response
Parameter | Description |
---|---|
address_id | string (36) Required The unique identificator of applicant's address. Received address_id parameter may differ from the initial value if the address is already under verification. In this case copy of address is created automatically. |
{
"address_id": "{address_id}"
}
Remove address
Request
URL: https://api.kycaid.com/addresses/{address_id}
Method: DELETE
Address can be deleted only if they are not under verification.
curl https://api.kycaid.com/addresses/{address_id} \
-H 'Authorization: Token <API_TOKEN>' \
-X DELETE
Response
Parameter | Description |
---|---|
address_id | string (36) Required The address unique identificator. |
{
"address_id": "{address_id}"
}
Affiliated persons
Create affiliated person
Request
URL: https://api.kycaid.com/affiliated-persons
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
type | string Required The type of affiliated person. Valid values are:AUTHORISED BENEFICIAL |
applicant_id | string (36) Required The applicant unique identificator that received in response of Create applicant request. |
first_name | string (50) Required The first name of affiliated person. |
last_name | string (50) Required The last name of affiliated person. |
title AUTHORISED | string (36) Required The title of affiliated person. |
share BENEFICIAL | float Required Affiliated persons shares. Available values between 0 and 100. |
dob | string (10) Required The affiliated person’s date of birth. (ISO 8601, YYYY-MM-DD) |
residence_country | string (2) Required The affiliated person current nationality. Example: GB (ISO 3166-2) |
email | string (254) Required The affiliated person email address. |
curl https://api.kycaid.com/affiliated-persons \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "AUTHORISED",
"applicant_id": "{applicant_id}",
"first_name": "John",
"last_name": "Doe",
"title": "CEO",
"dob": "1970-10-25",
"residence_country": "GB",
"email": "john.doe@mail.com"
}'
Response
Parameter | Description |
---|---|
affiliated_person_id | string (36) Required The unique identificator of affiliated person. |
{
"affiliated_person_id": "{affiliated_person_id}"
}
Update affiliated person
Request
URL: https://api.kycaid.com/affiliated-persons/{affiliated_person_id}
Method: PATCH
Content-Type: application/json
Parameter | Description |
---|---|
first_name | string (50) The first name of affiliated person. |
last_name | string (50) The last name of affiliated person. |
title AUTHORISED | string (36) The title of affiliated person. |
share BENEFICIAL | float Affiliated persons shares. Available values between 0 and 100. |
dob | string (10) The affiliated person’s date of birth. (ISO 8601, YYYY-MM-DD) |
residence_country | string (2) The affiliated person current nationality. Example: GB (ISO 3166-2) |
email | string (254) The affiliated person email address. |
curl https://api.kycaid.com/affiliated-persons/{affiliated_person_id} \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"type": "AUTHORISED",
"first_name": "John",
"last_name": "Doe",
"title": "CEO",
"dob": "1970-10-25",
"residence_country": "GB",
"email": "john.doe@mail.com"
}'
Response
Parameter | Description |
---|---|
affiliated_person_id | string (36) Required The unique identificator of affiliated person. |
{
"affiliated_person_id": "{affiliated_person_id}"
}
Remove affiliated person
Request
URL: https://api.kycaid.com/affiliated-persons/{affiliated_person_id}
Method: DELETE
Affiliated person can be deleted only if they are not under verification.
curl https://api.kycaid.com/affiliated-persons/{affiliated_person_id} \
-H 'Authorization: Token <API_TOKEN>' \
-X DELETE
Response
Parameter | Description |
---|---|
affiliated_person_id | string (36) Required The affiliated person unique identificator. |
{
"affiliated_person_id": "{affiliated_person_id}"
}
Verifications
Create verification
Request
URL: https://api.kycaid.com/verifications
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
applicant_id | string (36) Required The applicant unique identificator that received in response of Create applicant request. |
form_id | string (36) Required The form unique identificator (can be taken in customer dashboard). Used for inheritance of form configuration like ACR and email templates. |
language_code | string (2) Defined applicant language. Helps to determine the locale of the applicant when contacting him. Also, the language can be automatically determined based on the values in the "Accept-Language" headers if this parameter is absent. Default value is "EN" (ISO 639-1). |
Verification types
Name | Required data |
---|---|
Document verification DOCUMENT |
|
Facial verification FACIAL |
|
Address verification ADDRESS |
|
Tax ID verification TAX_ID |
|
AML check AML |
|
Payment method check PAYMENT_METHOD |
|
Video check VIDEO |
|
Database screening DATABASE_SCREENING | One of the next parameters are required:
|
curl https://api.kycaid.com/verifications \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "{applicant_id}",
"form_id": "{form_id}"
}'
Response
Parameter | Description |
---|---|
verification_id | string (36) Required The verification’s unique identificator which assist to identify verification during receiving callback after verification will be completed. |
Maximum 20 verifications for one applicant.
{
"verification_id": "{verification_id}"
}
Get verification
Request
URL: https://api.kycaid.com/verifications/{verification_id}
Method: GET
curl https://api.kycaid.com/verifications/{verification_id} \
-H 'Authorization: Token <API_TOKEN>'
Response
Parameter | Description |
---|---|
applicant_id | string (36) Required The applicant unique identificator that received in response of Create applicant request. |
verification_id | string (36) Required The verification’s unique identificator. |
status | string (9) Required Status of verification. Possible values:unused - the applicant has not yet filled out a formpending - verification of the applicant in progresscompleted - verification is completed |
verified | boolean Required Result of verification. Possible values:true - the applicant passed verificationfalse - the applicant failed verification |
verifications | VerificationsList Required VerificationsList object |
VerificationsList
Parameter | Description |
---|---|
profile | document | facial | address | aml | financial | payment_method | tax_id | database_screening | company | VerificationResult Required VerificationResult object |
VerificationResult
Parameter | Description |
---|---|
verified | boolean Required Result of particular verification. Possible values:true - the verification passedfalse - the verification failed |
comment | string (255) Accompanying verification comment. May not always be provided. |
{
applicant_id: <applicant_id>,
verification_id: <verification_uid>,
status: unused|pending|completed,
verified: true|false,
verifications: {
<verification_type>: {
verified: true|false,
comment: <some comment text>
}
}
}
{
"verification_id": "{verification_id}",
"status": "pending"
}
{
"verification_id": "{verification_id}",
"status": "completed",
"verified": true,
"verifications": {
"document": {
"verified": true,
"comment": ""
},
"address": {
"verified": true,
"comment": ""
}
}
}
Verification callback
Request
URL: <callback_url>
Method: POST
Content-Type: application/json
callback_url
parameter that was set in Create verification request, once verification will be completed. Verify callback will be in the JSON format and they will contain the following format:Parameter | Description |
---|---|
request_id | string (36) Required The unique identificator of callback request. |
type | string Required Type of callback. Possible types:VERIFICATION_COMPLETED - the type of callback that notifies about the end of verification. |
verification_id | string (36) Required The verification’s unique identificator. |
applicant_id | string (36) Required The applicant unique identificator. |
status | string (9) Required Status of verification. Possible values:unused - the applicant has not yet filled out a formpending - verification of the applicant in progresscompleted - verification is completed |
verified | boolean Required Result of verification. Possible values:true - the applicant passed verificationfalse - the applicant failed verification |
verifications | VerificationsList Required VerificationsList object |
applicant | Applicant object is returned only if parameter return_applicant was setup with value true for Create verification request. |
Attention. The callback request also include client's API token in http header, that have to be matched from client side by security reasons.
{
"request_id": "{request_id}",
"type": "VERIFICATION_COMPLETED",
"verification_id": "{verification_id}",
"applicant_id": "{applicant_id}",
"status": "completed",
"verified": false,
"verifications": {
"profile": {
"verified": true,
"comment": "",
"decline_reasons": []
},
"document": {
"verified": false,
"comment": "Your document has expired. Please, resubmit the form and upload the valid ID.",
"decline_reasons": []
}
}
}
Response
2xx
is treating as a success sending callback to customer server. Otherwise KYCAID server will repeat callback attempts with such time intervals: 60
, 300
, 600
, 3600
, 86400
seconds.Decline reasons
Verifications decline reasons
Code | Type | Description |
---|---|---|
OTHER | PROFILE DOCUMENT FACIAL ADDRESS AML PAYMENT_METHOD TAX_ID VIDEO COMPANY | Some other reason. |
WRONG_NAME | PROFILE DOCUMENT | Name/Last name is different from the one specified in the document provided. |
WRONG_DOB | PROFILE DOCUMENT | Date of Birth is different from the one specified in the document provided. |
AGE_RESTRICTION | PROFILE DOCUMENT FACIAL TAX_ID | The applicant is under allowed age. |
EXPIRED_DOCUMENT | DOCUMENT | The document has expired. |
EXPIRES_LESS_3_MONTHS | DOCUMENT ADDRESS AML | The document expires in less than 3 months. |
BAD_QUALITY | PROFILE DOCUMENT FACIAL ADDRESS AML PAYMENT_METHOD TAX_ID | The document is not visible or the quality of the document image is low. |
FAKE_DOCUMENT | DOCUMENT FACIAL ADDRESS AML PAYMENT_METHOD TAX_ID COMPANY | The document contains signs of forgery. |
WRONG_INFO | DOCUMENT | The information differs from the one stated in the document. |
PROHIBITED_JURISDICTION | PROFILE DOCUMENT ADDRESS AML PAYMENT_METHOD TAX_ID COMPANY | The document is issued in the prohibited jurisdiction. |
NO_SELFIE | FACIAL | The selfie image was not provided. |
DIFFERENT_FACES | FACIAL | The faces on selfie and in the document are different. |
WRONG_DOCUMENT | DOCUMENT FACIAL ADDRESS PAYMENT_METHOD TAX_ID COMPANY | The document does not match the applicant. |
DUPLICATE | PROFILE DOCUMENT FACIAL | This applicant was already created for this client, duplicates are not allowed. |
DOCUMENT_DAMAGED | DOCUMENT ADDRESS TAX_ID | Document is damaged. |
DOCUMENT_INCOMPLETE | DOCUMENT ADDRESS PAYMENT_METHOD TAX_ID | Document is incomplete. |
COMPROMISED_PERSON | DATABASE_SCREENING | The applicant was found in the database. |
Documents decline reasons
Code | Type | Description |
---|---|---|
OTHER | Some other reason. | |
WRONG_NAME | Name/Last name is different from the one specified in the document provided. | |
WRONG_DOB | Date of Birth is different from the one specified in the document provided. | |
AGE_RESTRICTION | The applicant is under allowed age. | |
EXPIRED_DOCUMENT | The document has expired. | |
EXPIRES_LESS_3_MONTHS | The document expires in less than 3 months. | |
BAD_QUALITY | The document is not visible or the quality of the document image is low. | |
FAKE_DOCUMENT | The document contains signs of forgery. | |
WRONG_INFO | The information differs from the one stated in the document. | |
PROHIBITED_JURISDICTION | The document is issued in the prohibited jurisdiction. | |
NO_SELFIE | The selfie image was not provided. | |
DIFFERENT_FACES | The faces on selfie and in the document are different. | |
WRONG_DOCUMENT | The document does not match the applicant. | |
DUPLICATE | This applicant was already created for this client, duplicates are not allowed. | |
DOCUMENT_DAMAGED | Document is damaged. | |
DOCUMENT_INCOMPLETE | Document is incomplete. | |
FRAUDULENT | Fraudulent behavior. | |
TAX_ID_REQUIRED | Tax ID is required. | |
COMPROMISED_PERSON | The applicant was found in the database. |
Get verifications report
Request
URL: https://api.kycaid.com/verifications/report
Method: GET
Parameter | Description |
---|---|
date | string (10) Required The date on which you need to receive the report. |
offset | integer Pagination offset for items in list. Default value is 0 . It can be used for pagination. |
count | integer Count for items in list. Default value is 1000 . Maximum value is 1000 . It can be used for pagination. |
curl https://api.kycaid.com/verifications/report?date=2023-01-31 \
-H 'Authorization: Token <API_TOKEN>'
Response
VerificationsReportObject
Parameter | Description |
---|---|
created_at KYC KYB SERVICE | string (19) Required Date and time when verification was created. |
verification_id KYC KYB SERVICE | string (36) Required The verification’s unique identificator. |
applicant_id KYC KYB | string (36) The applicant’s unique identificator. |
external_applicant_id KYC KYB | string (50) Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems. |
form_id KYC KYB | string (36) The form’s unique identificator. |
status KYC KYB SERVICE | string (10) Required Verification status. |
service KYC KYB SERVICE | string (10) Required Type of service. Possible values:KYC - KYC verificationKYB - KYB verificationSERVICE - Service (e.g. BR_CPF service) |
method KYC KYB SERVICE | string (10) Required Method of service. Possible values:UA_BANK_ID - Ukraine BankId (PrivatBank)UA_BANK_ID_2 - Ukraine BankId (id.gov.ua)UA_DIIA - Ukraine DiiaAUTOMATION_CHECK - Verification was processed automated.MANUAL_CHECK - Verification was processed manualy.UNKNOWN - Uknown method of verification.BR_CPF - Brazilian CPF service. |
name KYC KYB SERVICE | string (255) Required The name of applicant or service. |
dob KYC KYB | string (10) The applicant’s date of birth date. (ISO 8601, YYYY-MM-DD) |
country_code KYC KYB | string (2) The residence/registration country of applicant. Example: GB (ISO 3166-2) |
tax_id_number KYC KYB | string (2) The residence/registration country of applicant. Example: GB (ISO 3166-2) |
email KYC KYB | string (254) The applicant's email address. |
phone KYC KYB | string (15) The phone number of applicant. |
wallet_address KYC KYB | string (50) The applicant’s cryptocurrency wallet address. |
telegram_username KYC KYB | string (32) The applicant’s Telegram username. |
verification_types KYC KYB SERVICE | array Required The list of verification types. |
decline_reasons KYC KYB | array The list of decline reasons. |
processing_time KYC KYB SERVICE | integer Required Time (in seconds) was spent on verification processing. |
price KYC KYB SERVICE | string (10) Required Price (in euro cents) of verification. |
mode KYC KYB SERVICE | string (10) Required Mode of verification. Possible two values:TEST - testing modeLIVE - production mode |
[
{
"created_at": <created_at>,
"verification_id": <verification_id>,
"applicant_id": <applicant_id>,
"external_applicant_id": <external_applicant_id>,
"form_id": <form_id>,
"name": <name>,
"dob": <dob>,
"country_code": <country_code>,
"tax_id_number": <tax_id_number>,
"email": <email>,
"phone": <phone>,
"wallet_address": <wallet_address>,
"telegram_username": <telegram_username>,
"status": <status>,
"service": <service>,
"method": <method>,
"verification_types": [],
"decline_reasons": [],
"processing_time": <processing_time>,
"price": <price>,
"mode": <mode>
},
...
]
External verifications
Ukrainian BankId
2. The customer`s server sends create external verification request to KYCAID API server.
3. The customer`s client opens the received url in create external verification response.
4. The user returns to the specified URL (
redirect_url
) after passing verification in a third-party service.5. KYCAID server sends the verification callback to the customer's server.
6. The customer server is sending success response (http status 200) as a sign of getting a successful verification result.
Notes
- It is not always possible to return to the native application after passing the verification through BankId. In this case, you can use get external verification request to determine when the user has fully completed BankId flow.
- Recommended delay between get external verification requests is 2 seconds.
Create external verification
Request
URL: https://api.kycaid.com/external-verifications
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
type | string Required The external verification types. Valid values are:UA_BANK_ID UA_DIIA |
form_id | string (36) Required The form’s unique identificator. |
applicant_id | string (36) The applicant unique identificator that received in response of Create applicant request. |
external_applicant_id | string (50) Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems. |
language_code | string (2) Defined applicant language. Helps to determine the locale of the applicant when contacting him. Example: EN (ISO 639-1) |
curl https://api.kycaid.com/external-verifications \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "UA_BANK_ID",
"applicant_id": "{applicant_id}",
"form_id": "{form_id}",
}'
Response
Parameter | Description |
---|---|
external_verification_id | string (36) Required The external verification’s unique identificator which assists to identify status of external verification during processing of it. |
verification_id | string (36) Required The verification’s unique identificator which assists to identify verification during receiving callback after verification will be completed. |
applicant_id | string (36) Required The unique identifier of the applicant, which must be saved in the client's database and used to bind the client's user to the KYCAID applicant. |
request | RequestObject Required The verification’s unique identificator which assists to identify verification during receiving callback after verification will be completed. |
additional_requests | List of additional requests. For instance, separate requests for each verification provider. |
RequestObject
Parameter | Description |
---|---|
method | string Required HTTP Request Method. Supported values: GET , POST . |
url | string Required The URL to use for the request. |
AdditionalRequestObject
Parameter | Description |
---|---|
type | string Required Type of verification provider. Supported values: PRIVATBANK , MONOBANK . |
method | string Required HTTP Request Method. Supported values: GET , POST . |
url | string Required The URL to use for the request. |
Maximum 20 verifications for one applicant.
UA_BANK_ID
- The link lifetime is 3 minutes. After the expiration of the period, you need to send request one more time to create an external verification.
UA_DIIA
- The link lifetime is 3 minutes. After the expiration of the period, you need to send request one more time to create an external verification.
{
"external_verification_id": "{external_verification_id}",
"verification_id": "{verification_id}",
"applicant_id": "{applicant_id}",
"request": {
"method": "GET",
"url": "{url}"
},
"additional_requests": [
{
"type": "PRIVATBANK",
"method": "GET",
"url": "{url}"
},
{
"type": "MONOBANK",
"method": "GET",
"url": "{url}"
}
]
}
Get external verification
Request
URL: https://api.kycaid.com/external-verifications/{external_verification_id}
Method: GET
curl https://api.kycaid.com/external-verifications/{external-verifications} \
-H 'Authorization: Token <API_TOKEN>'
Response
Parameter | Description |
---|---|
external_verification_id | string (36) Required The external verification’s unique identificator which assist to identify status of external verification during processing of it. |
status | string Required Status of external verification. Possible values:pending - verification is in progresscompleted - verification was completed |
{
external_verification_id: <external_verification_id>,
status: pending|completed
}
Callbacks
Callback types
Type | Description |
---|---|
VERIFICATION_STATUS_CHANGED | Occurs whenever a verification status is changed. Mostly, it using to identify when verification is created. |
VERIFICATION_COMPLETED | Occurs whenever a verification is completed. |
VERIFICATION_STATUS_CHANGED
URL: <callback_url>
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
request_id | string (36) Required The unique identificator of callback request. |
type | string Required VERIFICATION_COMPLETED - type of callback |
verification_id | string (36) Required The verification’s unique identificator. |
applicant_id | string (36) Required The applicant unique identificator. |
verification_status | string (9) Required Status of verification. Possible values:unused - the applicant has not yet filled out a formpending - verification of the applicant in progresscompleted - verification is completed |
{
"request_id": "{request_id}",
"type":"VERIFICATION_STATUS_CHANGED",
"applicant_id":"{applicant_id}",
"verification_id":"{verification_id}",
"form_id":"{form_id}",
"verification_status":"pending"
}
VERIFICATION_COMPLETED
URL: <callback_url>
Method: POST
Content-Type: application/json
callback_url
parameter that was set in Create verification request, once verification will be completed. Verify callback will be in the JSON format and they will contain the following format:Parameter | Description |
---|---|
request_id | string (36) Required The unique identificator of callback request. |
type | string Required Type of callback. Possible types:VERIFICATION_COMPLETED - the type of callback that notifies about the end of verification. |
verification_id | string (36) Required The verification’s unique identificator. |
applicant_id | string (36) Required The applicant unique identificator. |
status | string (9) Required Status of verification. Possible values:unused - the applicant has not yet filled out a formpending - verification of the applicant in progresscompleted - verification is completed |
verified | boolean Required Result of verification. Possible values:true - the applicant passed verificationfalse - the applicant failed verification |
verifications | VerificationsList Required VerificationsList object |
applicant | Applicant object is returned only if parameter return_applicant was setup with value true for Create verification request. |
verification_statuses.duplicates | List of List of found duplicates during applicant verification.applicant_id Required |
verification_statuses.ludoman | boolean or null A parameter that determines whether the applicant is a ludoman or not. |
{
"request_id": "{request_id}",
"type": "VERIFICATION_COMPLETED",
"verification_id": "{verification_id}",
"applicant_id": "{applicant_id}",
"status": "completed",
"verified": false,
"verifications": {
"profile": {
"verified": true,
"comment": "",
"decline_reasons": []
},
"document": {
"verified": false,
"comment": "Your document has expired. Please, resubmit the form and upload the valid ID.",
"decline_reasons": []
}
},
"verification_statuses": {
"duplicates": ["duplicate_applicant_id_1", "duplicate_applicant_id_2"],
"ludoman": false
}
}
Callback response
2xx
is treating as a success sending callback to customer server. Otherwise KYCAID server will repeat callback attempts with such time intervals: 1 minute
, 5 minutes
, 10 minutes
, 30 minutes
, 1 hour
, 3 hours
, 6 hours
, 12 hours
, 24 hours
.Verify callback
How to verify:
Example
{"request_id":"61a7dbcc012d9042e909cf006e7b412d6ba5","type":"VERIFICATION_STATUS_CHANGED","applicant_id":"4141cc1b18dba048470b2961cb4592f480fe","verification_id":"2cf795e713be1040e50b202164ee17bfdfbe","form_id":"58bed87600dd9944f02ba0c9cd8b32d6bd4c","verification_status":"pending"}
eyJyZXF1ZXN0X2lkIjoiNjFhN2RiY2MwMTJkOTA0MmU5MDljZjAwNmU3YjQxMmQ2YmE1IiwidHlwZSI6IlZFUklGSUNBVElPTl9TVEFUVVNfQ0hBTkdFRCIsImFwcGxpY2FudF9pZCI6IjQxNDFjYzFiMThkYmEwNDg0NzBiMjk2MWNiNDU5MmY0ODBmZSIsInZlcmlmaWNhdGlvbl9pZCI6IjJjZjc5NWU3MTNiZTEwNDBlNTBiMjAyMTY0ZWUxN2JmZGZiZSIsImZvcm1faWQiOiI1OGJlZDg3NjAwZGQ5OTQ0ZjAyYmEwYzljZDhiMzJkNmJkNGMiLCJ2ZXJpZmljYXRpb25fc3RhdHVzIjoicGVuZGluZyJ9
f7681b097b77928fc031d614709976796057c306cf77fdd449bb414937bd87678d908d7efaa65e9b1dd65b9eeea2121ea75bd9007f44fe8fcd7c9ac6cdeeef0e
Forms
Get form URL
Request
URL: https://api.kycaid.com/forms/{form_id}/urls
Method: POST
Content-Type: application/json
Parameter | Description |
---|---|
applicant_id | string (36) The applicant unique identificator that received in response of Create applicant request. It's supposed to use when need to create verification for exists applicant. |
external_applicant_id | string (50) Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems. |
redirect_url | string (2048) The customer site URL, where applicant will be redirected after completing filling the form. |
curl https://api.kycaid.com/forms/{form_id}/urls \
-H 'Authorization: Token <API_TOKEN>' \
-X POST \
-d '{
"applicant_id": "{applicant_id}",
"external_applicant_id": "{external_applicant_id}",
"redirect_url": "https://site.com/success-kyc"
}'
Response
Parameter | Description |
---|---|
form_id | string (36) Required The form’s unique identificator. |
form_url | string (2048) Required One-time URL to the verification form. This URL will be available until applicant will not complete the form. |
verification_id | string (36) Required The verification’s unique identificator. |
For the setup initial language of form UI, you need to add URL parameter
lang
. Possible values: de
, en
, es
, fr
, kk
, pt
, uk
, ru
. Example: https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024/?lang=en
For the correct operation of the camera in the iframe, you need to add the attribute
allow="microphone *;camera *;midi *;encrypted-media *;"
to iframe.
{
"form_id": "{form_id}",
"form_url": "https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024",
"verification_id": "{verification_id}"
}
Additional
Get business activities
URL: https://api.kycaid.com/business-activities
Method: GET
curl https://api.kycaid.com/business-activities \
-H 'Authorization: Token <API_TOKEN>' \
-X GET
Response
BusinessCategoryObject
Parameter | Description |
---|---|
business_category_id | string (36) Required The unique identifier for the business category. |
labels | array Required List of BusinessCategoryLabelObjects. |
activities | array Required List of BusinessActivityObjects. |
BusinessCategoryLabelObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: EN (ISO 639-1) |
label | string (50) Required Business category name on specific language. |
BusinessActivityObject
Parameter | Description |
---|---|
business_activity_id | string (36) Required The unique identifier for the business activity which should be used for business_activity parameter during creation of applicant and other calls. |
labels | array Required List of BusinessActivityLabelObjects. |
BusinessActivityLabelObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: EN (ISO 639-1) |
label | string (50) Required Business activity name on specific language. |
[
{
business_category_id: <business_category_id>,
labels: [
{
language_code: <language_code>,
label: <business_category_name>
},
...
],
activities: [
{
business_activity_id: <business_activity_id>,
labels: [
{
language_code: <language_code>,
label: <business_activity_name>
},
...
],
}
]
},
...
]
[
{
"business_category_id": "3589f557065bc649ff2acc1407991fbbbfa0",
"labels": [
{
"label": "Arts, entertainment and recreation",
"language_code": "EN"
},
{
"label": "Искусство, развлечения и отдых",
"language_code": "RU"
},
{
"label": "Мистецтво, розваги та відпочинок",
"language_code": "UK"
}
],
"activities": [
{
"business_activity_id": "bfceccf606c7d645b5299804467c82c078b4",
"labels": [
{
"label": "Performing arts",
"language_code": "EN"
},
{
"label": "Исполнительское искусство",
"language_code": "RU"
},
{
"label": "Виконавче мистецтво",
"language_code": "UK"
}
]
}
]
}
]
Get countries
URL: https://api.kycaid.com/countries
Method: GET
curl https://api.kycaid.com/countries \
-H 'Authorization: Token <API_TOKEN>' \
-X GET
Response
CountryObject
Parameter | Description |
---|---|
country_code | string (2) Required The country code which should be used for residence_country and registration_country parameters during creation of applicant and other calls. Example: GB (ISO 3166-2) |
labels | array Required List of CountryLabelObjects. |
CountryLabelObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: EN (ISO 639-1) |
label | string (50) Required Country name on specific language. |
[
{
country_code: <country_code>,
labels: [
{
language_code: <language_code>,
label: <country_name>
},
...
]
},
...
]
[
{
"country_code": "AD",
"labels": [
{
"language_code": "EN",
"label": "Andorra"
},
{
"language_code": "RU",
"label": "Андорра"
},
{
"language_code": "UK",
"label": "Андорра"
}
]
}
]
Get languages
URL: https://api.kycaid.com/languages
Method: GET
curl https://api.kycaid.com/languages \
-H 'Authorization: Token <API_TOKEN>' \
-X GET
Response
LanguageObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: en (ISO 639-1) |
labels | array Required List of LanguageLabelObjects. |
LanguageLabelObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: en (ISO 639-1) |
label | string (50) Required Locale name on specific language. |
[
{
language_code: <language_code>,
labels: [
{
language_code: <language_code>,
label: <language_name>
},
...
]
},
...
]
[
{
"language_code": "en",
"labels": [
{
"language_code": "en",
"label": "English"
},
{
"language_code": "ru",
"label": "Английский"
},
{
"language_code": "uk",
"label": "Англійська"
}
]
}
]
Services
Brazilian CPF
URL: https://api.kycaid.com/services/br/cpf/{cpf_number}
Method: GET
curl https://api.kycaid.com/services/br/cpf/{cpf_number} \
-H 'Authorization: Token <API_TOKEN>' \
-X GET
Request
Parameter | Description |
---|---|
cpf_number | string (11) Required CPF number. Example: 123456778901, but not 123.456.789-01. |
Response
Parameter | Description |
---|---|
validation.valid | boolean Required Result of CPF number validation. |
data.number | string Required CPF number. |
data.name | string (50) Name |
data.first_name | string (50) First name |
data.last_name | string (50) Last name |
data.dob | string (10) Date of birth |
data.gender | string (1) Gender |
{
"validation": {
"valid": {status}
},
"data": {
"number": "{number}",
"name": "{name}",
"first_name": "{first_name}",
"last_name": "{last_name}",
"dob": "{dob}",
"gender": "{gender}"
}
}
Get countries
URL: https://api.kycaid.com/countries
Method: GET
curl https://api.kycaid.com/countries \
-H 'Authorization: Token <API_TOKEN>' \
-X GET
Response
CountryObject
Parameter | Description |
---|---|
country_code | string (2) Required The country code which should be used for residence_country and registration_country parameters during creation of applicant and other calls. Example: GB (ISO 3166-2) |
labels | array Required List of CountryLabelObjects. |
CountryLabelObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: EN (ISO 639-1) |
label | string (50) Required Country name on specific language. |
[
{
country_code: <country_code>,
labels: [
{
language_code: <language_code>,
label: <country_name>
},
...
]
},
...
]
[
{
"country_code": "AD",
"labels": [
{
"language_code": "EN",
"label": "Andorra"
},
{
"language_code": "RU",
"label": "Андорра"
},
{
"language_code": "UK",
"label": "Андорра"
}
]
}
]
Get languages
URL: https://api.kycaid.com/languages
Method: GET
curl https://api.kycaid.com/languages \
-H 'Authorization: Token <API_TOKEN>' \
-X GET
Response
LanguageObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: en (ISO 639-1) |
labels | array Required List of LanguageLabelObjects. |
LanguageLabelObject
Parameter | Description |
---|---|
language_code | string (2) Required Language code. Example: en (ISO 639-1) |
label | string (50) Required Locale name on specific language. |
[
{
language_code: <language_code>,
labels: [
{
language_code: <language_code>,
label: <language_name>
},
...
]
},
...
]
[
{
"language_code": "en",
"labels": [
{
"language_code": "en",
"label": "English"
},
{
"language_code": "ru",
"label": "Английский"
},
{
"language_code": "uk",
"label": "Англійська"
}
]
}
]
Examples
KYC
Step 1. Create applicant
PERSON
. Details
curl https://api.kycaid.com/applicants \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "PERSON",
"first_name": "John",
"last_name": "Doe",
"dob": "1970-10-25",
"residence_country": "GB",
"email": "john.doe@mail.com"
}'
{
"applicant_id": "<applicant_id>"
}
Step 2. Create applicant document
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "PASSPORT",
"document_number": "2367823468",
"issue_date": "2010-10-25",
"expiry_date": "2025-07-10",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 3. Create applicant selfie
SELFIE_IMAGE
. Details
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "SELFIE_IMAGE",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 4. Create verification
curl https://api.kycaid.com/verifications \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"form_id": "<form_id>"
}'
{
"verification_id": "<verification_id>"
}
KYB
Step 1. Create applicant
COMPANY
. Details
curl https://api.kycaid.com/applicants \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "COMPANY",
"business_activity_id": "<business_activity_id>",
"company_name": "Apple Inc.",
"email": "support@apple.com"
"phone": "4089961010",
"registration_country": "US"
}'
{
"applicant_id": "<applicant_id>"
}
Step 2. Create applicant business address
curl https://api.kycaid.com/addresses \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "BUSINESS",
"full_address": "Apple, One Apple Park Way, Cupertino, CA 95014"
}'
{
"address_id": "<address_id>"
}
Step 3. Create applicant registered address
curl https://api.kycaid.com/addresses \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "REGISTERED",
"full_address": "Apple, One Apple Park Way, Cupertino, CA 95014"
}'
{
"address_id": "<address_id>"
}
Step 4. Create registration company document
REGISTRATION_COMPANY
. Details
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "REGISTRATION_COMPANY",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 5. Create legal address document
COMPANY_LEGAL_ADDRESS
. Details
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "COMPANY_LEGAL_ADDRESS",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 6. Create authorised person document
AUTHORISED_PERSON
. Details
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "AUTHORISED_PERSON",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 7. Create company ownership document
COMPANY_OWNERSHIP
. Details
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"type": "COMPANY_OWNERSHIP",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 8. Create authorised person
AUTHORISED
. Details
curl https://api.kycaid.com/affiliated-persons \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "AUTHORISED",
"applicant_id": "<applicant_id>",
"first_name": "John",
"last_name": "Doe",
"title": "CEO",
"dob": "1970-10-25",
"residence_country": "GB",
"email": "john.doe@mail.com"
}'
{
"affiliated_person_id": "<affiliated_person_id>"
}
Step 9. Create authorised person document
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"affiliated_person_id": "<affiliated_person_id>",
"type": "PASSPORT",
"document_number": "2367823468",
"issue_date": "2010-10-25",
"expiry_date": "2025-07-10",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 10. Create authorised person address
curl https://api.kycaid.com/addresses \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"affiliated_person_id": "<affiliated_person_id>",
"type": "REGISTERED",
"country": "GB",
"state_or_province": "Westminster",
"city": "London",
"postal_code": "SW1A 2AB",
"street_name": "Downing St",
"building_number": "10"
}'
{
"address_id": "<address_id>"
}
Step 11. Create beneficial person
BENEFICIAL
. Details
curl https://api.kycaid.com/affiliated-persons \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"type": "BENEFICIAL",
"applicant_id": "<applicant_id>",
"first_name": "John",
"last_name": "Doe",
"title": "CEO",
"dob": "1970-10-25",
"residence_country": "GB",
"email": "john.doe@mail.com"
}'
{
"affiliated_person_id": "<affiliated_person_id>"
}
Step 12. Create beneficial person document
curl https://api.kycaid.com/files \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: multipart/form-data' \
-X POST \
-F 'file=@./my_file.jpg'
{
"file_id": "<file_id>"
}
curl https://api.kycaid.com/documents \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"affiliated_person_id": "<affiliated_person_id>",
"type": "PASSPORT",
"document_number": "2367823468",
"issue_date": "2010-10-25",
"expiry_date": "2025-07-10",
"front_side_id": "<file_id>"
}'
{
"document_id": "<document_id>"
}
Step 13. Create beneficial person address
curl https://api.kycaid.com/addresses \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"affiliated_person_id": "<affiliated_person_id>",
"type": "REGISTERED",
"country": "GB",
"state_or_province": "Westminster",
"city": "London",
"postal_code": "SW1A 2AB",
"street_name": "Downing St",
"building_number": "10"
}'
{
"address_id": "<address_id>"
}
Step 14. Create verification
COMPANY
type. Details
curl https://api.kycaid.com/verifications \
-H 'Authorization: Token <API_TOKEN>' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"applicant_id": "<applicant_id>",
"form_id": "<form_id>"
}'
{
"verification_id": "<verification_id>"
}