Guides

API integration

1. The customer`s application shows his own form with all needed fields for particular types of verifications.
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

Forms integration

1. Customer should create form with appropriate configurations in his dashboard.
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.
1. The next JS script should be included in the 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 callback VERIFICATION_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

The KYCAID API is used to submit verification requests with your customer’s identity document and we send you the verification result back.
  • 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

The API uses token-based authentication. You will be provided with a token which must be included in the header of all requests made to the API.
Request example
                    # 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

The test mode is no different from the live mode except for the fact that the priority for processing such verifications is low. You can also track test verifications on the verifications page in your account.

For enabling of test mode, all you need to do is use the API test token instead of production token, which you can find on the settings page in your account.

Limits

Maximum 3 verifications for one applicant.
The creation of applications can not exceed 3 times per minute and 20 times within 24 hours.
The creation of verifications can not exceed 3 times per minute and 20 times within 24 hours.

Auto verify

For immediate verification, you can use auto verification. To do this, you need to create an applicant with the appropriate data (see table below) and create verification with needed types.
TypeStatusValues
KYCApprovefirst_name: John
last_name: Snow
KYCDeclinefirst_name: John
last_name: Doe
KYBApprovecompany_name: SpaceX
KYBDeclinecompany_name: Roscosmos

Errors

The API uses standard HTTP response codes to indicate the status of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, the authentication header is missing, etc.), and codes in the 5xx range indicate an error with the server.

Error codes

CodeTypeDescription
400bad_requestYour request could not be processed, there should be more details in the response.
infected_fileThe antivirus has identified the file as not trustworthy.
limit_file_sizeThe file is too large.
401unauthorizedInvalid authorization token.
inactive_accountAccount was blocked.
402insufficient_fundsFunds are not enough to do some action.
403forbidden_duplicates_retriesBlock retries for duplicates.
forbidden_age_restricted_retriesBlock retries for restricted by age.
forbidden_country_restricted_retriesBlock retries for restricted by country.
forbidden_compromised_person_retriesBlock retries for compromised person.
forbidden_fake_document_retriesBlock retries for for cases where applicant provided fake or edited documents.
404not_foundURL or some entry not found
408request_timeoutThe server timed out waiting for the request.
409duplicate_dataFor instance when verification request has been submitted already.
flowSome action that contradicts the functional flow.
edit_deniedThe entry can not be edited.
delete_deniedThe entry can not be deleted.
422validationResponse 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_existsApplication already exists.
incompatible_file_for_recognitionFile can not be recognized.
verification_existsVerification already exists.
insufficient_dataInsufficient applicant data for current verification.
broken_fileThe file is damaged.
incompatible_file_formatThe 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_resolutionThe image resolution is too small. Minimal resolution is 480 px.
image_huge_resolutionThe image resolution is too huge. The maximum resolution is 7000 px.
429limit_exceededExceeding of some limits. (Example: The limit for creating documents has been exceeded)
500internal_serverAn unexpected error occurred on the server without a specific message.
503service_unavailableThe current service is temporarily unavailable.
Error response
                    {
    "type": "validation",
    "errors": [
        {
            "parameter": "residence_country",
            "message": "Country of residence has incorrect format"
        }
    ]
}

Applicants

Applicant types

TypeDescription
PERSONApplicant type using for KYC verification.
COMPANYApplicant type using for KYB verification.

Applicant object

ParameterDescription
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 residence country. Example: GB (ISO 3166-2)
nationality
PERSON
string (2)
The applicant’s current nationality country. 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 object example for type PERSON
                    {
    "applicant_id": "{applicant_id}",
    "external_applicant_id": "{external_applicant_id}",
    "type": "PERSON",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "dob": "1970-10-25",
    "residence_country": "GB",
    "nationality": "GB",
    "gender": "M",
    "email": "[email protected]",
    "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

ParameterDescription
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 residence country. Example: GB (ISO 3166-2)
nationality
PERSON
string (2)
The applicant’s current nationality country. 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.
Profile versioning
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.
Request example
                    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",
        "nationality": "GB",
        "email": "[email protected]"
    }'

Response

ParameterDescription
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.
Response example
                    {
    "applicant_id": "{applicant_id}"
}

Update applicant

Request

URL: https://api.kycaid.com/applicants/{applicant_id}

Method: PATCH

Content-Type: application/json

ParameterDescription
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.
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 residence country. Example: GB (ISO 3166-2)
nationality
PERSON
string (2)
The applicant’s current nationality country. 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.
Request example
                    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"
        "nationality": "GB"
    }'

Response

ParameterDescription
applicant_id
string (36) Required
The applicant’s unique identificator.
Response example
                    {
    "applicant_id": "{applicant_id}"
}

Get applicant

Request

URL: https://api.kycaid.com/applicants/{applicant_id}

Method: GET

ParameterDescription
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.
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.
Request example
                    curl https://api.kycaid.com/applicants/{applicant_id} \
    -H 'Authorization: Token {API_TOKEN}'
    -X GET

Response

ParameterDescription
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 residence country. Example: GB (ISO 3166-2)
nationality
PERSON
string (2)
The applicant’s current nationality country. 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".
Response example
                    {
    "applicant_id": "{applicant_id}",
    "type": "PERSON",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "dob": "1970-10-25",
    "residence_country": "GB",
    "nationality": "GB",
    "gender": null,
    "email": "[email protected]",
    "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

TypeDescription
GOVERNMENT_IDA 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.
PASSPORTA 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_PASSPORTAn internal identity document used by a country to control and monitor the internal movement and residence of its citizens.
DRIVERS_LICENSEAn official document permitting a specific individual to operate one or more types of vehicle and may be accepted as proof of identity.
PERMANENT_RESIDENCE_PERMITA 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_CARDIdentity certificate that refugees use as proof of identity. Issued by UNHCR or by the State of asylum.
FOREIGN_CITIZEN_PASSPORTA document which identifies the person as a citizen of a foreign country.
SELFIE_IMAGEA self-portrait photo which you made by yourself.
SELFIE_WITH_DOCUMENTA self-made portrait photo of yourself holding your identity document in a hand.
SELFIE_WITH_CREDIT_CARDA self-made portrait photo of yourself holding your credit card in a hand required to confirm the cardholder.
ADDRESS_DOCUMENTA 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_DOCUMENTThe 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_NUMBERA 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_CARDA plastic payment card issued by financial institutions, way to you access to the funds at your bank account.
BANK_STATEMENTA 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_COMPANYA 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.
A legal document which contains the official registered address of the company.
AUTHORISED_PERSONA 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_OWNERSHIPAn 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.
VIDEOA video on which the applicant should verify his identity.

Document object

ParameterDescription
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 EUR
ANNUAL_INCOME_GROUP_2 - 50000 - 100000 EUR
ANNUAL_INCOME_GROUP_3 - 100000 - 300000 EUR
ANNUAL_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.
front_side
string (2048)
It generated a one-time URL to the front-side file. URL is available only 24 hours.
back_side_id
string (36)
The file unique identificator that received in response of Create file.
back_side
string (2048)
It generated a one-time URL to the back-side file. URL is available only 24 hours.
other_side_1_id
string (36)
The file unique identificator that received in response of Create file.
other_side_1
string (2048)
It generated a one-time URL to the other side file. URL is available only 24 hours.
other_side_2_id
string (36)
The file unique identificator that received in response of Create file.
other_side_2
string (2048)
It generated a one-time URL to the other side file. URL is available only 24 hours.
other_side_3_id
string (36)
The file unique identificator that received in response of Create file.
other_side_3
string (2048)
It generated a one-time URL to the other side file. URL is available only 24 hours.
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 available
valid - the document is valid
invalid - the document is not valid
comment
string (1000)
The comment is about reasons of decline. It can be used as error message.
decline_reasonsList of decline reasons receiving only for document has invalid status.
The lifetime of one-time file URLs
URL in parameters front_side, back_side, other_side_1, other_side_2, other_side_3 is available about 24 hours.
Document object example for type PASSPORT
                    {
    "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,
    "other_side_3_id": null,
    "other_side_3": 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

ParameterDescription
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 EUR
ANNUAL_INCOME_GROUP_2 - 50000 - 100000 EUR
ANNUAL_INCOME_GROUP_3 - 100000 - 300000 EUR
ANNUAL_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.
other_side_3_id
string (36)
The file unique identificator that received in response of Create file.
Request example
                    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

ParameterDescription
document_id
string (36) Required
The document unique identificator.
Response example
                    {
    "document_id": "{document_id}"
}

Document count limits

Document typeLimit per verification
GOVERNMENT_ID / PASSPORT / DRIVERS_LICENSE / DOMESTIC_PASSPORT / PERMANENT_RESIDENCE_PERMIT / REFUGEE_CARD / FOREIGN_CITIZEN_PASSPORT1
SELFIE_IMAGE / SELFIE_WITH_DOCUMENT / SELFIE_WITH_CREDIT_CARD1
ADDRESS_DOCUMENT1
TAX_ID_NUMBER1
CREDIT_CARD1
REGISTRATION_COMPANY1
COMPANY_LEGAL_ADDRESS1
AUTHORISED_PERSON1
COMPANY_OWNERSHIP1
VIDEO1
FINANCIAL_DOCUMENT / BANK_STATEMENT5
Document limit error
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

ParameterDescription
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 EUR
ANNUAL_INCOME_GROUP_2 - 50000 - 100000 EUR
ANNUAL_INCOME_GROUP_3 - 100000 - 300000 EUR
ANNUAL_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.
other_side_3_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.
Request example
                    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

ParameterDescription
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.
Response example
                    {
    "document_id": "{document_id}"
}

Get document

Request

URL: https://api.kycaid.com/documents/{document_id}

Method: GET

ParameterDescription
document_id
string (36)
The document’s unique identificator.
Request example
                    curl https://api.kycaid.com/documents/{document_id} \
    -H 'Authorization: Token {API_TOKEN}'
    -X GET

Response

ParameterDescription
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 applicant
RECOGNITION - a document created during recognition of some image
ADMIN - a document created by manager
UA_BANK_ID - a document provided by Ukraine Bank ID service
UA_DIIA - a document provided by Ukraine Diia service
IN_AADHAAR - a document provided by India service
KZ_ADATA - a document provided by Kazakh 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 EUR
ANNUAL_INCOME_GROUP_2 - 50000 - 100000 EUR
ANNUAL_INCOME_GROUP_3 - 100000 - 300000 EUR
ANNUAL_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.
other_side_3_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".
Response example
            {
    "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,
    "other_side_3_id": null,
    "other_side_3": 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.

Request example
                    curl https://api.kycaid.com/documents/{document_id} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X DELETE

Response

ParameterDescription
document_id
string (36) Required
The document unique identificator.
Response example
                    {
    "document_id": "{document_id}"
}

Files

Create file

Request

URL: https://api.kycaid.com/files

Method: POST

Content-Type: multipart/form-data

ParameterDescription
file
binary Required
File for upload.

File requirements

  • Supported file formats: BMP, GIF, HEIC, JPEG, PNG, WEBP and PDF.
  • Minimum resolution for image is 480 px.
  • Maximum resolution for image is 7000 px.
  • Maximum file size is 50 Mb.
Request example
                    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

ParameterDescription
file_id
string (36) Required
The file unique identificator.
Response example
                    {
    "file_id": "{file_id}"
}

Update file

Request

URL: https://api.kycaid.com/files/{file_id}

Method: PUT

Content-Type: multipart/form-data

ParameterDescription
file
binary Required
File for upload. Supported file formats: BMP, GIF, HEIC, JPEG, PNG, WEBP and PDF. Maximum file size is 50 Mb.
Request example
                    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

ParameterDescription
file_id
string (36) Required
The file unique identificator.
Response example
                    {
    "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

ParameterDescription
address_id
string (36) Required
The unique identificator of applicant address.
type
string (7) Required
The address type. Valid values are:
REGISTERED
PLACE_OF_BIRTH
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
string (50)
The state of the applicant’s address.
region
string (50)
The region of the applicant’s address.
province
string (50)
The province of the applicant’s address.
city
string (50)
The city or town of the applicant’s address.
district
string (50)
The district of the applicant’s address.
address
string (255)
The address field 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 object example for type REGISTERED
                    {
    "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

ParameterDescription
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
PLACE_OF_BIRTH
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
string (50)
The state of the applicant’s address.
region
string (50)
The region of the applicant’s address.
province
string (50)
The province of the applicant’s address.
city
string (50)
The city or town of the applicant’s address.
district
string (50)
The district of the applicant’s address.
address
string (255)
The address field 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.
Request example
                    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

ParameterDescription
address_id
string (36) Required
The unique identificator of applicant's address.
Response example
                    {
    "address_id": "{address_id}"
}

Update address

Request

URL: https://api.kycaid.com/addresses/{address_id}

Method: PATCH

Content-Type: application/json

ParameterDescription
type
string (10)
The address type. Valid values are:
REGISTERED
PLACE_OF_BIRTH
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.
Request example
                    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

ParameterDescription
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.
Response example
                    {
    "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.

Request example
                    curl https://api.kycaid.com/addresses/{address_id} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X DELETE

Response

ParameterDescription
address_id
string (36) Required
The address unique identificator.
Response example
                    {
    "address_id": "{address_id}"
}

Affiliated persons

Create affiliated person

Request

URL: https://api.kycaid.com/affiliated-persons

Method: POST

Content-Type: application/json

ParameterDescription
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 residence country. Example: GB (ISO 3166-2)
nationality
string (2) Required
The affiliated person current nationality country. Example: GB (ISO 3166-2)
email
string (254) Required
The affiliated person email address.
Request example
                    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",
        "nationality": "GB",
        "email": "[email protected]"
    }'

Response

ParameterDescription
affiliated_person_id
string (36) Required
The unique identificator of affiliated person.
Response example
                    {
    "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

ParameterDescription
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 residence country. Example: GB (ISO 3166-2)
nationality
string (2)
The affiliated person current nationality country. Example: GB (ISO 3166-2)
email
string (254)
The affiliated person email address.
Request example
                    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",
        "nationality": "GB",
        "email": "[email protected]"
    }'

Response

ParameterDescription
affiliated_person_id
string (36) Required
The unique identificator of affiliated person.
Response example
                    {
    "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.

Request example
                    curl https://api.kycaid.com/affiliated-persons/{affiliated_person_id} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X DELETE

Response

ParameterDescription
affiliated_person_id
string (36) Required
The affiliated person unique identificator.
Response example
                    {
    "affiliated_person_id": "{affiliated_person_id}"
}

Verifications

Create verification

Request

URL: https://api.kycaid.com/verifications

Method: POST

Content-Type: application/json

ParameterDescription
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

NameRequired 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
  • Applicant with/without any data.
  • Document with type VIDEO.
Database screening
DATABASE_SCREENING		One of the next verification types are required:
  • PROFILE
  • DOCUMENT
  • TAX_ID
One of the next parameters are required:
Request example
                    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

ParameterDescription
verification_id
string (36) Required
The verification’s unique identificator which assist to identify verification during receiving callback after verification will be completed.
Verification limits
Maximum 20 verifications for one applicant.
Response example
                    {
    "verification_id": "{verification_id}"
}

Get verification

Request

URL: https://api.kycaid.com/verifications/{verification_id}

Method: GET

Request example
                    curl https://api.kycaid.com/verifications/{verification_id} \
    -H 'Authorization: Token {API_TOKEN}'

Response

ParameterDescription
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 form
pending - verification of the applicant in progress
completed - verification is completed
verified
boolean Required
Result of verification. Possible values:
null - the applicant under verification
true - the applicant passed verification
false - the applicant failed verification
verificationsVerificationsList object

VerificationsList

ParameterDescription
profile | document | facial | address | aml | financial | payment_method | tax_id | database_screening | companyVerificationResult object

VerificationResult

ParameterDescription
verified
boolean Required
Result of particular verification. Possible values:
true - the verification passed
false - the verification failed
comment
string (255)
Accompanying verification comment. May not always be provided.
Response structure
                    {
    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>
        }
    }
}
Response example when verification in pending
                    {
    "verification_id": "{verification_id}",
    "status": "pending"
}
Response example of completed verification
                    {
    "verification_id": "{verification_id}",
    "status": "completed",
    "verified": true,
    "verifications": {
        "document": {
            "verified": true,
            "comment": ""
        },
        "address": {
            "verified": true,
            "comment": ""
        }
    }
}

Decline reasons

Verifications decline reasons

CodeTypeDescription
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.
EDITED_DOCUMENT
DOCUMENT
FACIAL
ADDRESS
AML
PAYMENT_METHOD
TAX_ID
COMPANY
The document was edited.
MULTIPLE_PERSON
PROFILE
DOCUMENT
FACIAL
ADDRESS
AML
PAYMENT_METHOD
TAX_ID
VIDEO
COMPANY
Multiple person is not allowed.
COMPULSION
DOCUMENT
FACIAL
Compulsion.

Documents decline reasons

CodeTypeDescription
OTHERSome other reason.
WRONG_NAMEName/Last name is different from the one specified in the document provided.
WRONG_DOBDate of Birth is different from the one specified in the document provided.
AGE_RESTRICTIONThe applicant is under allowed age.
EXPIRED_DOCUMENTThe document has expired.
EXPIRES_LESS_3_MONTHSThe document expires in less than 3 months.
BAD_QUALITYThe document is not visible or the quality of the document image is low.
FAKE_DOCUMENTThe document contains signs of forgery.
WRONG_INFOThe information differs from the one stated in the document.
PROHIBITED_JURISDICTIONThe document is issued in the prohibited jurisdiction.
NO_SELFIEThe selfie image was not provided.
DIFFERENT_FACESThe faces on selfie and in the document are different.
WRONG_DOCUMENTThe document does not match the applicant.
DUPLICATEThis applicant was already created for this client, duplicates are not allowed.
DOCUMENT_DAMAGEDDocument is damaged.
DOCUMENT_INCOMPLETEDocument is incomplete.
FRAUDULENTFraudulent behavior.
TAX_ID_REQUIREDTax ID is required.
COMPROMISED_PERSONThe applicant was found in the database.
EDITED_DOCUMENTThe document was edited.
MULTIPLE_PERSONMultiple person is not allowed.
COMPULSIONCompulsion.

Get verifications report

Request

URL: https://api.kycaid.com/verifications/report

Method: GET

ParameterDescription
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.
Request example
                    curl https://api.kycaid.com/verifications/report?date=2023-01-31 \
    -H 'Authorization: Token {API_TOKEN}'

Response

List of VerificationsReportObjects

VerificationsReportObject

ParameterDescription
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 verification
KYB - KYB verification
SERVICE - 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 Diia
AUTOMATION_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 mode
LIVE - production mode
Response structure
                    [
    {
        "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

BankID is a method of verifying citizens through Ukrainian banks to provide administrative and other services via the Internet.

1. The customer`s client initiates external verification via BankId and sends an appropriate request to the customer server.
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

ParameterDescription
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)
Request example
                    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

ParameterDescription
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_requestsList of additional requests. For instance, separate requests for each verification provider.

RequestObject

ParameterDescription
method
string Required
HTTP Request Method. Supported values: GET, POST.
url
string Required
The URL to use for the request.

AdditionalRequestObject

ParameterDescription
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.
Verification limits
Maximum 20 verifications for one applicant.

UA_BANK_ID

UA_DIIA

Response example
                    {
    "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

Request example
                    curl https://api.kycaid.com/external-verifications/{external-verifications} \
    -H 'Authorization: Token {API_TOKEN}'

Response

ParameterDescription
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 progress
completed - verification was completed
Response structure
                    {
    external_verification_id: <external_verification_id>,
    status: pending|completed
}

Callbacks

Callback types

TypeDescription
VERIFICATION_STATUS_CHANGEDOccurs whenever a verification status is changed. Mostly, it using to identify when verification is created.
VERIFICATION_COMPLETEDOccurs whenever a verification is completed.
DOCUMENT_EXPIREDOccurs whenever a monitoring found expiration documents.
DATABASE_SCREENINGOccurs whenever a monitoring found persons or documents in database screening.

VERIFICATION_STATUS_CHANGED

URL: <callback_url>

Method: POST

Content-Type: application/json

KYC server will send callback request to customer server, once verification status will be changed. Verify callback will be in the JSON format and they will contain the following object parameters:
ParameterDescription
request_id
string (36) Required
The unique identificator of callback request.
type
string Required
VERIFICATION_STATUS_CHANGED - type of callback
form_id
string (36) Required
Form id.
form_token
string (36) Required
Form token. It can be used for additional customer purposes.
verification_id
string (36) Required
The verification’s unique identificator.
applicant_id
string (36) Required
The applicant unique identificator.
external_applicant_id
string (50)
Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems.
verification_status
string (9) Required
Status of verification. Possible values:
unused - the applicant has not yet filled out a form
pending - verification of the applicant in progress
completed - verification is completed
verification_attempts_left
number
Remaining verification attempts. Possible values:
number - count of remaining verifications
null - unlimited
Request example
                    {
    "request_id": "{request_id}",
    "type":"VERIFICATION_STATUS_CHANGED",
    "applicant_id":"{applicant_id}",
    "external_applicant_id":"{external_applicant_id}",
    "verification_id":"{verification_id}",
    "form_id":"{form_id}",
    "verification_status":"pending",
    "verification_attempts_left": {verification_attempts_left}
}

VERIFICATION_COMPLETED

URL: <callback_url>

Method: POST

Content-Type: application/json

KYC server will send verification result request to customer server based on 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:
ParameterDescription
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.
form_id
string (36) Required
Form id.
form_token
string (36) Required
Form token. It can be used for additional customer purposes.
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 form
pending - verification of the applicant in progress
completed - verification is completed
verified
boolean Required
Result of verification. Possible values:
true - the applicant passed verification
false - the applicant failed verification
verificationsVerificationsList object
applicantApplicant object is returned only if parameter return_applicant was setup with value true for Create verification request.
verification_statuses.duplicates
List of applicant_id Required
List of found duplicates during applicant verification.
verification_statuses.ludoman
boolean or null
A parameter that determines whether the applicant is a ludoman or not.
verification_attempts_left
number
Remaining verification attempts. Possible values:
number - count of remaining verifications
null - unlimited
Request example (without applicant)
                    {
    "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
    },
    "verification_attempts_left": {verification_attempts_left}
}
Request example (with applicant)
                    {
    "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": []
        }
    },
    "applicant": {
        "applicant_id": "{applicant_id}",
        "external_applicant_id": "{external_applicant_id}",
        "type": "PERSON",
        "first_name": "John",
        "middle_name": null,
        "last_name": "Doe",
        "dob": "1970-10-25",
        "residence_country": "GB",
        "nationality": "GB",
        "gender": "M",
        "email": "[email protected]",
        "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"
    },
    "verification_statuses": {
        "duplicates": ["duplicate_applicant_id_1", "duplicate_applicant_id_2"],
        "ludoman": false
    },
    "verification_attempts_left": {verification_attempts_left}
}

DOCUMENT_EXPIRED

URL: <callback_url>

Method: POST

Content-Type: application/json

KYC server will send callback request to customer server, once monitoring will find expiration document. Callback will be in the JSON format, and they will contain the following object parameters:
ParameterDescription
type
string Required
Type of callback. Possible types:
DOCUMENT_EXPIRED - type of callback.
document_id
string (36) Required
The documents’s unique identificator.
applicant_id
string (36) Required
The applicant unique identificator.
external_applicant_id
string (50)
The applicant external unique identificator.
verification_id
string (36) Required
The verification’s unique identificator.
Request example
                    {
    "type": "DOCUMENT_EXPIRED",
    "document_id": "{document_id}",
    "applicant_id": "{applicant_id}",
    "external_applicant_id": "{external_applicant_id}",
    "verification_id": "{verification_id}"
}

DATABASE_SCREENING

URL: <callback_url>

Method: POST

Content-Type: application/json

KYC server will send callback request to customer server, once monitoring will find person or document during database screening. Callback will be in the JSON format, and they will contain the following object parameters:
ParameterDescription
type
string Required
Type of callback. Possible types:
DATABASE_SCREENING - type of callback.
document_id
string (36)
The documents’s unique identificator.
applicant_id
string (36) Required
The applicant unique identificator.
external_applicant_id
string (50)
The applicant external unique identificator.
verification_id
string (36) Required
The verification’s unique identificator.
databases
array Required
The list of databases.
list_types
array Required
The list of databases.

Databases

TypeDatabasesDescription
INTERNAL
Kycaid’s internal blacklists
SANCTIONS
EU_ESMA
CA_CCASL
UK_CLOFST
CH_SESAM
FR_FA
KG_FIU
OPEN_SANC_SANCTIONS
OPEN_SANC_DEFAULT
UA_DOVIDKA
UA_FIU
UA_NAZK
UA_NSDCU
UN_UNSCSL
US_OFAC
Individuals and legal entities included to the global and local sanctions lists
PEP
PEP
OCCRP
OPEN_SANC_PEPS
OPEN_SANC_DEFAULT
UA_DOVIDKA
Individuals included to list of politically exposed persons
WANTED
EU_EUROPOL
INTERPOL
KZ_AFMRK
KZ_TERRORISTS
OPEN_SANC_CRIME
PL_POSZUKIWANI
UA_MVS_2
UA_SSU
UK_NCA
US_DEA
US_FBI
OPEN_SANC_DEFAULT
Individuals included to global or local wanted lists
EXPIRED
UA_DMSU_WANTED_PASSPORT
UA_MVS_WANTED_PASSPORT
Documents included to lists of stolen or lost documents
Request example
                    {
    "type": "DATABASE_SCREENING",
    "document_id": "{document_id}",
    "applicant_id": "{applicant_id}",
    "external_applicant_id": "{external_applicant_id}",
    "verification_id": "{verification_id}"
}

SERVICE_RESULT

URL: <callback_url>

Method: POST

Content-Type: application/json

The KYC server will send a callback request to the client's server as soon as the monitoring verifies the address. Callback will be in the JSON format, and they will contain the following object parameters:
ParameterDescription
type
string Required
Type of callback. Possible types:
SERVICE_RESULT - type of callback.
service_request_id
string (36) Required
The service unique identificator.
service_request_type
CRYPTO_ADDRESS_CHECK|CRYPTO_TRANSACTION_CHECK Required
The service verification type.
service_request_status
success|invalid Required
The service verification status.
resultThe address verification result.

CryptoAddressVerificationResult

ParameterDescription
result.riskscore
number Required

Risk assessment 60%.

No riskscore in the response:

  • If the response does not contain the risk score parameter, it means that the risks were not found in our databases.
result.signals
object Required
All interactions of the checked address within the specified blockchain that consider both incoming and outgoing connections (for example "miner": 0.245 - 24.5% belongs to the Miner category).
result.updated_at
number Required
result.address
string (256) Required
result.fiat_code_effective
string (256) Required
result.counterparty
Object Required

Response will contain the name of the cluster and its category if the address being checked is in a named cluster:

"counterparty": {"name": "Binance.com", "type": "exchange"}

The response will contain an internal id if the address being checked is in an unnamed cluster:

"counterparty": {"id": 1075118303}

The address to be checked will be specified as the counterparty if it is not in the cluster:

"counterparty": {"address": "3HQBsRNJcnzk4kcGxMabFMqD6Ud23T5eUd"}
result.reported_address_balance
boolean Required
result.address_details_data
object Required Additional details of the verified address.
result.black_lists_connections
boolean Required
If black list checking is enabled.
result.has_black_list_flag
boolean Required
Connection with blacklists: false - connections to blacklist not detected, true - connections to blacklist detected.
result.pdf_report
string Required
Link to download PDF report.
result.memo Required
string
result.uid
string Required
Unique verification identifier of the verified address.
result.asset
string Required
Currency of the verification check.
result.network
string Required
The network where the address verification occurred
result.timestamp
string Required
Date and time of check implementation.

CryptoTransactionVerificationResult

ParameterDescription
result.riskscore
number Required

Counterparty Risk Score. In this example answer, the Counterparty Risk Score is 28%.

The riskscore value refers to the counterparty:

  • For a transaction with the "deposit" type - it is the risk score of the sender, where all its interactions in the chain are taken into account.
  • For a transaction with the "withdrawal" type - it is the risk score of the recipient, where all its direct and indirect interactions in the chain are taken into account

No riskscore in the response:

  • If the response does not contain the risk score parameter, it means that the risks were not found in our databases.
result.signals
object Required
Sources of funds origin that are related to the transferred assets in the transaction (for example "exchange_mlrisk_high": 1 - 100% belongs to the exchange whith mlrisk high category)
result.updated_at
number Required
result.address
string (256) Required
The address.
result.created_at
number Required
result.amount
Number Required
result.risky_volume
Number Required
result.direction
deposit|withdrawal Required
result.tx
string Required
result.risky_volume_fiat
string Required Volume of risky assets in cents USD.
result.fiat
string Required Transaction amount in cents USD.
result.fiat_code_effective
string (256) Required
result.counterparty
Object Required
Counteragent with whom the interaction took place. For the type=deposit transaction it's the sender. For the type=withdrawal transaction it"s the recipient.
result.black_lists_connections
boolean Required
If black list checking is enabled.
result.has_black_list_flag
boolean Required
Connection with blacklists: false - connections to blacklist not detected, true - connections to blacklist detected.
result.pdf_report
string Required
Link to download PDF report.
result.memo
string Required
result.uid
string Required
Unique verification identifier of the verified address.
result.asset
string Required
Currency of the verification check.
result.network
string Required
The network where the address verification occurred
result.timestamp
string Required
Date and time of check implementation.
Request example
                    {
    "type": "SERVICE_RESULT",
    "service_request_id": "{service_request_id}",
    "service_request_type": "CRYPTO_ADDRESS_CHECK",
    "result": {
        "risk_score": 0.75,
        "signals": {
            "atm": 0,
            "child_exploitation": 0,
            "dark_market": 0,
            "dark_service": 0,
            "enforcement_action": 0,
            "exchange_fraudulent": 0,
            "gambling": 1,
            "illegal_service": 0,
            "liquidity_pools": 0,
            "marketplace": 0,
            "miner": 0,
            "mixer": 0,
            "other": 0,
            "payment": 0,
            "ransom": 0,
            "sanctions": 0,
            "scam": 0,
            "seized_assets": 0,
            "stolen_coins": 0,
            "terrorism_financing": 0,
            "wallet": 0,
            "exchange": 0,
            "risky_exchange": 0,
            "p2p_exchange": 0,
            "p2p_exchange_mlrisk_high": 0,
            "exchange_mlrisk_high": 0,
            "exchange_mlrisk_low": 0,
            "exchange_mlrisk_moderate": 0,
            "exchange_mlrisk_very_high": 0,
            "p2p_exchange_mlrisk_low": 0,
            "fraud_shop": 0,
            "illicit_actor_org": 0,
            "high_risk_jurisdiction": 0,
            "infrastructure_as_a_service": 0,
            "lending_contract": 0,
            "decentralized_exchange_contract": 0,
            "smart_contract": 0,
            "token_smart_contract": 0,
            "protocol_privacy": 0,
            "merchant_services": 0,
            "ico": 0,
            "unnamed_service": 0,
            "special_measures": 0,
            "online_pharmacy": 0,
            "bridge": 0,
            "malware": 0,
            "nft_platform_collection": 0
        },
        "updated_at": 1725168579,
        "address": "12mxdS6cmFmQgRDhboAqD5q9umtjVq6pE7",
        "fiat_code_effective": "usd",
        "counterparty": {
            "address": "12mxdS6cmFmQgRDhboAqD5q9umtjVq6pE7",
            "received_fiat_amount": 60608.7613726,
            "signals": {
                "bwd": {
                    "atm": 0,
                    "child_exploitation": 0,
                    "dark_market": 0,
                    "dark_service": 0,
                    "enforcement_action": 0,
                    "exchange_fraudulent": 0,
                    "exchange_licensed": 0,
                    "exchange_unlicensed": 0,
                    "gambling": 1,
                    "illegal_service": 0,
                    "liquidity_pools": 0,
                    "marketplace": 0,
                    "miner": 0,
                    "mixer": 0,
                    "other": 0,
                    "p2p_exchange_licensed": 0,
                    "p2p_exchange_unlicensed": 0,
                    "payment": 0,
                    "ransom": 0,
                    "sanctions": 0,
                    "scam": 0,
                    "seized_assets": 0,
                    "stolen_coins": 0,
                    "terrorism_financing": 0,
                    "wallet": 0
                },
                "fwd": {
                    "atm": 0,
                    "child_exploitation": 0,
                    "dark_market": 0,
                    "dark_service": 0,
                    "enforcement_action": 0,
                    "exchange_fraudulent": 0,
                    "exchange_licensed": 0,
                    "exchange_unlicensed": 0,
                    "gambling": 0,
                    "illegal_service": 0,
                    "liquidity_pools": 0,
                    "marketplace": 0,
                    "miner": 0,
                    "mixer": 0,
                    "other": 0,
                    "p2p_exchange_licensed": 0,
                    "p2p_exchange_unlicensed": 0,
                    "payment": 0,
                    "ransom": 0,
                    "sanctions": 0,
                    "scam": 0,
                    "seized_assets": 0,
                    "stolen_coins": 0,
                    "terrorism_financing": 0,
                    "wallet": 0
                }
            }
        },
        "reported_address_balance": null,
        "address_details_data": {
            "type": "pubkeyhash",
            "balance": "1042034",
            "final_balance": "1042034",
            "balance_usd": 604.12963184,
            "n_txs": 1,
            "first_tx": "2024-08-31 08:50:16",
            "last_tx": "2024-08-31 08:50:16",
            "received": "1042034",
            "received_usd": 615.9463,
            "sent": "0",
            "sent_usd": 0,
            "reported_balance_precision": 8,
            "balance_approximate": 0.01042034
        },
        "black_lists_connections": false,
        "has_black_list_flag": false,
        "pdf_report": "https://extrnlapiendpoint.silencatech.com/response/userdata/6A98C7D482B9F85/renderer/pdf/responsedata/66D3FBC303614791626230:EE5DFCC3EDE131B",
        "memo": "",
        "uid": "66d3fbc303614791626230",
        "asset": "BTC",
        "network": "BTC",
        "status": "success",
        "timestamp": "2024-09-01 05:29:39"
    }
}
Request example
                    {
    "type": "SERVICE_RESULT",
    "service_request_id": "{service_request_id}",
    "service_request_type": "CRYPTO_TRANSACTION_CHECK",
    "result": {
        "risk_score": 0.734,
        "signals": {
            "atm": 0,
            "child_exploitation": 0,
            "dark_market": 0,
            "dark_service": 0,
            "enforcement_action": 0,
            "exchange_fraudulent": 0,
            "gambling": 0,
            "illegal_service": 0,
            "liquidity_pools": 0,
            "marketplace": 0,
            "miner": 0,
            "mixer": 0,
            "other": 0,
            "payment": 0,
            "ransom": 0,
            "sanctions": 0,
            "scam": 0,
            "seized_assets": 0,
            "stolen_coins": 0,
            "terrorism_financing": 0,
            "wallet": 0,
            "exchange": 0,
            "risky_exchange": 0,
            "p2p_exchange": 0,
            "p2p_exchange_mlrisk_high": 0,
            "exchange_mlrisk_high": 0,
            "exchange_mlrisk_low": 0,
            "exchange_mlrisk_moderate": 0,
            "exchange_mlrisk_very_high": 0,
            "p2p_exchange_mlrisk_low": 0,
            "fraud_shop": 0,
            "illicit_actor_org": 0,
            "high_risk_jurisdiction": 0,
            "infrastructure_as_a_service": 0,
            "lending_contract": 0,
            "decentralized_exchange_contract": 0,
            "smart_contract": 0,
            "token_smart_contract": 0,
            "protocol_privacy": 0,
            "merchant_services": 0,
            "ico": 0,
            "unnamed_service": 0,
            "special_measures": 0,
            "online_pharmacy": 0,
            "bridge": 0,
            "malware": 0,
            "nft_platform_collection": 0
        },
        "updated_at": 1725094721,
        "address": "12mxdS6cmFmQgRDhboAqD5q9umtjVq6pE7",
        "created_at": 1725094721,
        "amount": 1042034,
        "risky_volume": 0,
        "direction": "withdrawal",
        "tx": "41a57df436157b92d5d61cdd36dd43d5f4734cbeee7f4f4809b91cc2a7b2a520",
        "risky_volume_fiat": 0,
        "fiat": 60609,
        "fiat_code_effective": "usd",
        "counterparty": {
            "address": "12mxdS6cmFmQgRDhboAqD5q9umtjVq6pE7",
            "signals": {
                "bwd": {
                    "atm": 0,
                    "child_exploitation": 0,
                    "dark_market": 0,
                    "dark_service": 0,
                    "enforcement_action": 0,
                    "exchange_fraudulent": 0,
                    "exchange_licensed": 0.072,
                    "exchange_unlicensed": 0.088,
                    "gambling": 0.812,
                    "illegal_service": 0,
                    "liquidity_pools": 0,
                    "marketplace": 0,
                    "miner": 0,
                    "mixer": 0,
                    "other": 0.007,
                    "p2p_exchange_licensed": 0.001,
                    "p2p_exchange_unlicensed": 0,
                    "payment": 0.001,
                    "ransom": 0,
                    "sanctions": 0,
                    "scam": 0,
                    "seized_assets": 0,
                    "stolen_coins": 0,
                    "terrorism_financing": 0,
                    "wallet": 0.018
                },
                "fwd": {
                    "atm": 0,
                    "child_exploitation": 0,
                    "dark_market": 0,
                    "dark_service": 0,
                    "enforcement_action": 0,
                    "exchange_fraudulent": 0,
                    "exchange_licensed": 0,
                    "exchange_unlicensed": 0,
                    "gambling": 0,
                    "illegal_service": 0,
                    "liquidity_pools": 0,
                    "marketplace": 0,
                    "miner": 0,
                    "mixer": 0,
                    "other": 0,
                    "p2p_exchange_licensed": 0,
                    "p2p_exchange_unlicensed": 0,
                    "payment": 0,
                    "ransom": 0,
                    "sanctions": 0,
                    "scam": 0,
                    "seized_assets": 0,
                    "stolen_coins": 0,
                    "terrorism_financing": 0,
                    "wallet": 0
                }
            }
        },
        "black_lists_connections": false,
        "has_black_list_flag": false,
        "pdf_report": "https://extrnlapiendpoint.silencatech.com/response/userdata/6A98C7D482B9F85/renderer/pdf/responsedata/66D2DB413E06E086000469:01A3561E99267B2",
        "memo": "",
        "uid": "66d2db413e06e086000469",
        "asset": "BTC",
        "network": "BTC",
        "timestamp": "2024-08-31 08:58:41"
    }
}

SIGNED_DOCUMENTS

URL: <callback_url>

Method: POST

Content-Type: application/json

The KYC server will send a callback request to the client's server as soon as the applicant or customer sign documents. Callback will be in the JSON format, and they will contain the following object parameters:
ParameterDescription
type
string Required
Type of callback. Possible types:
SIGNED_DOCUMENTS - type of callback.
request_id
string (36) Required
The unique identificator of callback request.
signed_by
string Required
Possible types:
APPLICANT
CUSTOMER
applicant_signature_type
string Required
Type of applicant signature. Possible types:
SMARTID - SmartID
DIIA_SIGNATURE - Diia.Signature
applicant_id
string (36) Required
The applicant unique identificator.
external_applicant_id
string (50)
The applicant external unique identificator.
verification_id
string (36) Required
The verification’s unique identificator.
applicantApplicant object is returned only if parameter return_applicant was setup with value true for Create verification request.
Request example
            {
  "type": "SIGNED_DOCUMENTS",
  "request_id": "{request_id}",
  "signed_by": "{signed_by}",
  "applicant_signature_type": "{applicant_signature_type}",
  "applicant_id": "{applicant_id}",
  "external_applicant_id": "{external_applicant_id}",
  "verification_id": "{verification_id}",
  "applicant": "{applicant}"
}

Callback response

HTTP status code 2xx is treating as a success sending callback to customer server during 10 seconds. 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

You have to use your API token, in order to check the data for the integrity of the callback response.
How to verify:
  1. A raw request body should be encoded using Base64 encoding.
  2. A hash of the encoded request body should be created using algorithm HMAC (SHA-512) and API token as the secret key.
  3. Created hash should be equal to a hash that was received in request header x-data-integrity

Example

Raw request body
            {"request_id":"61a7dbcc012d9042e909cf006e7b412d6ba5","type":"VERIFICATION_STATUS_CHANGED","applicant_id":"4141cc1b18dba048470b2961cb4592f480fe","verification_id":"2cf795e713be1040e50b202164ee17bfdfbe","form_id":"58bed87600dd9944f02ba0c9cd8b32d6bd4c","verification_status":"pending"}
Encoding request body
            eyJyZXF1ZXN0X2lkIjoiNjFhN2RiY2MwMTJkOTA0MmU5MDljZjAwNmU3YjQxMmQ2YmE1IiwidHlwZSI6IlZFUklGSUNBVElPTl9TVEFUVVNfQ0hBTkdFRCIsImFwcGxpY2FudF9pZCI6IjQxNDFjYzFiMThkYmEwNDg0NzBiMjk2MWNiNDU5MmY0ODBmZSIsInZlcmlmaWNhdGlvbl9pZCI6IjJjZjc5NWU3MTNiZTEwNDBlNTBiMjAyMTY0ZWUxN2JmZGZiZSIsImZvcm1faWQiOiI1OGJlZDg3NjAwZGQ5OTQ0ZjAyYmEwYzljZDhiMzJkNmJkNGMiLCJ2ZXJpZmljYXRpb25fc3RhdHVzIjoicGVuZGluZyJ9
Creation of hash (secret: 28c6f7cc0345a04eee0b535039b1c5a62547)
            f7681b097b77928fc031d614709976796057c306cf77fdd449bb414937bd87678d908d7efaa65e9b1dd65b9eeea2121ea75bd9007f44fe8fcd7c9ac6cdeeef0e

Forms

Get forms

Request

URL: https://api.kycaid.com/forms

Method: GET

Request example
                    curl https://api.kycaid.com/forms \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET

Response

List of FormObjects

FormObject

ParameterDescription
form_id
string Required
Form id.
name
string Required
Form name.
created_at
string Required
Date and time of form creation.
Response structure
                    [
    {
        "form_id": "<form_id>",
        "name": "<name>",
        "created_at": "<created_at>"
    },
    ...
]

Get form URL

Request

URL: https://api.kycaid.com/forms/{form_id}/urls

Method: POST

Content-Type: application/json

ParameterDescription
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.
Request example
                    curl https://api.kycaid.com/forms/{form_id}/urls \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "applicant_id": "{applicant_id}",
        "external_applicant_id": "{external_applicant_id}",
        "redirect_url": "https://site.com/success-kyc"
    }'

Response

ParameterDescription
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.
form_token
string (36) Required
Form token. It can be used for additional customer purposes.
verification_attempts_left
number
Remaining verification attempts. Possible values:
number - count of remaining verifications
null - unlimited
Form language
For the setup initial language of form UI, you need to add URL parameter lang.

Possible values:
az (Azerbaijani)
bn (Bengali)
de (German)
en (English)
es (Spanish)
es-mx (Spanish(Mexico))
fr (French)
he (Hebrew)
hi (Hindi)
kk (Kazakh)
nl (Dutch)
pl (Polish)
pt (Portuguese)
ro (Romanian)
ru (Russian)
tr (Turkish)
uk (Ukrainian)
uz (Uzbek)
yi (Yiddish)
zh (Chinese)

Example: https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024/?lang=uk
If the form URL opens in an iframe
For the correct operation of the camera in the iframe, you need to add the attribute allow="microphone *;camera *;midi *;encrypted-media *;clipboard-read;clipboard-write;" to iframe.

The iframe size should not exceed screen size on mobile devices.
postMessage communication for iframe solution
A form triggers a cross-origin message when the applicant completed the form, only when a form was opened in an iframe.

Message format:
{
    "event": "FORM_COMPLETED",
    "applicant_id": "{applicant_id}",
    "verification_id": "{verification_id}"
}
If the form URL opens in iOS WKWebView
For the correct operation of the camera in the WKWebView, you need to setup allowsInlineMediaPlayback = true.

WKWebViewConfiguration is only used when a web view is first initialized. You cannot use this class to change the web view's configuration after it has been created.
Response example
                    {
    "form_id": "{form_id}",
    "form_url": "https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024",
    "verification_id": "{verification_id}",
    "form_token": "{form_token}",
    "verification_attempts_left": {verification_attempts_left}
}


Additional

Get business activities

This method retrieves list of business activities that are available to perform a verification.

URL: https://api.kycaid.com/business-activities

Method: GET

Request example
                    curl https://api.kycaid.com/business-activities \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET

Response

List of BusinessCategoryObjects

BusinessCategoryObject

ParameterDescription
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

ParameterDescription
language_code
string (2) Required
Language code. Example: EN (ISO 639-1)
label
string (50) Required
Business category name on specific language.

BusinessActivityObject

ParameterDescription
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

ParameterDescription
language_code
string (2) Required
Language code. Example: EN (ISO 639-1)
label
string (50) Required
Business activity name on specific language.
Response structure
                    [
    {
        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>
                    },
                    ...
                ],
            }
        ]
    },
    ...
]
Response example
                    [
    {
        "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

This method retrieves all the countries that are available to perform a verification.

URL: https://api.kycaid.com/countries

Method: GET

Request example
                    curl https://api.kycaid.com/countries \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET


Response

List of CountryObjects

CountryObject

ParameterDescription
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

ParameterDescription
language_code
string (2) Required
Language code. Example: EN (ISO 639-1)
label
string (50) Required
Country name on specific language.
Response structure
                    [
    {
        country_code: <country_code>,
        labels: [
            {
                language_code: <language_code>,
                label: <country_name>
            },
            ...
        ]
    },
    ...
]
Response example
                    [
    {
        "country_code": "AD",
        "labels": [
            {
                "language_code": "EN",
                "label": "Andorra"
            },
            {
                "language_code": "RU",
                "label": "Андорра"
            },
            {
                "language_code": "UK",
                "label": "Андорра"
            }
        ]
    }
]

Get languages

This method retrieves list of supported languages.

URL: https://api.kycaid.com/languages

Method: GET

Request example
                    curl https://api.kycaid.com/languages \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET


Response

List of LanguageObjects

LanguageObject

ParameterDescription
language_code
string (2) Required
Language code. Example: en (ISO 639-1)
labels
array Required
List of LanguageLabelObjects.

LanguageLabelObject

ParameterDescription
language_code
string (2) Required
Language code. Example: en (ISO 639-1)
label
string (50) Required
Locale name on specific language.
Response structure
                    [
    {
        language_code: <language_code>,
        labels: [
            {
                language_code: <language_code>,
                label: <language_name>
            },
            ...
        ]
    },
    ...
]
Response example
                    [
    {
        "language_code": "en",
        "labels": [
            {
                "language_code": "en",
                "label": "English"
            },
            {
                "language_code": "ru",
                "label": "Английский"
            },
            {
                "language_code": "uk",
                "label": "Англійська"
            }
        ]
    }
]

Services

Brazilian CPF

This method retrieves information about Brazilian people based on their CPF number.

URL: https://api.kycaid.com/services/br/cpf/{cpf_number}

Method: GET

Request example
                    curl https://api.kycaid.com/services/br/cpf/{cpf_number} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET

Request

ParameterDescription
cpf_number
string (11) Required
CPF number. Example format: 123456778901, but not 123.456.789-01.

Response

ParameterDescription
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
Response structure
                    {
    "validation": {
        "valid": {status}
    },
    "data": {
        "number": "{number}",
        "name": "{name}",
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "dob": "{dob}",
        "gender": "{gender}"
    }
}

Mexican CURP

This method retrieves information about Mexican people based on their CURP number.

URL: https://api.kycaid.com/services/mx/curp/{curp_number}

Method: GET

Request example
                    curl https://api.kycaid.com/services/mx/curp/{curp_number} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET

Request

ParameterDescription
curp_number
string (18) Required
CURP number. Example format: HEGA820506HBCRRL09.

Response

ParameterDescription
validation.valid
boolean Required
Result of CURP number validation.
data.number
string Required
CURP number.
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
Response structure
                    {
    "validation": {
        "valid": {status}
    },
    "data": {
        "number": "{number}",
        "name": "{name}",
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "dob": "{dob}",
        "gender": "{gender}"
    }
}

Peru DNI

This method retrieves information about Peru people based on their DNI.

URL: https://api.kycaid.com/services/pe/dni/{dni_number}

Method: GET

Request example
                    curl https://api.kycaid.com/services/pe/dni/{dni_number} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET

Request

ParameterDescription
dni_number
string (8) Required
DNI number. Example format: 12345678.

Response

ParameterDescription
validation.valid
boolean Required
Result of DNI number validation.
data.number
string Required
DNI number.
data.first_name
string
First name
data.last_name
string
Last name
data.second_last_name
string
Second last name
data.residence_country
string (2)
Residence country
Response structure
                    {
    "validation": {
        "valid": {status}
    },
    "data": {
        "number": "{number}",
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "second_last_name": "{last_name}",
        "residence_country": "{residence_country}"
    }
}

Peru DNI Extra

This method retrieves extended information about Peru people based on their DNI.

URL: https://api.kycaid.com/services/pe/dni-extra/{dni_number}

Method: GET

Request example
                    curl https://api.kycaid.com/services/pe/dni-extra/{dni_number} \
    -H 'Authorization: Token {API_TOKEN}' \
    -X GET

Request

ParameterDescription
dni_number
string (8) Required
DNI number. Example format: 12345678.

Response

ParameterDescription
validation.valid
boolean Required
Result of DNI number validation.
data.number
string Required
Applicant's DNI number.
data.first_name
string
Applicant's first name
data.last_name
string
Applicant's last name
data.full_name
string
Applicant's full name
data.names
array
Applicant's full name as an array
data.issue_date
string
Applicant's document issue date
data.expiry_date
string
Applicant's document expiration date
data.dob
string
Applicant's date of birth
data.age
number
Applicant's age
data.dod
string
Applicant's date of death
data.gender
string
Applicant's gender
data.civil_status
string
Applicant's civil status
data.donor
boolean
Applicant was applied to be an organ donor
data.verification_digit
number
A digit to validate data
data.address.postal_code
string
Applicant's residence postal code
data.address.ubigeo
number
Applicant's residence code in UBIGEO coding system
data.address.region
string
Applicant's residence region
data.address.province
string
Applicant's residence province
data.address.district
string
Applicant's residence district

Error types

TypeMessage
not_foundInformation not found
missing_parameterParameter is missing
Response structure
            {
    "validation": {
        "valid": {status}
    },
    "errors": [
        {
            "type": "{type}",
            "message": "{message}"
        }
    ],
    "data": {
        "number": "{number}",
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "full_name": "{full_name}",
        "names": "{names}",
        "issue_date": "{issue_date}",
        "expiry_date": "{expiry_date}",
        "dob": "{dob}",
        "age": "{age}",
        "dod": "{dod}",
        "civil_status": "{civil_status}",
        "donor": "{donor}",
        "verification_digit": "{verification_digit}",
        "address": {
            "postal_code": "{postal_code}",
            "ubigeo": "{ubigeo}",
            "region": "{region}",
            "province": "{province}",
            "district": "{district}"
        }
    }
}

Nigerian NIN

This method retrieves information about Nigerian people based on their NIN.

URL: https://api.kycaid.com/services/ng/nin

Method: POST

Request example
            curl https://api.kycaid.com/services/ng/nin \
                -H 'Authorization: Token {API_TOKEN}' \
                -H 'Content-Type: application/json' \
                -X POST \
                -d '{
                    "nin_number": {nin_number},
                    "first_name": {first_name},
                    "last_name": {last_name}
                }'

Request

ParameterDescription
nin_number
string (11) Required
NIN number. Example format: 12345678901.
first_name
string Required
First name. Example: 'Bunch'.
last_name
string Required
Last name. Example: 'Dillon'.

Response

ParameterDescription
validation.valid
boolean Required
Result of NIN number validation.
data.first_name
string
First name
data.last_name
string
Last name
data.dob
string
Date of birth
data.phone
string
Phone number
data.email
string
Email
data.gender
string
Gender
Response structure
            {
                "validation": {
                    "valid": {status}
                },
                "data": {
                    "first_name": "{first_name}",
                    "last_name": "{last_name}",
                    "dob": "{dob}",
                    "phone": "{phone}",
                    "email": "{email}",
                    "gender": "{gender}",
                }
            }

Nigerian Driver License Number

This method retrieves information about Nigerian people based on their Driver License Number.

URL: https://api.kycaid.com/services/ng/driver-license-number

Method: POST

Request example
            curl https://api.kycaid.com/services/ng/driver-license-number \
                -H 'Authorization: Token {API_TOKEN}' \
                -H 'Content-Type: application/json' \
                -X POST \
                -d '{
                    "driver_license_number": {driver_license_number},
                    "first_name": {first_name},
                    "last_name": {last_name}
                }'

Request

ParameterDescription
driver_license_number
string (10-12) Required
Driver license number. Example format: AKW06968AA2.
first_name
string Required
First name. Example: 'Bunch'.
last_name
string Required
Last name. Example: 'Dillon'.

Response

ParameterDescription
validation.valid
boolean Required
Result of Driver license number validation.
data.first_name
string
First name
data.last_name
string
Last name
data.dob
string
Date of birth
data.phone
string
Phone number
data.email
string
Email
data.gender
string
Gender
Response structure
            {
                "validation": {
                    "valid": {status}
                },
                "data": {
                    "first_name": "{first_name}",
                    "last_name": "{last_name}",
                    "dob": "{dob}",
                    "phone": "{phone}",
                    "email": "{email}",
                    "gender": "{gender}",
                }
            }

Turkey Identity Number

This method validate Turkey Identity Number.

URL: https://api.kycaid.com/services/tr/identity-number

Method: POST

Request example
                    curl https://api.kycaid.com/services/tr/identity-number \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "identity_number": {identity_number},
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "birth_year": {birth_year}
    }'

Request

ParameterDescription
identity_number
number (11) Required
Turkey Identity Number. Example format: 12345678901.
first_name
string (50) Required
First name of applicant.
last_name
string (50) Required
last name of applicant.
birth_year
number (4) Required
Year of applicant birth.

Response

ParameterDescription
validation.valid
boolean Required
Result of Turkey Identity Number validation.
data.identity_number
number (11) Required
Turkey Identity Number.
data.first_name
string (50)
First name.
data.last_name
string (50)
Last name.
data.birth_year
number (4)
Birth year.
data.residence_country
string (2) Required
Residence country.
Response structure
                    {
    "validation": {
        "valid": {status}
    },
    "data": {
        "identity_number": {identity_number},
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "birth_year": {birth_year},
        "residence_country": "{residence_country}"
    }
}

Kazakhstan Personal Data

Request data

This method request applicant data by Kazakhstan IIN.

URL: https://api.kycaid.com/services/kz/personal-data/request

Method: POST

Request example
                    curl https://api.kycaid.com/services/kz/personal-data/request \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "iin": "{iin}"
    }'

Request

ParameterDescription
iin
string (12) Required
Kazakhstan IIN. Example format: 123456789012.

Response

ParameterDescription
validation.valid
boolean Required
Result of Kazakhstan IIN validation.
data.iin
string (12) Required
Kazakhstan IIN. Example format: 123456789012.
data.service_request_id
string (36)
Unique service request id.
Response structure
            {
    "validation": {
        "valid": {status}
    },
    "data": {
        "iin": "{iin}",
        "service_request_id": "{service_request_id}"
    }
}

Check data

This method retrieves information about applicant based on his Kazakhstan IIN.

URL: https://api.kycaid.com/services/kz/personal-data/check

Method: POST

Request example
                    curl https://api.kycaid.com/services/kz/personal-data/check \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "service_request_id": "{service_request_id}"
    }'

Request

ParameterDescription
service_request_id
string (36) Required
Unique service request id.

Response

ParameterDescription
data
object
It can be null if the request has not been completed yet. Maximum waiting time 3 min.
data.service_request_id
string (36) Required
Unique service request id.
data.iin
string (12) Required
Kazakhstan IIN. Example format: 123456789012.
data.first_name
string Required
Applicant first name.
data.last_name
string Required
Applicant last name.
data.middle_name
string Required
Applicant middle name.
data.dob
string (12) Required
Applicant date of birth.
data.gender
string (1) Required
Applicant gender.
data.document_number
string Required
Applicant document number.
data.full_address
string Required
Applicant registration address.
Response structure
            {
    "data": {
        "service_request_id": "{service_request_id}",
        "iin": "{iin}",
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "middle_name": "{middle_name}",
        "dob": "{dob}",
        "gender": "{gender}",
        "document_number": "{document_number}",
        "full_address": "{full_address}"
    }
}

India aadhaar card

Generate OTP

This method initialize checking Aadhaar card number.

URL: https://api.kycaid.com/services/in/aadhaar/generate-otp

Method: POST

Request example
                    curl https://api.kycaid.com/services/in/aadhaar/generate-otp \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "aadhaar_number": "{aadhaar_number}"
    }'

Request

ParameterDescription
aadhaar_number
string (12) Required
Aadhaar Card Number. Example format: 123456789012.

Response

ParameterDescription
validation.valid
boolean Required
Result of Aadhaar Number validation.
data.aadhaar_number
number (12) Required
Aadhaar Card Number. Example format: 123456789012.
data.otp_sent
boolean Required
Status of OTP sent.
data.service_request_id
string (36)
Unique service request id.

Error types

TypeMessage
unlinked_numberMobile number not linked with aadhaar number
invalid_numberPlease provide a valid Aadhaar number
lock_accountPlease unlock Aadhar from the UIDAI portal
Response structure
            {
    "validation": {
        "valid": {status}
    },
    "errors": [
        {
            "type": "{type}",
            "message": "{message}"
        }
    ],
    "data": {
        "aadhaar_number": "{aadhaar_number}",
        "otp_sent": {otp_sent},
        "service_request_id": "{service_request_id}"
    }
}

Submit OTP

This method retrieves information about applicant based on their Aadhaar card number.

URL: https://api.kycaid.com/services/in/aadhaar/submit-otp

Method: POST

Request example
                    curl https://api.kycaid.com/services/in/aadhaar/submit-otp \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "service_request_id": "{service_request_id}",
        "otp": "{otp}"
    }'

Request

ParameterDescription
service_request_id
string (36) Required
Unique service request id.
otp
string (6) Required
The 6 digit OTP received to the registered mobile number.

Response

ParameterDescription
data.service_request_id
string (36) Required
Unique service request id.
data.aadhaar_number
number (12) Required
Aadhaar Card Number. Example format: 123456789012.
data.full_name
string (255) Required
Full Name as per Aadhaar Records.
data.first_name
string (255) Required
Applicant first name.
data.last_name
string (255) Required
Applicant last name.
data.dob
string (12) Required
Applicant date of birth.
data.gender
string (1) Required
Applicant gender.
data.full_address
string (255) Required
Applicant full address.
data.profile_image
string
Applicant profile photo.
Response structure
            {
    "data": {
        "service_request_id": "{service_request_id}",
        "aadhaar_number": "{aadhaar_number}",
        "full_name": "{full_name}",
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "dob": "{dob}",
        "gender": "{gender}",
        "full_address": "{aadhaar_number}",
        "profile_image": "{profile_image}"
    }
}

Phone number check

Send SMS

This method initialize checking phone number.

URL: https://api.kycaid.com/services/phone-number/check/request

Method: POST

Request example
                    curl https://api.kycaid.com/services/phone-number/check/request \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "phone_number": "{phone_number}"
    }'

Request

ParameterDescription
phone_number
string (15) Required
Phone number for check. Phone number must be in international format. Example format: 3805012345678.

Response

ParameterDescription
validation.format
boolean Required
Result of phone number validation.
validation.sending
boolean Required
Status of sending SMS.
data.phone_number
number (15) Required
Applicants phone number.
data.service_request_id
string (36)
Unique service request id.
Response structure
            {
    "validation": {
        "format": {format},
        "sending": {sending}
    },
    "data": {
        "phone_number": "{phone_number}",
        "service_request_id": "{service_request_id}"
    }
}

Submit Pin Code

This method for sending pin code from SMS message.

URL: https://api.kycaid.com/services/phone-number/check/submit-pin-code

Method: POST

Request example
                    curl https://api.kycaid.com/services/phone-number/check/submit-pin-code \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "service_request_id": "{service_request_id}",
        "pin_code": "{pin_code}"
    }'

Request

ParameterDescription
service_request_id
string (36) Required
Unique service request id.
pin_code
string (6) Required
The 6 digit from SMS message.

Response

ParameterDescription
validation.format
boolean Required
Result of phone number validation.
validation.valid
boolean Required
Result of phone number check.
validation.expired
boolean Required
Status of request expiration.
data.service_request_id
string (36) Required
Unique service request id.
data.pin_code
string (6) Required
The 6 digit from SMS message.
Response structure
            {
    "validation": {
        "format": {format},
        "valid": {valid},
        "expired": {expired}
    },
    "data": {
        "pin_code": "{expired}",
        "service_request_id": "{service_request_id}"
    }
}

Identity document recognition

This method provides the possibility of data extraction from identity documents.

URL: https://api.kycaid.com/recognizer/id

Method: POST

Request example
            curl https://api.kycaid.com/recognizer/id \
    -H 'Authorization: Token {API_TOKEN} \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "images": [
            "/9j/4AAQSkZJRgABAQEAkAC...",
            "/9j/4AAQSkZJRgABAQEAxwD..."
        ]
    }'

Request

ParameterDescription
images
array <string> Required
Array of images in Base64.

Response

ParameterDescription
identity_document.documents
array <string> Required
List of recognized documents.
identity_document.statuses
object Required
List of document statuses.
identity_document.fields
array <object> Required
List of document fields.
identity_document.images
array <object> Required
Last name
identity_document.more_pages_available
number Required
Indicates if a document has more pages to be processed, for example, ID card's front and back side. Default value is 0.
identity_document.processing_time
number Required
Time spent on document recognition (milliseconds).

Document types

IDName
11Passport
12Identity card
13Diplomatic passport
14Service passport
15Seamans identity document
16Identity card for residence
17Travel document
20National identity card
21Social identity card
22Alien's identity card
23Privileged identity card
24Residence permit identity card
25Origin card
26Emergency passport
27Alien's passport
28Alternative identity card
29Visa ID2
30Visa ID3
32Authorization card
33Beginner permit
34Border crossing card
35Chauffeur license
36Chauffeur license under 18
37Chauffeur license under 21
38Commercial driving license
39Commercial driving license instructional permit
40Commercial driving license under 18
41Commercial driving license under 21
42Commercial instruction permit
43Commercial new permit
44Concealed carry license
45Concealed firearm permit
46Conditional driving license
47Department of veterans affairs identity card
48Diplomatic driving license
49Driving license
50Driving license instructional permit
51Driving license instructional permit under 18
52Driving license instructional permit under 21
53Driving license learners permit
54Driving license learners permit under 18
55Driving license learners permit under 21
56Driving license novice
57Driving license novice under 18
58Driving license novice under 21
59Driving license registered offender
60Driving license restricted under 18
61Driving license restricted under 21
62Driving license temporary visitor
63Driving license temporary visitor under 18
64Driving license temporary visitor under 21
65Driving license under 18
66Driving license under 21
67Employment driving permit
68Enhanced chauffeur license
69Enhanced chauffeur license under 18
70Enhanced chauffeur license under 21
71Enhanced commercial driving license
72Enhanced driving license
73Enhanced driving license under 18
74Enhanced driving license under 21
75Enhanced identity card
76Enhanced identity card under 18
77Enhanced identity card under 21
78Enhanced operators license
79Firearms permit
80Full provisional license
81Full provisional license under 18
82Full provisional license under 21
83Geneva conventions identity card
84Graduated driving license under 18
85Graduated driving license under 21
86Graduated instruction permit under 18
87Graduated instruction permit under 21
88Graduated license under 18
89Graduated license under 21
90Handgun carry permit
91Identity and privilege card
92Identity card mobility impaired
93Identity card registered offender
94Identity card temporary visitor
95Identity card temporary visitor under 18
96Identity card temporary visitor under 21
97Identity card under 18
98Identity card under 21
99Other
100Ignition interlock permit
101Immigrant visa
102Instruction permit
103Instruction permit under 18
104Instruction permit under 21
105Interim driving license
106Interim identity card
107Intermediate driving license
108Intermediate driving license under 18
109Intermediate driving license under 21
110Junior driving license
111Learner instructional permit
112Learner license
113Learner license under 18
114Learner license under 21
115Learner permit
116Learner permit under 18
117Learner permit under 21
118Limited license
119Limited permit
120Limited term driving license
121Limited term identity card
122Liquor identity card
123New permit
124New permit under 18
125New permit under 21
126Non-US citizen driving license
127Occupational driving license
128Oneida tribe of indians identity card
129Operator license
130Operator license under 18
131Operator license under 21
132Permanent driving license
133Permit to re-enter
134Probationary auto license
135Probationary driving license under 18
136Probationary driving license under 21
137Probationary vehicle sales person license
138Provisional driving license
139Provisional driving license under 18
140Provisional driving license under 21
141Provisional license
142Provisional license under 18
143Provisional license under 21
144Public passenger chauffeur license
145Racing and gaming comission card
146Refugee travel document
147Renewal permit
148Restricted commercial driver license
149Restricted driver license
150Restricted permit
151Seasonal permit
152Seasonal resident identity card
153Seasonal citizen identity card
154Sex offender
155Social security card
156Temporary driving license
157Temporary driving license under 18
158Temporary driving license under 21
159Temporary identity card
160Temporary instruction permit identity card
161Temporary instruction permit identity card under 18
162Temporary instruction permit identity card under 21
163Temporary visitor driving license
164Temporary visitor driving license under 18
165Temporary visitor driving license under 21
166Uniformed services identity card
167Vehicle sales person license
168Worker identification credential
169Commercial driving license novice
170Commercial driving license novice under 18
171Commercial driving license novice under 21
172Passport card
173Passport resident card
174Personal identification verification
175Temporary operator license
176Driving license under 19
177Identity card under 19
178Visa
179Temporary passport
180Voting card
181Health card
182Certificate of citizenship
183Address card
184Airport immigration card
185Alien registration card
186APEH card
187Coupon to driving license
188Crew member certificate
189Document for return
190E-card
191Employment card
192HKSAR immigration form
193Immigrant card
194Labour card
195Laissez passer
196Lawyer identity certificate
197License card
198Passport stateless
199Passport child
200Passport consular
201Passport diplomatic service
202Passport official
203Passport provisional
204Passport special
205Permission to the local border traffic
206Registration certificate
207Sedesol card
208Social card
209TB card
210Vehicle passport
211W document
212Diplomatic identity card
213Consular identity card
214Income tax card
215Residence permit
216Document of identity
217Border crossing permit
218Passport limited validity
219Sim card
220Tax card
221Company card
222Domestic passport
223Identity certificate
224Resident id card
225Armed forces identity card
226Professional card
227Registration stamp
228Driver card
229Driver training certificate
230Qualification driving license
231Membership card
232Public vehicle driver authority card
233Marine license
234Temporary learner license
235Temporary commercial driving license
236Interim instructional permit
237Certificate of competency
238Certificate of proficiency
239Trade license
240Passport page
241Invoice
242Passenger locator form

Fields types

IDName
0Document class code
1Issuing state code
2Document number
3Date of expiry
4Date of issue
5Date of birth
6Place of birth
7Personal number
8Surname
9Given name(s)
10Mother's name
11Nationality
12Sex
13Height
14Weight
15Eyes color
16Hair color
17Address
18Donor
19Social security number
20DL class
21DL endorsement code
22DL restriction code
23Date of 21st birthday
24Issuing authority
25Surname and given names
26Nationality code
27Passport number
28Invitation number
29Visa ID
30Visa class
31Visa subclass
35MRZ type
36Optional data
37Document class name
38Issuing state name
39Place of issue
40Document number checksum
41Date of birth checksum
42Date of expiry checksum
43Personal number checksum
44Final checksum
45Passport number checksum
46Invitation number checksum
47Visa ID checksum
48Surname and given names checksum
49Visa valid until checksum
50Other
51MRZ strings
52Name suffix
53Name prefix
54Date of issue checksum
55Date of issue check digit
56Document series
57Registration number
58Vehicle model
59Vehicle color
60Vehicle body number
61Vehicle type
62Max permissible weight
63Unladen mass
64Address: area
65Address: state
66Address: building
67Address: house
68Address: flat
69Place of registration
70Date of registration
71Resident from
72Resident until
73Issuing authority code
74Place of birth: area
75Place of birth: state code
76Address: street
77Address: city
78Address: jurisdiction code
79Address: postal code
80Document number check digit
81Date of birth check digit
82Date of expiry check digit
83Personal number check digit
84Final check digit
85Passport number check digit
86Invitation number check digit
87Visa ID check digit
88Surname and given names check digit
89Visa valid until check digit
90Permit class
91Permit expiry date
92Permit identifier
93Permit issue date
94Permit restriction code
95Permit endorsement code
96Issue timestamp
97Number of duplicates
98Medical indicator codes
99Non-resident indicator
100Visa type
101Visa valid from
102Visa valid until
103Duration of stay
104Number of entries
105Day
106Month
107Year
108Unique customer identifier
109Commercial vehicle code
110AKA: date of birth
111AKA: social insurance number
112AKA: surname
113AKA: given name(s)
114AKA: name suffix
115AKA: name prefix
116Mailing address: street
117Mailing address: city
118Mailing address: jurisdiction code
119Mailing address: postal code
120Number for validation
121Inventory number
122Race ethnicity
123Jurisdiction vehicle class
124Jurisdiction endorsement code
125Jurisdiction restriction code
126Family name
127Given name(s) (national)
128Visa ID (national)
129Father's name
130Father's name (national)
131Surname and given names (national)
132Place of birth (national)
133Issuing authority (national)
134Issuing state code (numeric)
135Nationality code (numeric)
136Engine power
137Engine volume
138Chassis number
139Engine number
140Engine model
141Vehicle category
142Identity card number
143Control number
144Parents' given names
145Second surname
146Middle name
147Vehicle identification number
148VIN check digit
149VIN checksum
150Line 1 check digit
151Line 2 check digit
152Line 3 check digit
153Line 1 checksum
154Line 2 checksum
155Line 3 checksum
156Registration number check digit
157Registration number checksum
158Vehicle ITS code
159Card access number
160Marital status
161Company name
162Special notes
163Spouse's surname
164Tracking number
165Booklet number
166Children
167Copy
168Serial number
169Dossier number
170AKA: surname and given names
171Territorial validity
172MRZ strings with correct checksums
173CDL restriction code
174Date of 18th birthday
175DL record created
176DL date of duplicate issue
177Card type
178Military ID number
179Destination
180Blood group
181Sequence number
182Body type
183Vehicle make
184Transaction number
185Age
186Folio number
187Voter key
188Address: municipality
189Address: location
190Section
191OCR number
192Federal elections
193Reference number
194Optional data checksum
195Optional data check digit
196Visa number
197Visa number checksum
198Visa number check digit
199Voter
200Type of the previous document
220Field from MRZ
221Current date
251Status date of expiry
252Banknote number
253CSC code
254Pseudonym
255Academic title
256Address country
257Address ZIP code
258eID residence permit 1
259eID residence permit 2
260eID place of birth: street
261eID place of birth: city
262eID place of birth: state
263eID place of birth: country
264eID place of birth: postal code
265CDL class
266Date of 19th birthday
267Weight (pound)
268Indicator of document limited duration
269Endorsement expiration date
270Revision date
271Compliance type
272Family name truncation
273First name truncation
274Middle name truncation
275Exam date
276Organization
277Department
278Pay grade
279Rank
280Benefits number
281Sponsor service
282Sponsor status
283Sponsor
284Relationship
285USCIS
286Category
287Conditions
288Identifier
289Configuration
290Discretionary data
291Line 1 optional data
292Line 2 optional data
293Line 3 optional data
294EQV code
295ALT code
296Binary code
297Pseudo code
298Fee
299Stamp number
300SBH security options
301SBH integrity options
302Date of creation
303Validity period
304Patron header version
305BDB type
306Biometric type
307Biometric subtype
308Biometric product ID
309Biometric format owner
310Biometric format type
311Phone
312Profession
313Position
314Personal data summary
315Other valid ID
316Custody info
317Other name
318Observations
319Tax
320Personalization date
321Personalization SN
322Other person name
323Notify person: date of record
324Notify person: name
325Notify person: phone
326Notify person: address
327DS certificate issuer
328DS certificate subject
329DS certificate valid from
330DS certificate valid to
331Vehicle data from the DG1 data group
332Type of approval number
333Administrative number
334Document discriminator
335Data discriminator
336ID number of ISO issuer
340GNIB number
341Department number
342Telegraph code
343Allergies
344Special code
345Court code
346County
347Sponsor SSN
348DoD number
349Expiry date of Motorcycle Novice status
350DUF number
351AGY
352PNR code
353Code of the airport of departure
354Code of the airport of arrival
355Flight number
356Date of flight
357Seat number
358Date of boarding pass issue
359CCW until
360Reference number checksum
361Reference number check digit
362Room number
363Religion
364Months to expire
365Electronic ticket indicator
366Compartment code
367Check-in sequence number
368Airline designator of boarding pass issuer
369Airline numeric code
370Ticket number
371Frequent flyer airline designator
372Frequent flyer number
373Free baggage allowance
374PDF417 codec
375Identity card number checksum
376Identity card number check digit
377Veteran
378DL category A1 valid from
379DL category A1 valid to
380DL category A1 codes
381DL category A valid from
382DL category A valid to
383DL category A codes
384DL category B valid from
385DL category B valid to
386DL category B codes
387DL category C1 valid from
388DL category C1 valid to
389DL category C1 codes
390DL category C valid from
391DL category C valid to
392DL category C codes
393DL category D1 valid from
394DL category D1 valid to
395DL category D1 codes
396DL category D valid from
397DL category D valid to
398DL category D codes
399DL category BE valid from
400DL category BE valid to
401DL category BE codes
402DL category C1E valid from
403DL category C1E valid to
404DL category C1E codes
405DL category CE valid from
406DL category CE valid to
407DL category CE codes
408DL category D1E valid from
409DL category D1E valid to
410DL category D1E codes
411DL category DE valid from
412DL category DE valid to
413DL category DE codes
414DL category M valid from
415DL category M valid to
416DL category M codes
417DL category L valid from
418DL category L valid to
419DL category L codes
420DL category T valid from
421DL category T valid to
422DL category T codes
423DL category AM valid from
424DL category AM valid to
425DL category AM codes
426DL category A2 valid from
427DL category A2 valid to
428DL category A2 codes
429DL category B1 valid from
430DL category B1 valid to
431DL category B1 codes
432Surname at birth
433Civil status
434Number of seats
435Number of standing places
436Max speed
437Fuel type
438Vehicle environmental type
439Power-to-weight ratio
440Max mass of trailer (braked)
441Max mass of trailer (unbraked)
442Transmission type
443Trailer hitch
444Accompanied by
445Police district
446First issue date
447Payload capacity
448Number of axles
449Permissible axle load
450Precinct
451Invited by
452Purpose of entry
453Skin color
454Complexion
455Airport of departure
456Airport of arrival
457Airline name
458Airline loyalty program for frequent flyers
459License number
460In tanks
461Other than tanks
462Fast Track service
463Owner
464MRZ strings from ICAO RFID
465Number of card issuances
466Number of card issuances checksum
467Number of card issuances check digit
468Century of birth
469DL category A3 valid from
470DL category A3 valid to
471DL category A3 codes
472DL category C2 valid from
473DL category C2 valid to
474DL category C2 codes
475DL category B2 valid from
476DL category B2 valid to
477DL category B2 codes
478DL category D2 valid from
479DL category D2 valid to
480DL category D2 codes
481DL category B2E valid from
482DL category B2E valid to
483DL category B2E codes
484DL category G valid from
485DL category G valid to
486DL category G codes
487DL category J valid from
488DL category J valid to
489DL category J codes
490DL category LC valid from
491DL category LC valid to
492DL category LC codes
493Bank card number
494Bank card validity
495Tax number
496Health insurance number
497Grandfather's name
498Selectee indicator
499Mother's surname
500Mother's name
501Father's surname
502Father's name
503Mother's date of birth
504Father's date of birth
505Mother's personal number
506Father's personal number
507Mother's place of birth
508Father's place of birth
509Mother's country of birth
510Father's country of birth
511Date of first renewal
512Date of second renewal
513Place of examination
514Application number
515Voucher number
516Authorization number
517Faculty
518Form of education
519DNI number
520Retirement number
521Professional id number
522Age at issue
523Years since issue
524DL category BTP valid from
525DL category BTP codes
526DL category BTP valid to
527DL category C3 valid from
528DL category C3 codes
529DL category C3 valid to
530DL category E valid from
531DL category E codes
532DL category E valid to
533DL category F valid from
534DL category F codes
535DL category F valid to
536DL category FA valid from
537DL category FA codes
538DL category FA valid to
539DL category FA1 valid from
540DL category FA1 codes
541DL category FA1 valid to
542DL category FB valid from
543DL category FB codes
544DL category FB valid to
545DL category G1 valid from
546DL category G1 codes
547DL category G1 valid to
548DL category H valid from
549DL category H codes
550DL category H valid to
551DL category I valid from
552DL category I codes
553DL category I valid to
554DL category K valid from
555DL category K codes
556DL category K valid to
557DL category LK valid from
558DL category LK codes
559DL category LK valid to
560DL category N valid from
561DL category N codes
562DL category N valid to
563DL category S valid from
564DL category S codes
565DL category S valid to
566DL category TB valid from
567DL category TB codes
568DL category TB valid to
569DL category TM valid from
570DL category TM codes
571DL category TM valid to
572DL category TR valid from
573DL category TR codes
574DL category TR valid to
575DL category TV valid from
576DL category TV codes
577DL category TV valid to
578DL category V valid from
579DL category V codes
580DL category V valid to
581DL category W valid from
582DL category W codes
583DL category W valid to
584URL
585Caliber
586Model
587Make
588Number of cylinders
589Surname of husband after registration
590Surname of wife after registration
591Date of birth of wife
592Date of birth of husband
593Citizenship of first person
594Citizenship of second person
595CVV code
596Date of insurance expiry
597Mortgage by
598Old document number
599Old date of issue
600Old place of issue
601DL category LR valid from
602DL category LR valid to
603DL category LR codes
604DL category MR valid from
605DL category MR valid to
606DL category MR codes
607DL category HR valid from
608DL category HR valid to
609DL category HR codes
610DL category HC valid from
611DL category HC valid to
612DL category HC codes
613DL category MC valid from
614DL category MC valid to
615DL category MC codes
616DL category RE valid from
617DL category RE valid to
618DL category RE codes
619DL category R valid from
620DL category R valid to
621DL category R codes
622DL category CA valid from
623DL category CA valid to
624DL category CA codes
625Citizenship status
626Military service from
627Military service to
628DL category NT valid from
629DL category NT valid to
630DL category NT codes
631DL category TN valid from
632DL category TN valid to
633DL category TN codes
634DL category D3 valid from
635DL category D3 valid to
636DL category D3 codes
637Alternative date of expiry
638DL category CD valid from
639DL category CD valid to
640DL category CD codes
641Issuer identification number
642Payment period from
643Payment period to
644Vaccination certificate identifier
645First name
646Date of arrival
647Second name
648Third name
649Fourth name
650Last name
651DL category RM valid from
652DL category RM codes
653DL category RM valid to
654DL category PW valid from
655DL category PW codes
656DL category PW valid to
657DL category EB valid from
658DL category EB codes
659DL category EB valid to
660DL category EC valid from
661DL category EC codes
662DL category EC valid to
663DL category EC1 valid from
664DL category EC1 codes
665DL category EC1 valid to
666Place of birth city
667Year of birth
668Year of expiry
669Grandfather's name (maternal)
670First surname
671Month of birth
672Floor number
673Entrance number
674Block number
675Street number
676Street type
677City sector
678County type
679City type
680Building type

Image types

IDName
201Document holder photo
202Fingerprint of document holder
203Image of the iris of document holder
204Signature of document holder
205Barcode image
206Image of document confirming owner citizenship
207Cropped and rotated with perspective compensation (front side) of a document. Single input image can contain multiple document side/pages, which will be returned as separated results. Most coordinates in other types defined on that image.
208Image of the rear side of the document
209Area with dynamic color change
210Additional Portrait
211Stamp
250Undefined image type
300Fingerprint (thumb, left hand)
301Fingerprint (index, left hand)
302Fingerprint (middle, left hand)
303Fingerprint (ring, left hand)
304Fingerprint (little, left hand)
305Fingerprint (thumb, right hand)
306Fingerprint (index, right hand)
307Fingerprint (middle, right hand)
308Fingerprint (ring, right hand)
309Fingerprint (little, right hand)
313Fingerprint (four without thumb on right hand)
314Fingerprint (four without thumb on left hand
315Fingerprint (two thumbs)

Language codes

CodeLocale
laLatin
afAfrikaans
sqAlbanian
ar-DZArabic (Algeria)
ar-BHArabic (Bahrain)
ar-EGArabic (Egypt)
ar-IQArabic (Iraq)
ar-JOArabic (Jordan)
ar-KWArabic (Kuwait)
ar-LBArabic (Lebanon)
ar-LYArabic (Libya)
ar-MAArabic (Morocco)
ar-OMArabic (Oman)
ar-QAArabic (Qatar)
ar-SAArabic (Saudi Arabia)
ar-SYArabic (Syria)
ar-TNArabic (Tunisia)
ar-AEArabic (U.A.E.)
ar-YEArabic (Yemen)
hyArmenian
az-AZAzeri (Cyrillic)
azAzeri (Latin)
euBasque
beBelarusian
bgBulgarian
caCatalan
zh-HKChinese (HongKong S.A.R.)
zh-MOChinese (Macao S.A.R.)
zhChinese
zh-SGChinese (Singapore)
zh-TWChinese (Taiwan)
hrCroatian
csCzech
daDanish
dvDivehi
nl-BEDutch (Belgium)
nl-NLDutch (Netherlands)
en-AUEnglish (Australia)
en-BZEnglish (Belize)
en-CAEnglish (Canada)
en-CBEnglish (Caribbean)
en-IEEnglish (Ireland)
en-JMEnglish (Jamaica)
en-NZEnglish (New Zealand)
en-PHEnglish (Philippines)
en-ZAEnglish (South Africa)
en-TTEnglish (Trinidad)
en-GBEnglish (United Kingdom)
en-USEnglish (United States)
en-ZWEnglish (Zimbabwe)
etEstonian
fo_FOFaeroese
faFarsi
fiFinnish
fr-BEFrench (Belgium)
fr-CAFrench (Canada)
fr-FRFrench (France)
fr-LUFrench (Luxembourg)
fr-MCFrench (Monaco)
fr-CHFrench (Switzerland)
mk-MKFYRO Macedonian
glGalician
kaGeorgian
de-ATGerman (Austria)
de-DEGerman (Germany)
de-LIGerman (Liechtenstein)
de-LUGerman (Luxembourg)
de-CHGerman (Switzerland)
elGreek
guGujarati
heHebrew
hi-INHindi (India)
huHungarian
isIcelandic
idIndonesian
it-ITItalian (Italy)
it-CHItalian (Switzerland)
jaJapanese
knKannada
kkKazakh
kokKonkani
koKorean
ky-CyrlKyrgyz (Cyrillic)
lvLatvian
ltLithuanian
ms-MYMalay (Malaysia)
ms-BNMalay (Brunei Darussalam)
mrMarathi
mn-CyrlMongolian (Cyrillic)
nbNorwegian (Bokmal)
nn-NONorwegian (Nynorsk)
plPolish
pt-BRPortuguese (Brazil)
pt-PTPortuguese (Portugal)
paPunjabi
rmRhaeto-Romanic
roRomanian
ruRussian
saSanskrit
sr-CyrlSerbian (Cyrillic)
sr-LatnSerbian (Latin)
skSlovak
slSlovenian
es-ARSpanish (Argentina)
es-BOSpanish (Bolivia)
es-CLSpanish (Chile)
es-COSpanish (Colombia)
es-CRSpanish (Costa Rica)
es-DOSpanish (Dominican Republic)
es-ECSpanish (Ecuador)
es-SVSpanish (El Salvador)
es-GTSpanish (Guatemala)
es-HNSpanish (Honduras)
es-MXSpanish (Mexico)
es-NISpanish (Nicaragua)
es-PASpanish (Panama)
es-PYSpanish (Paraguay)
es-PESpanish (Peru)
es-PRSpanish (Puerto Rico)
esSpanish (Traditional Sort)
esSpanish (International Sort)
es-UYSpanish (Uruguay)
es-VESpanish (Venezuela)
swSwahili
svSwedish
sv-FISwedish (Finland)
syrSyriac
taTamil
ttTatar
teTelugu
th-THThai (Thailand)
trTurkish
tg-TJTajik (Cyrillic)
tkTurkmen
ukUkrainian
urUrdu
uz-CyrlUzbek (Cyrillic)
uz-LatnUzbek (Latin)
viVietnamese
zh-HansCTC Simplified
zh-HantCTC Traditional
Response structure
                    {
    "identity_document": {
        "documents": [
            {
                "name": "Kazakhstan - ePassport (2009)",
                "type": 11,
                "country": "KZ",
                "list_index": 0,
                "page_index": 0
            }
        ],
        "statuses": {
            "expiration": true,
            "validation_fields": true,
            "comparison_fields": true,
            "mrz": true,
            "overall": true
        },
        "fields": [
            {
                "field_id": 0,
                "field_name": "document class code",
                "source_id": 2,
                "source_name": "mrz",
                "value": "P",
                lang": "la",
                "validity_status": true,
                "comparison_status": true,
                "values": [
                    {
                        "source_id": 2,
                        "source_name": "mrz",
                        "value": "P",
                        "validity_status": true,
                        "page_index": 0
                    },
                    {
                        "source_id": 1,
                        "source_name": "visual",
                        "value": "P",
                        "validity_status": null,
                        "page_index": 0
                    }
                ]
            },
            ...
        ],
        "images": [
            {
                "field_id": 201,
                "field_name": "portrait",
                "source_id": 1,
                "source_name": "visual",
                "page_index": 1,
                "original_page_index": 1,
                "value": "/9j/4AAQSkZJRgABA...",
                "width": 383,
                "height": 502
            },
            ...
        ],
        "more_pages_available": 0,
        "processing_time": 1022
    }
}

Blacklists check

Persons

This method retrieves information about applicants from the Kycaid blacklist databases, providing compliance checks with laws and regulations.

URL: https://api.kycaid.com/bdb/persons

Method: POST

Request
                    curl https://api.kycaid.com/bdb/persons \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "first_name": "{first_name}",
        "last_name": "{last_name}",
        "middle_name": "{middle_name}",
        "residence_country": "{residence_country}",
        "dob": "{dob}",
        "bdb_types": "{bdb_types}"
    }'
Example
            curl https://api.kycaid.com/bdb/persons \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "first_name": "Johnson",
        "last_name": "Brown",
        "middle_name": "Abraham",
        "residence_country": "UK",
        "dob": "2012-10-18",
        "bdb_types": "WANTED,PEP"
    }'

Request

ParameterDescription
full_name
string (100) Required *
An applicant's full name. Full name or first name with last name are required.
first_name
string (64) Required *
An applicant's first name. Full name or first name with last name are required.
last_name
string (64) Required *
An applicant's last name. Full name or first name with last name are required.
middle_name
string (64)
An applicant's middle name
dob
string
An applicant's date of birth
residence_country
string
An applicant's residence country
bdb_types
Array
Type of blacklist databases: SANCTIONS, PEP, SELF_RESTRICTED, WANTED, EXPIRED

Response

ParameterDescription
data.name
string
An applicant's full name
data.origin_name
string
An applicant's full name in applicant's language
data.first_name
string
An applicant's first name
data.origin_first_name
string
An applicant's first name in applicant's language
data.last_name
string
An applicant's last name
data.origin_last_name
string
An applicant's last name in applicant's language
data.middle_name
string
An applicant's middle name
data.origin_middle_name
string
An applicant's middle name in applicant's language
data.residence_country
string (2)
An applicant's residence country
data.dob
string
An applicant's date of birth
data.gender
string
An applicant's gender
data.description
string
A detailed description of applicant's status
data.bdb_name
string
A blacklist database name
data.bdb_type
string
A type of blacklist database
data.accuracy
string
An accuracy of provided information in percents

Error types

TypeMessage
not_foundInformation not found
Response structure
                    {
    "errors": [
        {
            "type": "{type}",
            "message": "{message}"
        }
    ],
    "data": [
        {
            "name": "{name}",
            "origin_name": "{origin_name}",
            "first_name": "{first_name}",
            "origin_first_name": "{origin_first_name}",
            "last_name": "{last_name}",
            "origin_last_name": "{origin_last_name}",
            "middle_name": "{middle_name}",
            "origin_middle_name": "{origin_middle_name}",
            "residence_country": "{residence_country}",
            "dob": "{dob}",
            "gender": "{gender}",
            "description": "{description}",
            "bdb_name": "{bdb_name}",
            "bdb_type": "{bdb_type}",
            "accuracy": "{accuracy}"
        }
    ]
}

Tax id

This method retrieves information on tax IDs from the Kycaid blacklist databases.

URL: https://api.kycaid.com/bdb/tax-ids

Method: POST

Request
                curl https://api.kycaid.com/bdb/tax-ids \
-H 'Authorization: Token {API_TOKEN}' \
-X POST \
-d '{
    "tax_id_number": "{tax_id_number}",
    "tax_id_country": "{tax_id_country}",
    "bdb_types": "{bdb_types}"
}'
Example
        curl https://api.kycaid.com/bdb/tax-ids \
-H 'Authorization: Token {API_TOKEN}' \
-X POST \
-d '{
    "tax_id_number": "1129821775",
    "tax_id_country": "UK",
    "bdb_types": "WANTED,PEP"
}'

Request

ParameterDescription
tax_id_number
string (2-32) Required *
A tax identification number (tax ID number).
tax_id_country
string (2)
An issuing country of a tax ID.
bdb_types
Array
Type of blacklist databases: SANCTIONS, PEP, SELF_RESTRICTED, WANTED, EXPIRED

Response

ParameterDescription
data.tax_id_number
string
A tax identification number (tax ID number)
data.tax_id_country
string (2)
An issuing country of a tax ID
data.description
string
An additional information regarding a tax ID
data.bdb_name
string
A name of a blacklist database where a tax ID was found
data.bdb_type
string
A type of blacklist databases where a tax ID appeared

Error types

TypeMessage
not_foundInformation not found
Response structure
                {
"errors": [
    {
        "type": "{type}",
        "message": "{message}"
    }
],
"data": [
    {
        "tax_id_number": "1129821775",
        "tax_id_country": "GB",
        "bdb_name": "Open Sanctions Peps",
        "bdb_type": "SANCTIONS"
    }
]
}

Document

This method retrieves information on documents from the Kycaid blacklist databases.

URL: https://api.kycaid.com/bdb/documents

Method: POST

Request
                curl https://api.kycaid.com/bdb/documents \
-H 'Authorization: Token {API_TOKEN}' \
-X POST \
-d '{
    "document_number": "{document_number}",
    "document_type": "{document_type}",
    "document_country": "{document_country}",
    "bdb_types": "{bdb_types}"
}'
Example
        curl https://api.kycaid.com/bdb/documents \
-H 'Authorization: Token {API_TOKEN}' \
-X POST \
-d '{
    "document_number": "920927306325",
    "document_type": "PASSPORT",
    "document_country": "GB",
    "bdb_types": "WANTED,PEP"
}'

Request

ParameterDescription
document_number
string (2-32) Required *
A number of a document to check with blacklist databases.
document_type
string
Type of a document: PASSPORT, DOMESTIC_PASSPORT, GOVERNMENT_ID, DRIVERS_LICENSE, FOREIGN_CITIZEN_PASSPORT, PERMANENT_RESIDENCE_PERMIT , REFUGEE_CARD
document_country
string (2)
An issuing country of a document.
bdb_types
Array
Type of blacklist databases: SANCTIONS, PEP, SELF_RESTRICTED, WANTED, EXPIRED

Response

ParameterDescription
data.document_number
string
A number of a document
data.document_type
string (2)
A type of a document
data.document_country
string (2)
An issuing country of a document
data.description
string
An additional information regarding a document
data.bdb_name
string
A name of a blacklist database where a document was found
data.bdb_type
string
A type of blacklist databases where information from a document appeared

Error types

TypeMessage
not_foundInformation not found
Response structure
                {
"errors": [
    {
        "type": "{type}",
        "message": "{message}"
    }
],
"data": [
    {
        "document_number": "920927306325",
        "document_type": "PASSPORT",
      "document_country": "GB",
      "bdb_name": "NAZK Sanctions",
      "bdb_type": "SANCTIONS"
    }
]
}

Crypto check

Address verification

URL: https://api.kycaid.com/services/crypto/address-verification

Method: POST

Request
                    curl https://api.kycaid.com/services/crypto/address-verification \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "hash": "{hash}",
        "asset": "{asset}",
        "callback_url": "{callback_url}",
    }'
Example
            curl https://api.kycaid.com/services/crypto/address-verification \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "hash": "3HQBsRNJcnzk4kcGxMabFMqD6Ud23T5eUd",
        "asset": "BTC",
        "callback_url": "https://yourwebsite.com",
    }'

Request

ParameterDescription
hash
string (16,128) Required *
An crypto address.
asset
string (5) Required *
Currency that will be checked (BTC, BCH, LTC, XRP, ETC, ADA, ETH, TRX, ALGO, XLM, MATIC, ZEC, DOGE, SOL, BSV, AVAX, ARB, DOT, TetherOMNI, TON, XTZ, NEAR).
callback_url
string (5) Required *
The url to which you will receive a callback with data after verification is completed. *It can take from 30 seconds to 10 minutes.

Response

ParameterDescription
data.service_request_id
string (36)
Unique service request id.
Response structure
                    {
    "data": {
        "service_request_id": "{service_request_id}"
    }
}

Transaction verification

URL: https://api.kycaid.com/services/crypto/transaction-verification

Method: POST

Request
                    curl https://api.kycaid.com/services/crypto/transaction-verification \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "hash": "{hash}",
        "address": "{address}"
        "asset": "{asset}"
        "direction": "{direction}",
        "callback_url": "{callback_url}",
    }'
Example
            curl https://api.kycaid.com/services/crypto/transaction-verification \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "hash": "41a57df436157b92d5d61cdd36dd43d5f4734cbeee7f4f4809b91cc2a7b2a520",
        "address": "12mxdS6cmFmQgRDhboAqD5q9umtjVq6pE7",
        "asset": "BTC"
        "direction": "withdrawal",
        "callback_url": "https://yourwebsite.com",
    }'

Request

ParameterDescription
hash
string (16,128) Required *
Verified transaction.
address
string (16,128) Required *
Address (BTC, BCH, LTC, XRP, ETC, ADA, ETH, TRX, ALGO, XLM, MATIC) where the funds were accepted
asset
string (5) Required *
Currency that will be checked (BTC, BCH, LTC, XRP, ETC, ADA, ETH, TRX, ALGO, XLM, MATIC, ZEC, DOGE, SOL, BSV, AVAX, ARB, DOT, TetherOMNI, TON, XTZ, NEAR).
direction
deposit|withdrawal Required *
If the funds were sent to your address, direction = deposit, if you sent the funds from your address, direction = withdrawal
callback_url
string (5) Required *
The url to which you will receive a callback with data after verification is completed. *It can take from 30 seconds to 10 minutes.

Response

ParameterDescription
data.service_request_id
string (36)
Unique service request id.
Response structure
                    {
    "data": {
        "service_request_id": "{service_request_id}"
    }
}

Qualified electronic signature

SmartID

SmartID start

URL: https://api.kycaid.com/services/ua/smartid/start

Method: POST

Request
                    curl https://api.kycaid.com/services/ua/smartid/start \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "verification_id": "{verification_id}"
    }'

Request

ParameterDescription
verification_id
string (36) Required
The verification’s unique identificator.

Response

ParameterDescription
status
string
Status of sign. Possible values:
need_sign
forbidden
error
data.verification_id
string (36)
The verification’s unique identificator.
data.confirmation_url
string
The URL for opening SmartID application.
Response structure
                    {
    "status": "need_sign"
    "data": {
        "verification_id": "{verification_id}",
        "confirmation_url": "{confirmation_url}"
    }
}

SmartID status

URL: https://api.kycaid.com/services/ua/smartid/status

Method: POST

Request
                    curl https://api.kycaid.com/services/ua/smartid/status \
    -H 'Authorization: Token {API_TOKEN}' \
    -X POST \
    -d '{
        "verification_id": "{verification_id}"
    }'

Request

ParameterDescription
verification_id
string (36) Required
The verification’s unique identificator.

Response

ParameterDescription
status
string
Status of sign. Possible values:
need_sign
signed
waiting
forbidden
error
data.verification_id
string (36)
The verification’s unique identificator.
Response structure
                    {
    "status": "waiting",
    "data": {
        "verification_id": "{verification_id}"
    }
}

Examples

KYC

Step 1. Create applicant

First step - it's creation of applicant with type PERSON. Details
To present a list of residence countries, you must use appropriate API.
Create applicant request
                    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": "[email protected]"
    }'
Create applicant response
                    {
    "applicant_id": "<applicant_id>"
}

Step 2. Create applicant document

Create file for document. Details
Create document with type PASSPORT. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create applicant document request
                    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>"
    }'
Create applicant document response
                    {
    "document_id": "<document_id>"
}

Step 3. Create applicant selfie

Create file for document. Details
Create document with type SELFIE_IMAGE. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create applicant selfie request
                    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>"
    }'
Create applicant selfie response
                    {
    "document_id": "<document_id>"
}

Step 4. Create verification

Create verification request with DOCUMENT and FACIAL types. Details
Create verification request
                    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>"
        }'
Create verification response
                    {
    "verification_id": "<verification_id>"
}

KYB

Step 1. Create applicant

First step - it's creation of applicant with type COMPANY. Details
To present a list of business activities, you must use appropriate API.
To present a list of registration countries, you must use appropriate API.
Create applicant request
                    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": "[email protected]"
        "phone": "4089961010",
        "registration_country": "US"
    }'
Create applicant response
                    {
    "applicant_id": "<applicant_id>"
}

Step 2. Create applicant business address

Create business address for applicant. Details
Create business address request
                    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"
    }'
Create business address response
                    {
    "address_id": "<address_id>"
}

Step 3. Create applicant registered address

Create registered address for applicant. Details
Create registered address request
                    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"
    }'
Create registered address response
                    {
    "address_id": "<address_id>"
}

Step 4. Create registration company document

Create file for document. Details
Create document with type REGISTRATION_COMPANY. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create registration company document request
                    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>"
    }'
Create registration company document response
                    {
    "document_id": "<document_id>"
}

Step 5. Create legal address document

Create file for document. Details
Create document with type COMPANY_LEGAL_ADDRESS. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create legal address document request
                    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>"
    }'
Create legal address document response
                    {
    "document_id": "<document_id>"
}

Step 6. Create authorised person document

Create file for document. Details
Create document with type AUTHORISED_PERSON. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create authorised person document request
                    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>"
    }'
Create authorised person document response
                    {
    "document_id": "<document_id>"
}

Step 7. Create company ownership document

Create file for document. Details
Create document with type COMPANY_OWNERSHIP. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create company ownership document request
                    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>"
    }'
Create company ownership document response
                    {
    "document_id": "<document_id>"
}

Step 8. Create authorised person

Create affiliated person with type AUTHORISED. Details
To present a list of residence countries, you must use Get country API.
Create authorised person request
                    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": "[email protected]"
    }'
Create authorised person response
                    {
    "affiliated_person_id": "<affiliated_person_id>"
}

Step 9. Create authorised person document

Create file for document. Details
Create document with type PASSPORT. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create authorised person document request
                    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>"
    }'
Create authorised person document response
                    {
    "document_id": "<document_id>"
}

Step 10. Create authorised person address

Create registered address for authorised person. Details
Create authorised person address request
                    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"
    }'
Create authorised person address response
                    {
    "address_id": "<address_id>"
}

Step 11. Create beneficial person

Create affiliated person with type BENEFICIAL. Details
To present a list of residence countries, you must use Get country API.
Create beneficial person request
                    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": "[email protected]"
    }'
Create beneficial person response
                    {
    "affiliated_person_id": "<affiliated_person_id>"
}

Step 12. Create beneficial person document

Create file for document. Details
Create document with type PASSPORT. Details
Create file request
                    curl https://api.kycaid.com/files \
    -H 'Authorization: Token {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -X POST \
    -F 'file=@./my_file.jpg'
Create file response
                    {
    "file_id": "<file_id>"
}
Create beneficial person document request
                    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>"
    }'
Create beneficial person document response
                    {
    "document_id": "<document_id>"
}

Step 13. Create beneficial person address

Create registered address for beneficial person. Details
Create beneficial person address request
                    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"
    }'
Create beneficial person address response
                    {
    "address_id": "<address_id>"
}

Step 14. Create verification

Create verification request with COMPANY type. Details
Create verification request
                    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>"
        }'
Create verification response
                    {
    "verification_id": "<verification_id>"
}