Table of contents

• Overview
• Import individuals
  • Archive structure
  • applicant.json content
  • applicant.json example
  • applicantIdDoc.json content
  • applicantIdDoc.json example
• Import companies
  • Archive structure
  • applicant.json content
  • applicant.json example
  • applicantIdDoc.json content
  • applicantIdDoc.json example
• Response explained

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

info attributes

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

addresses element fields

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

review attributes

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

reviewResult attributes

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

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.

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

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.

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.

address attributes

The following table explains available details of the company address.

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.

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