Imports applicant data and images with verification results to a new applicant profile.
Table of contents
Overview
Use this method to import the applicant data, images, and associated review results via the *.zip
archive submitted in the request body. The archive will be processed, creating a new applicant profile with approved documents in the Sumsub system.
The archive you are submitting must contain:
- The
applicant.json
file that has an applicant entry with review results. Make sure to specify.review.levelName
in this file for the method to work properly. - Directories that include the images to be uploaded and the
applicantIdDoc.json
file with the document information (one file and one image per directory). TheapplicantIdDoc.json
file must always have the object values ofidDocType
andcountry
.
Below, you can find the specifics of importing individual and company applicants with examples of archives and JSON files.
Note
The rate limit for this method: 10 requests per 10 seconds.
Import individual applicants
To import an individual applicant, submit the *.zip archive with the data structured as described in the overview. The number and type of directories depend on and correspond to the required steps configured for the verification level.
Below, you can overview the example of the archive structure and possible values with descriptions of the applicant.json
and applicantIdDoc.json
files.
Archive structure example
The following is an example of the archive structure to create an applicant profile based on the default basic-kyc-level
verification level.
applicant.json
content
applicant.json
contentThe applicant.json
file must contain the applicant entry with review results. See the tables and the JSON file example below for details.
applicant.json
root values
applicant.json
root valuesValue | Type | Required | Description |
---|---|---|---|
externalUserId | String | Yes | Unique applicant identifier as registered on your side:
|
info | Object | Yes | Holds the personal applicant information extracted during verification on your side. |
review | Object | Yes | Explains the details of the applicant verification status and check results on your side. |
info
attributes
info
attributesThe following table explains the info
object attributes representing general applicant information.
Field | Type | Required | Description |
---|---|---|---|
firstName | String | Yes | Applicant first name in the original language. |
middleName | String | No | Applicant middle name in the original language. |
lastName | String | Yes | Applicant last name in the original language. |
legalName | String | No | Legal name of the company the applicant is related to (UBO or shareholder). You can keep this information and use it for your personal navigation. Note that the legalName field is not checked and you might need it just in case. |
gender | String | No | Applicant gender (M or F ). |
dob | Date | No | Applicant date of birth (format YYYY-mm-dd , e.g. 2001-09-25 ). |
placeOfBirth | String | No | Applicant place of birth. This can be a city, a town or another settlement type. |
countryOfBirth | String | No | Applicant country of birth. Presented as an alpha-3 country code (for example, DEU , GBR , ARG , and so on). |
stateOfBirth | String | No | State, region, district, county or another territorial entity of birth inside a country, if applicable. |
country | String | Yes | Applicant country of birth. Presented as an alpha-3 country code (for example, DEU , GBR , ARG , and so on). |
nationality | String | No | Applicant country of origin. Presented as an alpha-3 country code (for example, DEU , GBR , ARG , and so on). |
addresses | Array of objects | No | Includes data objects containing the applicant address details extracted from the PoA documents submitted by the applicant. |
tin | String | No | Taxpayer identification number that is unique to each taxpayer. |
addresses
element fields
addresses
element fieldsThe following table explains the addresses
element fields containing the applicant address details.
Field | Type | Required | Description |
---|---|---|---|
country | String | No | Alpha-3 country code (for example, DEU , GBR , ARG , and so on). |
postCode | String | No | Address postal code. |
town | String | No | City, town, or another settlement. |
state | String | No | State, region, district, county or another territorial entity inside a country. |
street | String | No | Street name. |
subStreet | String | No | Additional information related to the street. This could be a house number or any other details. |
buildingName | String | No | Building name if applicable. |
flatNumber | String | No | Flat or apartment number. |
buildingNumber | String | No | Building number. |
review
attributes
review
attributesThe following table explains the review
object attributes that represent the details of the verification status.
Field | Type | Required | Description |
---|---|---|---|
createDate | Date | No | Date and time when the applicant profile was created on your side in the format: yyyy-MM-dd HH:mm:ss+0000 , for example, 2022-11-21 08:25:32+0000 . |
reviewDate | Date | No | Review date and time on your side in the format: yyyy-MM-dd HH:mm:ss+0000 , for example, 2022-11-21 08:25:32+0000 . |
levelName | String | Yes | Verification level name. The level determines the verification steps the applicant must complete and the documents that are required for verification. β Mind the following:
|
reviewResult | Object | Yes | Contains extra details of the applicant review result. |
reviewStatus | String | Yes | β The applicant review status must be completed only. Otherwise, the applicant data import will fail. |
reviewResult
attributes
reviewResult
attributesThe following table explains the reviewResult
attributes representing the applicant verification result details.
Field | Type | Description |
---|---|---|
moderationComment | String | Human-readable comment that can be shown to the applicant. |
clientComment | String | Internal comment that must not be shown to the applicant. |
reviewAnswer | String | β οΈ Must be GREEN as this method is used to import only approved applicants on your side. |
applicant.json
example
applicant.json
exampleThe following is an example of a typical applicant.json
file for importing individual applicants with the basic-kyc-level
specified. You can always create a file with your own structure within the possible parameters.
{
"externalUserId": "someClientUserId",
"info": {
"firstName": "John",
"lastName": "Snow",
"country": "GBR"
},
"review": {
"createDate": "2022-11-21 08:25:32+0000",
"reviewDate": "2022-11-21 08:25:36+0000",
"levelName": "basic-kyc-level",
"reviewResult": {
"moderationComment": "",
"clientComment": "",
"reviewAnswer": "GREEN"
},
"reviewStatus": "completed"
}
}
Attention
When creating the
applicant.json
file, mind the fields with required values and make sure to specify.review.levelName
of the verification level made particularly for individual applicants.
applicantIdDoc.json
content
applicantIdDoc.json
contentThe applicantIdDoc.json
file represents the object that is used as metadata
to upload an image to the applicant profile. See the following table with the values that can be submitted in the applicantIdDoc.json
file to import an individual applicant.
Value | Type | Required | Description |
---|---|---|---|
idDocType | String | Yes | Type of document that is specified in the level to be provided for verification. See the supported document types that can be specified. |
idDocSubType | String | No | Specify the document side, if required. FRONT_SIDE , BACK_SIDE or null .β οΈ If both sides of the document are required to be submitted, create a directory for each side in the archive, and provide the applicantIdDoc.json file and image for each respectively. |
country | String | Yes | Alpha-3 code (e.g., DEU , GBR , ARG , and so on) of the country where the document was issued. |
firstName | String | No | Applicant first name. |
middleName | String | No | Applicant middle name. |
lastName | String | No | Applicant last name. |
issuedDate | Date | No | Date of the document issue (format YYYY-mm-dd , e.g. 2010-09-25 ). |
validUntil | Date | No | Date when the document validity expires (format YYYY-mm-dd , e.g. 2025-09-25 ). |
number | String | No | Unique registration number of the document. |
dob | Date | No | Applicant date of birth (format YYYY-mm-dd , e.g. 1975-09-25 ). |
placeOfBirth | String | No | Applicant place of birth. This can be a city, a town or another settlement type. |
applicantIdDoc.json
example
applicantIdDoc.json
exampleThe following is an example of a typical applicantIdDoc.json
file for importing individual applicants. You can always create a file with your own structure within the possible parameters.
{
"idDocType": "ID_CARD",
"country": "GBR",
"firstName": "John",
"lastName": "Doe",
"issuedDate": "2020-09-25",
"number": "1234567890",
"dob": "1985-01-23"
}
Attention
The
idDocType
andcountry
values must always be provided.
Import company applicants
To import a company applicant, submit the *.zip archive with the data structured as described in the overview.
The number of directories in the archive depends on the number of company docs required in the verification level. However, if the level has no documents required, the archive may only contain the applicant.json
file.
Below, you can overview the examples of the archive structure and possible values with descriptions of the applicant.json
and applicantIdDoc.json
files.
Attention
Beneficiaries should be imported to or created in the Sumsub system beforehand if you need them added to the company structure.
Archive structure examples
The following is an example of the archive structure to create a company profile based on basic-kyb-level
that requires only one company document.
Another example represents the simplest archive structure to create a company profile based on the default KYB verification level that does not require company documents.
applicant.json
content (for companies)
applicant.json
content (for companies)The applicant.json
file must contain the company data with review results. The root values of the file are the same as for importing an individual, with the difference they should include the companyInfo
data within the info
object and the name of the verification level configured for KYB applicants.
applicant.json
root values
applicant.json
root valuesValue | Type | Required | Description |
---|---|---|---|
externalUserId | String | Yes | Unique applicant identifier as registered on your side:
|
info | Object | Yes | Includes the companyInfo object. |
review | Object | Yes | Explains the details of the applicant verification status and check results on your side. The values of the review object are equal to those for importing individuals. |
companyInfo
attributes
companyInfo
attributesThe following table explains the companyInfo
object attributes representing general data about the company, such as the company name, location and country of registration, legal entity type, contacts, and other details.
Field | Type | Required | Description |
---|---|---|---|
companyName | String | Yes | The name of the company. |
registrationNumber | String | No | Unique number assigned to the company when it was registered as a legal entity. |
country | String | Yes | Alpha-3 code of the country where the company is legally registered (for example, DEU or GBR ). |
legalAddress | String | No | The address a legal entity uses to register with a legal authority. |
incorporatedOn | String | No | The date of company incorporation (format YYYY-mm-dd , e.g. 2001-09-25 ). |
type | String | No | Type of legal entity. For example, Private Company Limited by Shares , Public Limited Company , Limited Partnership , and so on. |
email | String | No | Company email address. |
phone | String | No | Company phone number. |
controlScheme | String | No | Description of the control scheme of the company ownership or group of entities. |
taxId | String | No | Taxpayer registration number/Code of taxpayer registration. |
registrationLocation | String | No | City, town, or another location where the company was registered. |
website | String | No | Website URL of the company. |
postalAddress | String | No | Company postal address. |
beneficiaries | Array of objects | No | Contains applicantId of beneficiaries and additional information, such as the position and type. |
address | Object | No | Represents the company address. |
noUBOs | Boolean | No | When set to true , a company is to be verified with no UBOs specified in the company profile. For example, in case when another legal entity that cannot be a UBO owns this company. |
noShareholders | Boolean | No | When set to true , a company is to be verified with no shareholders specified in the company profile. For example, in case when the verification level settings require a company to have three shareholders but the company has just one. |
beneficiaries
element fields
beneficiaries
element fieldsThe following table describes the beneficiaries
array of objects containing applicantId
of beneficiaries and additional information, such as their position and type.
Field | Type | Required | Description |
---|---|---|---|
applicantId | String | Yes | Unique applicant identifier of the beneficiary in the Sumsub system. This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant is created on the Sumsub side, and can be found in the Dashboard . If the applicantId is unknown to you, use the Get applicant data (externalUserId) method to fetch it. |
positions | Array of strings | No | Positions in the company that the beneficiary is holding:
β οΈ Not required for KYB 2.0. |
type | String | Yes | Type of beneficiary:
|
shareSize | Double | No | Percentage of ownership if the beneficiary is a shareholder of the company. |
inRegistry | Boolean | No | Matching to a Corporate registry.
|
imageIds | Array of strings | No | Image IDs of the uploaded document. If the imageIds array contains more than one element, the first one would be the front side and the others β back sides. |
address
attributes
address
attributesThe following table explains available details of the company address.
Field | Type | Required | Description |
---|---|---|---|
country | String | No | Alpha-3 country code (for example, DEU , GBR , ARG , and so on). |
postCode | String | No | Address postal code. |
state | String | No | State, region, district, county or another territorial entity inside a country. |
town | String | No | City, town, or another settlement. |
street | String | No | Street name. |
subStreet | String | No | Additional information related to the street. This could be a house number or any other details. |
applicant.json
example (for companies)
applicant.json
example (for companies)The following is an example of a typical applicant.json
file for importing company applicants with the basic-kyb-level
specified. You can always create a file with your own structure within the possible parameters.
{
"externalUserId": "someCoolCompanyId",
"info": {
"companyInfo": {
"companyName": "COMPANY WITH A DOCUMENT LTD",
"registrationNumber" : "09688671",
"country" : "GBR"
}
},
"review": {
"createDate": "2024-07-21 08:25:32+0000",
"reviewDate": "2024-07-21 08:25:36+0000",
"levelName": "basic-kyb-level",
"reviewResult": {
"moderationComment": "",
"clientComment": "",
"reviewAnswer": "GREEN"
},
"reviewStatus": "completed"
}
}
Attention
When creating the
applicant.json
file, mind the fields with required values and make sure to specify.review.levelName
of the verification level made particularly for company applicants.
applicantIdDoc.json
content (for companies)
applicantIdDoc.json
content (for companies)The applicantIdDoc.json
file represents the object that is used as metadata
to upload an image to the company profile. As opposed to the such-like file for importing individuals, it should contain the idDocType
required for company applicants.
See the following table with the values that can be submitted in the applicantIdDoc.json
file to import an individual applicant.
Value | Type | Required | Description |
---|---|---|---|
idDocType | String | Yes | Specify the idDocType required.See the list of supported document types for companies for details. |
idDocSubType | String | No | The [optional] idDocSubType if the COMPANY_DOC was specified as a document type in the parameter above.See the list of supported document subtypes for companies for details. |
country | String | Yes | Alpha-3 code (e.g., DEU , GBR , ARG , and so on) of the country where the document was issued. |
applicantIdDoc.json
example (for companies)
applicantIdDoc.json
example (for companies)The following is an example of a typical applicantIdDoc.json
file for importing company applicants.
{
"idDocType": "COMPANY_DOC",
"idDocSubType": "STATE_REGISTRY",
"country": "GBR"
}
Attention
The
idDocType
andcountry
values must always be provided.
Response explained
The response is a JSON file representing the applicant profile with augmented and structured information created as a result of importing applicant data. The existence of some fields depends on the documents submitted for verification and verification regulations.
You can see the response structure, possible content with descriptions, and examples on the following page.
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error.
For example:
{
"description": "Level 'xxx-kyb-level' not found",
"code": 404,
"correlationId": "41654fff445f47f19490dfa50457e013"
}