---
updatedAt: 2026-09-29T08:48:04.000Z
agentTools:
projectIndex: https://docs.sumsub.com/llms.txt
---
# Import applicant from archive
# Table of contents
* [Overview](#overview)
* [Required permissions](#required-permissions)
* [Import individuals](#import-individual-applicants)
* [Archive structure](#archive-structure-example)
* [applicant.json content](#applicantjson-content)
* [applicant.json example](#applicantjson-file-example)
* [applicantIdDoc.json content](#applicantiddocjson-file-content)
* [applicantIdDoc.json example](#applicantiddocjson-example)
* [Import companies](#import-company-applicants)
* [Archive structure](#archive-structure-examples)
* [applicant.json content](#applicantjson-content-for-companies)
* [applicant.json example](#applicantjson-example-for-companies)
* [applicantIdDoc.json content](#applicantiddocjson-content-for-companies)
* [applicantIdDoc.json example](#applicantiddocjson-example-for-companies)
* [Response explained](#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](#import-individual-applicants) and [company](#import-company-applicants) applicants with examples of archives and JSON files.
### Attention
All file names within the archive, as well as the archive name itself, must contain only the following characters: `A–Z`, `a–z`, `0–9`, `_`, `-`, and `.`. Any other characters will cause the request to fail.
### Note
The [rate limit](https://docs.sumsub.com/sumsub/reference/authentication#rate-limits) for this method: 10 requests per 10 seconds.
## Required permissions
To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the **Create applicants** [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions).
# Import individual applicants
To import an individual applicant, submit the [\*.zip archive](#archive-structure-example) with the data structured as described in the [overview](#overview). The number and type of directories depend on and correspond to the [required steps](https://docs.sumsub.com/sumsub/docs/understand-verification-types) configured for the [verification level](https://docs.sumsub.com/sumsub/docs/verification-levels).
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
| Value | Type | Required | Description |
| :--------------- | :--------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalUserId` | String | Yes | Unique applicant identifier as registered on your side: - This identifier can be used to [get the applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) 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](https://docs.sumsub.com/sumsub/reference/changing-top-level-information) .
|
| `info` | [Object](#info-attributes) | Yes | Holds the personal applicant information extracted during verification on your side. |
| `review` | [Object](#review-attributes) | Yes | Explains 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.
| 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 | Gender of the applicant (`M`, `F`, or `X`). |
| `dob` | Date | No | Applicant date of birth (format `YYYY-mm-dd`, for exampl`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 | Country where the applicant currently resides or the country of their nationality. 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](#addresses-element-fields) | 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. |
| `tins` | Array of objects | No | List of the applicant taxpayer identification numbers, present when the applicant has more than one TIN. Each entry carries its own country (see sub-table). The single `tin` / `taxResidenceCountry` pair mirrors the first entry (`tins[0]`).
⚠️ This option is currently available only upon request to our support team or your CSM. |
# `tins` element fields
List of the applicant's taxpayer identification numbers, present when the applicant has more than one TIN.
⚠️ This option is currently available only upon request to our support team or your CSM.
| Field | Type | Description |
| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tin` | string | Taxpayer identification number. |
| `country` | string | Country where this TIN applies, as an [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code (for example, `DEU`, `GBR`, `ARG`). |
## `addresses` element fields
The 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
The 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](https://docs.sumsub.com/sumsub/docs/verification-levels) name. The level determines the verification steps the applicant must complete and the [documents that are required](/reference/get-applicant-data#requirediddocs-attributes) for verification.
⚠ Mind the following: - Level has to be created in the same [environment](https://docs.sumsub.com/sumsub/docs/sandbox-mode) . 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.
|
| `reviewResult` | [Object](#reviewresult-attributes) | 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
The 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
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](#applicantjson-content).
```json
{
"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.
| 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](https://docs.sumsub.com/sumsub/reference/add-id-documents#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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) (for example, `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`, for example, `2010-09-25`). |
| `validUntil` | Date | No | Date when the document validity expires (format `YYYY-mm-dd`, for example, `2025-09-25`). |
| `number` | String | No | Unique registration number of the document. |
| `dob` | Date | No | Applicant date of birth (format `YYYY-mm-dd`, for example, `1975-09-25`). |
| `placeOfBirth` | String | No | Applicant 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](#applicantiddocjson-content).
```json
{
"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](#archive-structure-examples) with the data structured as described in the [overview](#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
| Value | Type | Required | Description |
| :--------------- | :--------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalUserId` | String | Yes | Unique applicant identifier as registered on your side: - This identifier can be used to [get the applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) 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](https://docs.sumsub.com/sumsub/reference/changing-top-level-information) .
|
| `fixedInfo` | Object | Yes | Includes the [companyInfo](#companyinfo-attributes) object. |
| `review` | [Object](#review-attributes) | 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](#review-attributes). |
## `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.
| 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) 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`, for example, `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](#beneficiaries-arguments) | No | Contains `applicantId` of beneficiaries and additional information, such as the position and type. |
| `address` | [Object](#address-attributes) | 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` arguments
The 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](https://cockpit.sumsub.com/checkus/#/applicants/individual?limit=10\&page=0) .
If the `applicantId` is unknown to you, use the [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) method to fetch it. |
| `positions` | Array of strings | No | Positions 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.
|
| `type` | String | Yes | Type 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.
⚠️ Deprecated in the KYB 2.0 flow
|
| `types` | Array of strings | No | Beneficiary roles for the new data structure, when one entity may have multiple roles. Possible values: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.
⚠️ Required for the KYB 2.0 flow only.
|
| `shareSize` | Double | No | Percentage of ownership if the beneficiary is a shareholder of the company. |
| `inRegistry` | Boolean | No | Matching to a Corporate registry.true — found in the registry.false — not found.null — unknown
⚠️ Deprecated in the KYB 2.0 flow
|
| `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. |
| `applicant` | Object | No | The structure to create a new beneficiary. |
## `address` attributes
The 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)
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](#applicantjson-content-for-companies).
```json
{
"externalUserId": "someCoolCompanyId",
"fixedInfo": {
"companyInfo": {
"companyName": "COMPANY WITH A DOCUMENT LTD",
"registrationNumber" : "09654321",
"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.
| Value | Type | Required | Description |
| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idDocType` | String | Yes | Specify the `idDocType` required.
See the list of [supported document types for companies](https://docs.sumsub.com/sumsub/reference/add-id-documents#supported-iddoctypes-for-company-verification) 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](https://docs.sumsub.com/sumsub/reference/add-id-documents#supported-iddocsubtypes-for-company_doc) for details. |
| `country` | String | Yes | Alpha-3 code (for example, `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.
```json
{
"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](https://docs.sumsub.com/sumsub/reference/create-applicant#root-variables).
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error.
For example:
```json
{
"description": "Level 'xxx-kyb-level' not found",
"code": 404,
"correlationId": "41654fff445f47f19490dfa50457e013"
}
```
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "sumsub-api",
"version": "1.0"
},
"servers": [
{
"url": "https://api.sumsub.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "X-App-Token",
"in": "header",
"x-default": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/resources/applicants/-/applicantImport": {
"post": {
"summary": "Import applicant from archive",
"description": "",
"operationId": "import-applicant-from-archive",
"parameters": [
{
"name": "Content-Type",
"in": "header",
"schema": {
"type": "string",
"default": "application/zip"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"RAW_BODY": {
"type": "string",
"description": "`*.zip` archive with data to import.",
"default": "An archive file.",
"format": "binary"
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```