Import applicant profile from archive

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). The applicantIdDoc.json file must always have the object values of idDocType and country.

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

The 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

ValueTypeRequiredDescription
externalUserIdStringYesUnique applicant identifier as registered on your side:
  • This identifier can be used to get the applicant data in case the applicantId in the Sumsub system is unknown to you.
  • When creating an applicant, you can generate and add the externalUserId manually, or it will be automatically generated and added by Sumsub.
  • You can change the externalUserId by the following method .
infoObjectYesHolds the personal applicant information extracted during verification on your side.
reviewObjectYesExplains the details of the applicant verification status and check results on your side.

info attributes

The following table explains the info object attributes representing general applicant information.

FieldTypeRequiredDescription
firstNameStringYesApplicant first name in the original language.
middleNameStringNoApplicant middle name in the original language.
lastNameStringYesApplicant last name in the original language.
legalNameStringNoLegal 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.
genderStringNoApplicant gender (M or F).
dobDateNoApplicant date of birth (format YYYY-mm-dd, e.g. 2001-09-25).
placeOfBirthStringNoApplicant place of birth. This can be a city, a town or another settlement type.
countryOfBirthStringNoApplicant country of birth. Presented as an alpha-3 country code (for example, DEU, GBR, ARG, and so on).
stateOfBirthStringNoState, region, district, county or another territorial entity of birth inside a country, if applicable.
countryStringYesApplicant country of birth. Presented as an alpha-3 country code (for example, DEU, GBR, ARG, and so on).
nationalityStringNoApplicant country of origin. Presented as an alpha-3 country code (for example, DEU, GBR, ARG, and so on).
addressesArray of objectsNoIncludes data objects containing the applicant address details extracted from the PoA documents submitted by the applicant.
tinStringNoTaxpayer identification number that is unique to each taxpayer.

addresses element fields

The following table explains the addresses element fields containing the applicant address details.

FieldTypeRequiredDescription
countryStringNoAlpha-3 country code (for example, DEU, GBR, ARG, and so on).
postCodeStringNoAddress postal code.
townStringNoCity, town, or another settlement.
stateStringNoState, region, district, county or another territorial entity inside a country.
streetStringNoStreet name.
subStreetStringNoAdditional information related to the street. This could be a house number or any other details.
buildingNameStringNoBuilding name if applicable.
flatNumberStringNoFlat or apartment number.
buildingNumberStringNoBuilding number.

review attributes

The following table explains the review object attributes that represent the details of the verification status.

FieldTypeRequiredDescription
createDateDateNoDate 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.
reviewDateDateNoReview 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.
levelNameStringYesVerification level name. The level determines the verification steps the applicant must complete and the documents that are required for verification.

⚠ Mind the following:
  • Level has to be created in the same environment . For example, in the Sandbox mode, you may not be able to use a level configured to be only available in the Production environment.
  • Level name is case-sensitive. Kyc-level and kyc-level are considered as completely different level names. The system does not allow creating an applicant with the level name that does not exist.
  • The system does not allow creating a company profile with a level for individuals and vice versa.
reviewResultObjectYesContains extra details of the applicant review result.
reviewStatusStringYes⚠ The applicant review status must be completed only. Otherwise, the applicant data import will fail.

reviewResult attributes

The following table explains the reviewResult attributes representing the applicant verification result details.

FieldTypeDescription
moderationCommentStringHuman-readable comment that can be shown to the applicant.
clientCommentStringInternal comment that must not be shown to the applicant.
reviewAnswerString⚠️ Must be GREEN as this method is used to import only approved applicants on your side.

applicant.json example

The 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

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

ValueTypeRequiredDescription
idDocTypeStringYesType of document that is specified in the level to be provided for verification.

See the supported document types that can be specified.
idDocSubTypeStringNoSpecify 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.
countryStringYesAlpha-3 code (e.g., DEU, GBR, ARG, and so on) of the country where the document was issued.
firstNameStringNoApplicant first name.
middleNameStringNoApplicant middle name.
lastNameStringNoApplicant last name.
issuedDateDateNoDate of the document issue (format YYYY-mm-dd, e.g. 2010-09-25).
validUntilDateNoDate when the document validity expires (format YYYY-mm-dd, e.g. 2025-09-25).
numberStringNoUnique registration number of the document.
dobDateNoApplicant date of birth (format YYYY-mm-dd, e.g. 1975-09-25).
placeOfBirthStringNoApplicant place of birth. This can be a city, a town or another settlement type.

applicantIdDoc.json example

The 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 and country 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)

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

ValueTypeRequiredDescription
externalUserIdStringYesUnique applicant identifier as registered on your side:
  • This identifier can be used to get the applicant data in case the applicantId in the Sumsub system is unknown to you.
  • When creating an applicant, you can generate and add the externalUserId manually, or it will be automatically generated and added by Sumsub.
  • You can change the externalUserId by the following method .
infoObjectYesIncludes the companyInfo object.
reviewObjectYesExplains 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

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

FieldTypeRequiredDescription
companyNameStringYesThe name of the company.
registrationNumberStringNoUnique number assigned to the company when it was registered as a legal entity.
countryStringYesAlpha-3 code of the country where the company is legally registered (for example, DEU or GBR).
legalAddressStringNoThe address a legal entity uses to register with a legal authority.
incorporatedOnStringNoThe date of company incorporation (format YYYY-mm-dd, e.g. 2001-09-25).
typeStringNoType of legal entity. For example, Private Company Limited by Shares, Public Limited Company, Limited Partnership, and so on.
emailStringNoCompany email address.
phoneStringNoCompany phone number.
controlSchemeStringNoDescription of the control scheme of the company ownership or group of entities.
taxIdStringNoTaxpayer registration number/Code of taxpayer registration.
registrationLocationStringNoCity, town, or another location where the company was registered.
websiteStringNoWebsite URL of the company.
postalAddressStringNoCompany postal address.
beneficiariesArray of objectsNoContains applicantId of beneficiaries and additional information, such as the position and type.
addressObjectNoRepresents the company address.
noUBOsBooleanNoWhen 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.
noShareholdersBooleanNoWhen 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

The following table describes the beneficiaries array of objects containing applicantId of beneficiaries and additional information, such as their position and type.

FieldTypeRequiredDescription
applicantIdStringYesUnique 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.
positionsArray of stringsNoPositions in the company that the beneficiary is holding:
  • director β€” appointed to manage the company business and affairs.
  • shareholder β€” owns shares in the company stock.
  • other β€” specify a position that does not meet the two above.

⚠️ Not required for KYB 2.0.

typeStringYesType of beneficiary:
  • ubo β€” ultimate beneficial owner of the company.
  • shareholder β€” owns shares in the company stock.
  • representative β€” authorized to act or speak for or in support of the company.
  • director β€” appointed to manage the company business and affairs.
shareSizeDoubleNoPercentage of ownership if the beneficiary is a shareholder of the company.
inRegistryBooleanNoMatching to a Corporate registry.
  • true β€” found in the registry.
  • false β€” not found.
  • null β€” unknown
imageIdsArray of stringsNoImage 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

The following table explains available details of the company address.

FieldTypeRequiredDescription
countryStringNoAlpha-3 country code (for example, DEU, GBR, ARG, and so on).
postCodeStringNoAddress postal code.
stateStringNoState, region, district, county or another territorial entity inside a country.
townStringNoCity, town, or another settlement.
streetStringNoStreet name.
subStreetStringNoAdditional information related to the street. This could be a house number or any other details.

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)

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.

ValueTypeRequiredDescription
idDocTypeStringYesSpecify the idDocType required.

See the list of supported document types for companies for details.
idDocSubTypeStringNoThe [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.
countryStringYesAlpha-3 code (e.g., DEU, GBR, ARG, and so on) of the country where the document was issued.

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 and country 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"
}
Language
Authorization
Header
Click Try It! to start a request and see the response here!