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 nationality. Example: GB (ISO 3166-2)
gender
PERSON
string (1)
The applicant’s gender. International regulations require either "M" or "F".
wallet_address
PERSON
string (50)
The applicant’s cryptocurrency wallet address.
telegram_username
PERSON
string (32)
The applicant’s Telegram username.
pep
PERSON
boolean
Define if applicant is politically exposed person.
custom_field_1
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_2
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_3
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_4
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_5
PERSON
string (2048)
Custom field can be used for storing any customer data.
company_name
COMPANY
string (255) Required for COMPANY
The applicant’s company name.
business_activity_id
COMPANY
string (36) Required for COMPANY
The business activity of applicant’s company. API for getting business activities.
registration_country
COMPANY
string (2) Required for COMPANY
The registration country of applicant’s company. Example: GB (ISO 3166-2)
email
PERSON
COMPANY
string (254)
The applicant’s email address.
phone
PERSON
COMPANY
string (15)
The phone number of applicant.
external_applicant_id
PERSON
COMPANY
string (50)
Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems.
addresses
PERSON
COMPANY
list Address object Required
The addresses associated with the matched applicant.
documents
PERSON
COMPANY
list Document object Required
The documents associated with the matched applicant.
profile_status
PERSON
COMPANY
enum (pending, valid, invalid) Required
The status of profile verification.
decline_reasons
PERSON
COMPANY
list Decline reason Required
List of decline reasons receiving only for profile has invalid status.
verification_status
PERSON
COMPANY
enum (pending, valid, invalid) Required
The status of applicant's last verification.
created_at
PERSON
COMPANY
string Required
Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42".
Applicant object example for type PERSON
                    {
    "applicant_id": "{applicant_id}",
    "type": "PERSON",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "dob": "1970-10-25",
    "residence_country": "GB",
    "gender": "M",
    "email": "john.doe@mail.com",
    "phone": "+44 1632 960615",
    "wallet_address": "1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX",
    "telegram_username": "johndoe",
    "pep": false,
    "profile_status": false,
    "decline_reasons": [
        "WRONG_NAME",
        "WRONG_DOB"
    ],
    "addresses": [
        {
            "address_id": "{address_id}",
            "type": "REGISTERED",
            "status": "valid",
            "full_address": null,
            "country": "GB",
            "state_or_province": "Westminster",
            "city": "London",
            "postal_code": "SW1A 2AB",
            "street_name": "Downing St",
            "building_number": "10",
            "unit_number": null,
            "created_at": "2020-11-22 14:15:15",
            "decline_reasons": []
        }
    ],
    "documents": [
         {
            "document_id": "{document_id}",
            "type": "PASSPORT",
            "status": "invalid",
            "document_number": "00000000001",
            "issue_date": "2000-01-01",
            "expiry_date": "2020-01-01",
            "income_sources": [],
            "annual_income": null,
            "transaction_amount": null,
            "transaction_purpose": null,
            "origin_funds": null,
            "card_number": null,
            "account_number": null,
            "front_side_id": "{front_side_id}",
            "front_side": "{front_side_url}",
            "back_side_id": null,
            "back_side": null,
            "created_at": "2020-11-22 14:14:56",
            "decline_reasons": [
                "EXPIRED_DOCUMENT"
            ]
        }
    ],
    "verification_status": "invalid",
    "created_at": "2020-01-31 13:52:36"
}

Create applicant

Request

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

Method: POST

Content-Type: application/json

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 nationality. Example: GB (ISO 3166-2)
gender
PERSON
string (1)
The applicant’s gender. International regulations require either "M" or "F".
wallet_address
PERSON
string (50)
The applicant’s cryptocurrency wallet address.
telegram_username
PERSON
string (32)
The applicant’s Telegram username.
pep
PERSON
boolean
Define if applicant is politically exposed person.
custom_field_1
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_2
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_3
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_4
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_5
PERSON
string (2048)
Custom field can be used for storing any customer data.
company_name
COMPANY
string (255) Required for COMPANY
The applicant’s company name.
business_activity_id
COMPANY
string (36) Required for COMPANY
The business activity of applicant’s company. API for getting business activities.
registration_country
COMPANY
string (2) Required for COMPANY
The registration country of applicant’s company. Example: GB (ISO 3166-2)
email
PERSON
COMPANY
string (254)
The applicant’s email address.
phone
PERSON
COMPANY
string (15)
The phone number of applicant.
external_applicant_id
PERSON
COMPANY
string (50)
Custom identifier of the applicant, which is intended for binding the applicant in the customer and KYCAID systems.
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",
        "email": "john.doe@mail.com"
    }'

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
first_name
PERSON
string (50)
The applicant’s first name.
middle_name
PERSON
string (50)
The applicant’s middle name.
last_name
PERSON
string (50)
The applicant’s last name.
dob
PERSON
string (10)
The applicant’s date of birth. (ISO 8601, YYYY-MM-DD)
residence_country
PERSON
string (2)
The applicant’s current nationality. Example: GB (ISO 3166-2)
gender
PERSON
string (1)
The applicant’s gender. International regulations require either "M" or "F".
wallet_address
PERSON
string (50)
The applicant’s cryptocurrency wallet address.
telegram_username
PERSON
string (32)
The applicant’s Telegram username.
pep
PERSON
boolean
Define if applicant is politically exposed person.
custom_field_1
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_2
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_3
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_4
PERSON
string (2048)
Custom field can be used for storing any customer data.
custom_field_5
PERSON
string (2048)
Custom field can be used for storing any customer data.
company_name
COMPANY
string (255)
The applicant’s company name.
business_activity_id
COMPANY
string (36)
The business activity of applicant’s company. API for getting business activities.
registration_country
COMPANY
string (2)
The registration country of applicant’s company. Example: GB (ISO 3166-2)
email
PERSON
COMPANY
string (254)
The applicant’s email address.
phone
PERSON
COMPANY
string (15)
The phone number of applicant.
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"
    }'

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
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 nationality. Example: GB (ISO 3166-2)
gender
PERSON
string (1)
The applicant’s gender. International regulations require either "M" or "F".
pep
PERSON
boolean
Define if applicant is politically exposed person.
company_name
COMPANY
string (255) Required for COMPANY
The applicant’s company name.
business_activity_id
COMPANY
string (36) Required for COMPANY
The business activity of applicant’s company. API for getting business activities.
registration_country
COMPANY
string (2) Required for COMPANY
The registration country of applicant’s company. Example: GB (ISO 3166-2)
email
PERSON
COMPANY
string (254)
The applicant’s email address.
phone
PERSON
COMPANY
string (15)
The phone number of applicant.
addresses
PERSON
COMPANY
list Address object Required
The addresses associated with the matched applicant.
documents
PERSON
COMPANY
list Document object Required
The documents associated with the matched applicant.
profile_status
PERSON
COMPANY
enum (pending, valid, invalid) Required
The status of profile verification.
decline_reasons
PERSON
COMPANY
list Decline reason Required
List of decline reasons receiving only for profile has invalid status.
created_at
PERSON
COMPANY
string Required
Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42".
Response example
                    {
    "applicant_id": "{applicant_id}",
    "type": "PERSON",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "dob": "1970-10-25",
    "residence_country": "GB",
    "gender": null,
    "email": "john.doe@mail.com",
    "phone": null,
    "pep": null,
    "profile_status: false,
    "decline_reasons": [
        "WRONG_NAME",
        "WRONG_DOB"
    ],
    "addresses": [],
    "documents": [],
    "verification_status": "invalid",
    "created_at": "2020-01-31 13:52:36"
}

Documents

Document types

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.
back_side_id
string (36)
The file unique identificator that received in response of Create file.
other_side_1_id
string (36)
The file unique identificator that received in response of Create file.
other_side_2_id
string (36)
The file unique identificator that received in response of Create file.
created_at
string
Date and time when applicant was created. Format "YYYY-MM-DD hh:mm:ss". Example "2005-08-09 18:31:42".
status
string (7)
Status of document verification. Possible values:
null - status of verification is not 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.
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,
    "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.
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.
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
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.
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,
    "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
BUSINESS
ADDITIONAL
full_address
string (255)
The applicant’s full address.
country
string (2)
The country of the applicants’s address. Example: GB (ISO 3166-2)
state_or_province
string (50)
The county, state or province of the applicant’s address.
city
string (50)
The city or town of the applicant’s address.
postal_code
string (20)
The post or zip code of the applicant’s address.
street_name
string (50)
The street name for applicant’s address.
building_number
string (20)
The building number for applicant’s address.
unit_number
string (20)
The unit number for applicant’s address.
Address 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
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 \
    -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
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 nationality. 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",
        "email": "john.doe@mail.com"
    }'

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 nationality. 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",
        "email": "john.doe@mail.com"
    }'

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 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:
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": ""
        }
    }
}

Verification callback

Request

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

Attention. The callback request also include client's API token in http header, that have to be matched from client side by security reasons.
Request example
                    {
    "request_id": "{request_id}",
    "type": "VERIFICATION_COMPLETED",
    "verification_id": "{verification_id}",
    "applicant_id": "{applicant_id}",
    "status": "completed",
    "verified": false,
    "verifications": {
        "profile": {
            "verified": true,
            "comment": "",
            "decline_reasons": []
        },
        "document": {
            "verified": false,
            "comment": "Your document has expired. Please, resubmit the form and upload the valid ID.",
            "decline_reasons": []
        }
    }
}

Response

HTTP status code 2xx is treating as a success sending callback to customer server. Otherwise KYCAID server will repeat callback attempts with such time intervals: 60, 300, 600, 3600, 86400 seconds.

Decline reasons

Verifications decline reasons

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.

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.

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.

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_COMPLETED - type of callback
verification_id
string (36) Required
The verification’s unique identificator.
applicant_id
string (36) Required
The applicant unique identificator.
verification_status
string (9) Required
Status of verification. Possible values:
unused - the applicant has not yet filled out a form
pending - verification of the applicant in progress
completed - verification is completed
Request example
                    {
    "request_id": "{request_id}",
    "type":"VERIFICATION_STATUS_CHANGED",
    "applicant_id":"{applicant_id}",
    "verification_id":"{verification_id}",
    "form_id":"{form_id}",
    "verification_status":"pending"
}

VERIFICATION_COMPLETED

URL: <callback_url>

Method: POST

Content-Type: application/json

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.
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.
Request example
                    {
    "request_id": "{request_id}",
    "type": "VERIFICATION_COMPLETED",
    "verification_id": "{verification_id}",
    "applicant_id": "{applicant_id}",
    "status": "completed",
    "verified": false,
    "verifications": {
        "profile": {
            "verified": true,
            "comment": "",
            "decline_reasons": []
        },
        "document": {
            "verified": false,
            "comment": "Your document has expired. Please, resubmit the form and upload the valid ID.",
            "decline_reasons": []
        }
    },
    "verification_statuses": {
        "duplicates": ["duplicate_applicant_id_1", "duplicate_applicant_id_2"],
        "ludoman": false
    }
}

Callback response

HTTP status code 2xx is treating as a success sending callback to customer server. Otherwise KYCAID server will repeat callback attempts with such time intervals: 1 minute, 5 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours, 24 hours.

Verify callback

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 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>' \
    -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 language
For the setup initial language of form UI, you need to add URL parameter lang. Possible values: de, en, es, fr, kk, pt, uk, ru. Example: https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024/?lang=en
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 *;" to iframe.
Response example
                    {
    "form_id": "{form_id}",
    "form_url": "https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024",
    "verification_id": "{verification_id}"
}


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: 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}"
    }
}

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": "Англійська"
            }
        ]
    }
]

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": "john.doe@mail.com"
    }'
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": "support@apple.com"
        "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": "john.doe@mail.com"
    }'
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": "john.doe@mail.com"
    }'
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>"
}