Overview

Use this method to create a new applicant profile of either of the following types:

individual — if the applicant is a physical person.
company — if the applicant is a legal entity.

📘
Note
The maximum number of applicant profiles that you can create in Sandbox mode is limited to 500 per 24 hours.

In the constructor above, you can see the parameters that can be provided when creating an individual applicant. Find out the specifics of creating a company applicant in the section below.

When creating a new applicant profile, you do not always have to send us pre-filled applicant data, such as the applicant name, date of birth, address, and so on. You only need to send images and get the recognized document data using this method. It is the best way to increase your conversion because rejects of mismatches in names and typos will be excluded.

Each applicant may have several ID documents (as well as additional photos of different documents) attached, such as, for example, an ID card or a passport.

See Applicant life-cycle to view the way an applicant profile goes through from creation to verification.

👍
Tip

If you have requirements to perform data cross-validation and have no possibility to do it on your side, use the fixedInfo object to fill data like names, date of birth, and address.

When using the fixedInfo object, mind that a verification level specified for a particular applicant should include the Applicant data step.

Make sure to save the applicant ID. You may need it for future requests.

Specifics of creating company applicants

When creating a company applicant, make sure to provide a companyInfo object within the request. The companyInfo object attributes are required to properly validate the company data during verification. This information is not mandatory to be added upon creation, but make sure to provide it before requesting a check.

📘
Note
Within the KYB 1.0 flow, companyInfo must be nested inside the info object. As for KYB 2.0, embed companyInfo inside the fixedInfo object. See the request examples below.

`companyInfo` arguments

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 of the country where the company is legally registered (for example, `DEU` or `GBR`).
`alternativeNames`	Array of strings	No	List of alternative names of the company: a brand name, business trademark, name in a local language, and so on. For example, "Megacorp" instead of "The Megacorp ABC Inc."
`legalAddress`	String	No	Address a legal entity uses to register with a legal authority.
`incorporatedOn`	Date	No	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.
`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.

`address` arguments

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.

Request examples

curl -X POST \
  'https://api.sumsub.com/resources/applicants?levelName=basic-kyc-level' \
  -H 'Content-Type: application/json' \
  -d '{
          "externalUserId": "someUniqueUserId",
          "email": "[email protected]",
          "phone": "+449112081223",
          "fixedInfo": {
              "country": "GBR",
              "placeOfBirth": "London"
          }
      }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants?levelName=kyb-level' \
  -H 'Content-Type: application/json' \
  -d '{
        "externalUserId": "someClientUserIdCompany",
        "info": {
            "companyInfo": {
                "companyName": "COMPANY NAME LTD",
                "registrationNumber": "09688671",
                "country": "GBR",
                "incorporatedOn": "2015-01-01",
                "type": "Private Company Limited by Shares",
                "email": "[email protected]",
                "phone": "+12366020172",
                "website": "example.com"
            }
        },
        "type": "company"
      }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants?levelName=kyb-level' \
  -H 'Content-Type: application/json' \
  -d '{
        "externalUserId": "someClientUserIdCompany",
        "fixedInfo": {
            "companyInfo": {
                "companyName": "COMPANY NAME LTD",
                "registrationNumber": "09688671",
                "country": "GBR",
                "incorporatedOn": "2015-01-01",
                "type": "Private Company Limited by Shares",
                "email": "[email protected]",
                "phone": "+12366020172",
                "website": "example.com"
            }
        },
        "type": "company"
      }'

Response explained

The response is a JSON file representing the applicant profile that you have created (or Sumsub have created for you, for example, via the WebSDK) with augmented and structured information. The existence of some fields depends on the documents and data submitted for verification and verification regulations.

Below, you can see the response structure, possible content with descriptions, and examples of response:

Root variables
info
- companyInfo
- idDocs
- address, addresses
fixedInfo
agreement
requiredIdDocs
- docSets
review
- reviewResult
questionnaires
notes
memberOf
Response examples

Root variables

Root variables are the core applicant profile data items. Some of them may include nested attributes and element fields.

Field	Type	Description
`id`	String	Unique applicant identifier in the Sumsub system (`applicantId`). This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant profile is created on the Sumsub side.
`createdAt`	Date	Date and time (GMT) when the applicant profile was created in the Sumsub system. Format: `YYYY-MM-DD HH:MI:SS`.
`clientId`	String	Unique identifier of you as our client in the Sumsub system. This identifier is assigned to you when you are registered in and get access to the Sumsub system. It usually resembles your name or your company name. `clientId` is automatically added to the applicant profile when it is created.
`inspectionId`	String	Unique combination of digits and characters to identify all actions with the applicant’s ID documents. Added automatically when the applicant is created. This is useful, for example, if you want to find out which document photos were a part of the final verification and made the applicant pass or fail the check. To receive the necessary images, use this method.
`externalUserId`	String	Unique applicant identifier as registered on your side. When creating an applicant, you can generate and add the `externalUserId` manually, or it will be automatically generated and added to the applicant profile by Sumsub.
`sourceKey`	String	Source key that helps you group clients that send applicants.
`info`	Object	General applicant information recognized from the documents that Sumsub cross-validates with the applicant data provided (`fixedInfo`). Note that `info` and `fixedInfo` objects have the same attributes.
`fixedInfo`	Object	General applicant information that is submitted by the applicant via the Web or Mobile SDK or by you via this API method. Sumsub should not change this information but use it to cross-validate with the data recognized from the applicant documents. Note that `info` and `fixedInfo` objects have the same attributes.
`email`	String	Applicant email address. It is mandatory if the email verification is required. If not provided, the applicant cannot receive verification status emails.
`phone`	String	Applicant phone number. It is mandatory if the phone verification is required.
`applicantPlatform`	String	The platform from which the applicant registered in the system and/or provided profile data (`API`, `Web`, `Android`, `iOS`).
`ipCountry`	String	Alpha-3 country code (`DEU`, `GBR`, `ARE`, and so on) of the country that owns the IP address from which the applicant got registered and/or submitted the data.
`authCode`	String	JWT token to sign in a user. For more details, refer to WebSDK Settings.
`agreement`	Object	Contains information about the applicant consent to submitting and processing the personal data.
`requiredIdDocs`	Object	Configuration of steps for the applicant to complete verification. It includes step types (e.g. `IDENTITY`, `SELFIE`) and the documents appropriate for each step (e.g. `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`), or necessary data fields to be filled in. For example, the `APPLICANT_DATA` step type includes a list of fields the applicant must fill in, so we could proceed with verification.
`review`	Object	Explains the details of the current applicant verification status and check result.
`lang`	String	Two-letter code of the language (ISO 639-1 format, for example, `en`, `fr`, `de`) for the SDK and emails sent to the applicant. The verification results should be displayed to the applicant in this language as well. As a rule, it is detected by the applicant IP address. You can set the language when initializing the SDK (MSDK), or via API when creating an applicant.
`metadata`	Array of objects	Additional information not displayed to the end-user. For example: `[{"key": "keyFromClient", "value": "valueFromClient"}]`.
`type`	Enum	Defines the applicant type. Added automatically when the applicant is created. The following entity types are available: `individual` — for applicants registered and checked as individuals. `company` — for applicants registered and checked as legal entities.
`riskLabels`	Object	Contains information on the applicant risk labels.
`questionnaires`	Array of objects	Includes the objects describing questionnaires that the applicant is given to complete during (or after) verification. If the applicant has already filled a questionnaire, you can see the submitted answers in the `value` fields.
`notes`	Array of objects	Includes the objects representing notes added to the applicant profile by you or by Sumsub operators.
`tags`	Array of strings	Contains tags that you have created and then assigned to the applicant.
`memberOf`	Array of objects	Includes data objects with the applicant companies' IDs the beneficiary of which the applicant is and which are registered in the Sumsub system.

`info` attributes

The following table explains the info object attributes — general applicant information recognized from the documents that Sumsub cross-validates with the applicant data provided (fixedInfo).

Note that info and fixedInfo objects have the same attributes except for idDocs.

Field	Type	Description
`companyInfo`	Object	⚠️ Available only for company applicants provided a company applicant has been created within the KYB 1.0 flow. The object contains general information about the company, such as the company name, location and country of registration, legal entity type, contacts and other details.
`firstName`	String	Applicant first name in the original language.
`firstNameEn`	String	Automatic transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant middle name in the original language.
`middleNameEn`	String	Automatic transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant last name in the original language.
`lastNameEn`	String	Automatic transliteration of the applicant last name into Latin characters.
`legalName`	String	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	Applicant gender (`M` or `F`). If the gender was not specified in the applicant profile, this field will not be present.
`dob`	Date	Applicant date of birth (format `YYYY-mm-dd`, e.g. `2001-09-25`).
`placeOfBirth`	String	Applicant place of birth. This can be a city, a town or another settlement type.
`countryOfBirth`	String	Applicant country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`stateOfBirth`	String	State, region, district, county or another territorial entity of birth inside a country, if applicable.
`country`	String	Country that issued the applicant's document. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`nationality`	String	Applicant country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`addresses`	Array of objects	Includes data objects containing the applicant address details extracted from the PoA documents submitted by the applicant.
`tin`	String	Taxpayer identification number that is unique to each taxpayer.
`idDocs`	Array of objects	Includes data objects containing information extracted from the applicant documents, which can be useful in cases where a verification has been completed.

`companyInfo` attributes

The following table explains the companyInfo object attributes representing the company applicant data.

⚠️ This object is only available for company applicants.

Field	Type	Description
`companyName`	String	The name of the company.
`registrationNumber`	String	Unique number that is assigned to the company when it was registered as a legal entity.
`country`	String	Alpha-3 code of the country where the company is legally registered (for example, `DEU`, `GBR`, and so on).
`alternativeNames`	Array of strings	List of alternative names of the company: a brand name, business trademark, name in a local language, and so on. For example, "Megacorp" instead of "The Megacorp ABC Inc."
`legalAddress`	String	Address a legal entity uses to register with a legal authority.
`incorporatedOn`	Date	Date of company incorporation (format `YYYY-mm-dd`, e.g. `2001-09-25`).
`applicantPosition`	String	Applicant position in regards to the company.
`type`	String	Type of legal entity. For example, private company limited by shares, public limited company, state-owned enterprise, and so on.
`email`	String	Company email address.
`phone`	String	Company phone number.
`taxId`	String	Taxpayer registration number/Code of taxpayer registration.
`registrationLocation`	String	City, town, or another location where the company was registered.
`website`	String	Website URL of the company.
`postalAddress`	String	Company postal address.
`address`	Object	Represents the company address.
`controlScheme`	String	Description of the control scheme of the company ownership or group of entities.
`noUBOs`	Boolean	When set to `true`, a company is to be 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	When set to `true`, a company is to be 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`	Array of objects	Contains `applicantId`s of beneficiaries and additional information such as position and type.

`beneficiaries` element fields

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

Mind that the beneficiaries array is available for company applicants only.

Field	Type	Description
`id`	String	Beneficiary identifier that is autogenerated for all KYB 2.0 beneficiaries when they are added to the company structure. ⚠️ Beneficiary identifier is not the equivalent of `applicantId`.
`applicant`	Object	Applicant profile data.
`applicantId`	String	Applicant identifier of the beneficiary in the Sumsub system.
`beneficiaryInfo`	Object	Structure that contains the beneficiary contact data. ⚠️ Available for KYB 2.0 only.
`positions`	Array of strings	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` — a position that does not meet the two above. ⚠️ Available for KYB 1.0 only.
`type`	String	Beneficiary single role in the company control and ownership structure. 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. ⚠️ Available for KYB 1.0 only.
`types`	Array of strings	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. ⚠️ Available for KYB 2.0 only.
`shareSize`	Double	Percentage of ownership if the beneficiary is a shareholder of the company.
`inRegistry`	Boolean	Matching to a Corporate registry. `true` — found in the registry. `false` — not found. `null` — unknown ⚠️ Available for KYB 1.0 only.
`imageIds`	Array of strings	Image IDs represent a document uploaded. If `imageIds` array contains more than one element, the first one would be the front side and the others — back sides.

`beneficiaryInfo` attributes

The following table explains the beneficiaryInfo attributes representing the beneficiary contact data.

⚠️ Available for company applicants and KYB 2.0 only.

Field	Type	Description
`firstName`	String	First name of the beneficiary.
`lastName`	String	Last name of the beneficiary.
`dob`	Date	Beneficiary date of birth.
`email`	String	Beneficiary email address.
`taxResidenceCountry`	String	Country where the beneficiary pays taxes. Presented as an alpha-3 code (for example, `DEU`, `GBR`, `ARG`, and so on).
`shareSize`	Double	Percentage of ownership if the beneficiary is a shareholder of the company.

`idDocs` element fields

The following table explains the data objects representing the details of identity documents provided by the applicant.

Field	Type	Description
`idDocType`	String	Type of document that is specified in the level to be provided for verification. For example, `PASSPORT`, `UTILITY_BILL`, `VEHICLE_REGISTRATION_CERTIFICATE`, and so on. See the lists of supported document types and supported company document types for details.
`country`	String	Alpha-3 code (for example, `DEU`, `GBR`, `ARG`, and so on) of the country where the document was issued.
`firstName`	String	Applicant first name in the original language as it is in the document.
`firstNameEn`	String	Automatic transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant middle name in the original language as it is in the document.
`middleNameEn`	String	Automatic transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant last name in the original language as it is in the document.
`lastNameEn`	String	Automatic transliteration of the applicant last name into Latin characters.
`issuedDate`	Date	Date when the identity document was issued (format `YYYY-MM-DD`).
`issueAuthority`	String	Official name of the authority that issued the document.
`issueAuthorityCode`	String	Code of the ssuing Authority that is in charge of issuing the uploaded document.
`validUntil`	Date	Date when the document validity expires.
`number`	String	Unique registration number of the document.
`additionalNumber`	String	Usually, it is a sort of personal number. For example, DNI in Spain, CRP in Brazil, or ARC in Cyprus.
`dob`	Date	Applicant date of birth (format `YYYY-mm-dd`, e.g. `2001-09-25`) as it is specified in the document.
`address`	Object	Includes the applicant address details.
`mrzLine1`	String	A line of MRZ (machine-readable zone) from the document. Additional lines, such as `mrzLine2` and `mrzLine3`, may also be present if available. The number indicates the line position in sequential order.
`nfcInfo`	Object	Includes the data extracted from the NFC chip of an identity document.

`address` attributes and `addresses` element fields

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

Field	Type	Description
`buildingName`	String	Building name.
`flatNumber`	String	Flat or apartment number.
`subStreet`	String	Additional information related to the street. This could be a house number or any other details.
`subStreetEn`	String	Automatic transliteration of the additional information related to the street into Latin characters.
`street`	String	Street name.
`streetEn`	String	Automatic transliteration of the street name into Latin characters.
`state`	String	State, region, district, county or another territorial entity inside a country.
`stateEn`	String	Automatic transliteration of the territorial entity into Latin characters.
`buildingNumber`	String	Building number.
`town`	String	City, town, or another settlement.
`townEn`	String	Automatic transliteration of the settlement into Latin characters.
`postCode`	String	Address postal code.
`country`	String	Alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`formattedAddress`	String	Address in a human readable format. For example, `Design Offices, Philipsbornstraße 2, 30165 Hannover, Germany`.

`nfcInfo` attributes

The following table explains the nfcInfo attributes representing the data extracted from the NFC chip of an identity document.

Field	Type	Description
`fullMrz`	String	Contains the full Machine-Readable Zone (MRZ) data from the ID document.
`imageId`	String	Unique identifier of the image that represents the uploaded document.

`fixedInfo` attributes

The following table explains the fixedInfo object attributes — general applicant information that is submitted by the applicant via the Web or Mobile SDK or by you via this API method. Sumsub should not change this information but use it to cross-validate with the data recognized from the applicant documents (info object).

Note that info and fixedInfo objects have the same attributes except for idDocs.

Field	Type	Description
`companyInfo`	Object	⚠️ Available only for company applicants provided a company applicant has been created within the KYB 2.0 flow. The object contains general information about the company, such as the company name, location and country of registration, legal entity type, contacts and other details.
`firstName`	String	Applicant first name in the original language.
`firstNameEn`	String	Automatic transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant middle name in the original language.
`middleNameEn`	String	Automatic transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant last name in the original language.
`lastNameEn`	String	Automatic transliteration of the applicant last name into Latin characters.
`legalName`	String	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	Applicant gender that can be male or female (`M` or `F`). If the gender is not specified in the applicant profile, this field is absent.
`dob`	Date	Applicant date of birth (format `YYYY-mm-dd`, e.g. `2001-09-25`).
`placeOfBirth`	String	Applicant place of birth. This can be a city, a town or another settlement type.
`countryOfBirth`	String	Applicant country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`stateOfBirth`	String	State, region, district, county or another territorial entity of birth inside a country, if applicable.
`country`	String	Applicant country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`nationality`	String	Applicant country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`addresses`	Array of objects	Includes data objects containing the applicant address details provided by the applicant.
`tin`	String	Taxpayer identification number that is unique to each taxpayer.
`taxResidenceCountry`	String	Country where the applicant pays taxes. Presented as an alpha-3 code (for example, `DEU`, `GBR`, `ARG`, and so on).

`agreement` attributes

🚧
Attention
A new data format for the agreement object has been introduced (see the following response examples for details). The old format will be deprecated and no longer be supported starting June 10, 2025.
Update your integration accordingly to ensure continued compatibility.

The following table explains the details of the applicant consent to the submitting and processing of personal data. Mind that the new agreement object includes an items array, where each object represents an individual consent event and may contain multiple agreements.

Objects in the items array are sorted chronologically, from oldest to newest.

Since an applicant can accept the same agreement multiple times, such instances are grouped within the same item.

Grouping logic:

If you send different sets of agreements in separate requests, each set will be returned as a separate item in the response.
If you send the same set of agreements more than once, a new item will not be created. Instead, the response will include the original item with the earliest acceptedAt timestamp.

Field	Type	Description
`id`	String	Consent identifier.
`createdAt`	Date	Date and time (GMT) when consent for the submission and processing of personal data was given to the applicant.
`acceptedAt`	Date	Date and time (GMT) when the applicant confirmed their consent for the submission and processing of personal data.
`source`	String	Specifies the source from which the applicant confirmed the agreement (`WebSDK`, `MSDK`, `API`).
`type`	String	Indicates the way the agreement was obtained (e.g., during onboarding, via reusable KYC, and so on).
`recordIds`	Array of strings	Each `recordId` corresponds to an individual accepted agreement text.

`requiredIdDocs` attributes

The requiredIdDocs object represents the configuration of steps for the applicant to complete verification. It includes a set of required documents and data to provide.

Field	Type	Description
`videoIdent`	Boolean	Specifies if the video identification is required (`true`) or not required (`false`) to pass verification.
`docSets`	Array of objects	Includes the objects representing specific document sets and their attributes.
`excludedCountries`	Array of strings	Countries (in alpha-3 country code, for example, `DEU`, `GBR`, `ARG`, etc.) that are excluded from the list of supported.
`kybSettings`	Object	Includes the thresholds of ownership share (`shareholderThreshold` and `uboThreshold`) that are used to identify the types of company beneficiaries. If `shareholderThreshold` is less and `uboThreshold` is greater than the ownership percentage, then the individual is a shareholder. If the ownership percentage is greater than or equal to the `uboThreshold`, then the individual is a UBO. Companies are always classified as shareholders.

`docSets` element fields

The following table explains the element fields of the docSets array representing specific document sets and their attributes.

Field	Type	Description
`idDocSetType`	String	Human-readable identifier of the document set type, for example, `IDENTITY`, `SELFIE`, `PROOF_OF_RESIDENCE`, and so on.
`companyBeneficiaryDefinitions`	Array of objects	Specification of level steps to be fulfilled. Stands for "Associated parties". Available for company applicants.
`companyDocsGroupDefinitions`	Array of objects	Definitions of the required document groups for verification. Available for company applicants.
`fields`	Array of objects	Includes the objects describing the document data fields that should be filled with personal information to verify the applicant. Each object contains the following attributes: `name` (String) — the field name, for example, `firstName`, `lastName`, `email`, and so on. `required` (Boolean) — `true` if the field is required for verification, `false` if not (still, it can be optionally filled in the SDK).
`types`	Array of strings	Includes the types of documents that are required for a particular `idDocSetType` to pass verification.
`videoRequired`	String	Method of passing the document upload step that can be set up when configuring a verification level. `disabled` — selfie with a document. `enabled` — video selfie with a phrase. `photoRequired` — web camera photo (still face image). `passiveLiveness` — liveness check. `docapture` — enables the camera for the steps with ID documents.
`captureMode`	String	This mode is applied in case the `docapture` method is used (see the table row above). `manualAndAuto` — allows both to automatically capture the photo of a document when the camera is initialized, and for the applicant to hit a button to take a photo. `manualOnly` — allows only manually hitting a button to take a photo.
`uploaderMode`	String	This mode is applied in case the `docapture` method is used. `always` — always allows uploading a ready-made photo instead of using a camera. `never` — does not allow uploading a ready-made photo. `fallback` — allows uploading a ready-made photo only if a camera is not available.
`questionnaireDefId`	String	Identifier of the questionnaire that is added to the verification level and is to be or has already been filled by the applicant.

`companyBeneficiaryDefinitions` element fields

Field	Type	Description
`category`	String	Beneficiary role name (`ubos`, `shareholders`, `directors`).
`canSkip`	Boolean	Indicates if it is skippable via SDK: `true` — yes, `false` — no.
`individual`	Object	Contains information on the associated party as an individual applicant.
`company`	Object	Contains information on the associated party as a company applicant.

`individual` and `company` attributes

Field	Type	Description
`enabled`	Boolean	Nested KYC (for individuals) or KYB (for companies) verification enabled for this role: `true` — yes, `false` — no.
`levelName`	String	Name of the verification level.
`fields`	Array of objects	Includes the objects describing the data fields that should be filled with personal information to verify the applicant. Each object contains the following attributes: `name` (String) — the field name, for example, `firstName`, `lastName`, `email`, and so on. `required` (Boolean) — `true` if the field is required for verification, `false` if not (still, it can be optionally filled in the SDK).
`customFields`	Array of objects	Includes the objects each of those represents an additional custom field (`applicantIdDocSetCustomField`) that should be filled for verification. Each object contains the following attributes: `name` (String) — the field name in the system, for example, `firstName`, `lastName`, `email`, and so on. `displayName` (String) — the field name displayed in the SDK, for example, `First name`, `Last name`, `E-mail`, and so on. `required` (Boolean) — `true` if the field is required for verification, `false` if not (still, it can be optionally filled in the SDK).

`companyDocsGroupDefinitions` element fields

Field	Type	Description
`label`	String	Label of the document group (e.g., `legalPresence`, `companyDetails`).
`subTypes`	Array of strings	List of document types included into the verification group.
`required`	Boolean	Indicates if this is required (`true`) or optional (`false`).

`review` attributes

The following table explains the review object attributes that represent the details of the current applicant verification status and check result.

Field	Type	Description
`reviewId`	String	Unique identifier of the applicant profile review in the Sumsub system.
`levelName`	String	Name of the verification level the applicant has to go through.
`attemptId`	String	Unique identifier of the current verification attempt. Applicants may initiate several attempts to get verified if, for example, they failed once or changed/added the documents, or you could change the verification level to start another check.
`attemptCnt`	Integer	Counting number of the current verification attempt on the same verification level.
`elapsedSincePendingMs`	Integer	Elapsed time since the applicant verification passed to the `pending` status.
`createDate`	Date	Date and time (UTC) when the applicant profile was created in the Sumsub system.
`reviewDate`	Date	Date and time (UTC) when the current applicant check was completed.
`reviewResult`	Object	Contains extra details of the applicant verification result.
`reviewStatus`	String	Indicates the applicant review status.

`reviewResult` attributes

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

Field	Type	Description
`reviewAnswer`	String	Explains the review result. `GREEN` — the applicant is approved. `RED` — the applicant is declined.
`rejectLabels`	Array of strings	Includes one or more reasons for rejection. The field is available if `reviewAnswer` returns `RED`. For more details, see Temporary rejection and Final rejection clarification.
`reviewRejectType`	String	Indicates the type of rejection. `FINAL` — final rejection in case of major violations. For example, an attempt of fraud was detected during identification, the applicant is found in the list of persons under sanctions, and so on. The applicant rejected with a final rejection status will not be able to resubmit the documents for verification. `RETRY` — temporary rejection in case of minor violations. For example, a name or address mismatch, incorrect TIN was provided, and so on. A temporary rejected applicant is sent a resubmission request. Thus the applicant has a chance to upload new documents or resubmit correct data. For more details, see Temporary rejection and Final rejection clarification.
`clientComment`	String	Human-readable comment that explains the reasons for rejection in detail, and that must not be shown to the applicant.
`moderationComment`	String	Human-readable comment that explains the reasons for rejection in detail, and that can be shown to the applicant.
`buttonIds`	Array of strings	Button identifiers that have been used for applicant rejection. A specific `buttonId` is automatically assigned to each rejection. For more details, see Temporary rejection and Final rejection clarification.

`questionnaires` element fields

The following table includes the data objects explaining the questionnaires that the applicant is given to complete during (or after) verification. If the applicant has already filled in a questionnaire, in the value fields, you can see the answers provided and the score assigned to them.

Field	Type	Description
`id`	String	Unique identifier of the questionnaire. You give this ID to the questionnaire when creating it.
`sections`	Object	Includes the objects each of those is a separate group of questions added to the questionnaire. A section object has an ID representing the section given when the questionnaire was created. Each section consists of items (single questions), and has its own score based on the score of the items included.
`score`	Double	When setting up a questionnaire, you have the option to set up the risk scoring. It means that you can add a value to each possible answer. When the applicant selects this answer, the assigned value is added to the score. You can set up the score for the following question types: `dropdown`, `checkboxes`, `multiple choice`. The section score depends on the score values given to the items it contains. Upon completion of the questionnaire, the system sums up the section score values which results in the entire questionnaire score.

📘
Note
Each questionnaire ID attribute should be unique. If you intend to change the questionnaire structure, IDs should not be reused.

`sections` element fields

The following table describes the sections attributes.

Name	Type	Description
`id`	String	Unique section identifier.
`condition`	String	Condition that makes a section visible, depending on the `value` of the specified `sectionId.itemId={options.value}`.
`items`	Object	Includes the objects each of those stands for a single question added to the questionnaire, and has an ID—item identifier—representing this question.

`items` element fields

The items object contains internal objects each of those stands for a single question added to the questionnaire, and has the attributes described in the table below.

Field	Type	Description	Supported values
`id`	String	Unique item identification number.	Any unique item identifier.
`condition`	String	Condition that makes the item show up.	`sectionId.itemId={options.value}` ( Example: `1-Section.1-2=someValue` )
`value`	String	Contains the value that represents an answer to a question.	Any string value.
`values`	Array of strings	Contains the values that represent multiple answers to a question (e.g. for checkboxes).	Any string values.
`score`	Double	Score that is an estimation of the sum of all answers in one question.	`Double` value.
`dataScores`	Array of objects	Compartmentalized information about risk scoring for each answer (for example, a question may have multiple answers to choose from in the checkboxes).	Each object includes the following: `value` — represents the given answer. `score` — represents the estimation of the answer.

`notes` element fields

The following table explains the data objects representing the notes added to the applicant profile by you or Sumsub operators.

Field	Type	Description
`note`	String	Contains the text of the note added.
`moderatorName`	String	Identifier of the one who created the note in the applicant profile.
`createdAt`	Date	Date and time (GMT) when the note was created.

`memberOf` element fields

The following table explains the element fields in the memberOf array which contains the objects representing the companies the beneficiary of which is this applicant, and which are registered in the Sumsub system.

Field	Type	Description
`applicantId`	String	Unique identifier of the company registered as an applicant in the Sumsub system.
`fullName`	String	Full name of the company applicant.

Response examples

{
  "id": "5b594ade0a975a36c9349e66",
  "createdAt": "2020-06-24 05:05:14",
  "clientId": "your_cool_id",
  "inspectionId": "5b594ade0a975a36c9379e67",
  "externalUserId": "SomeExternalUserId",
  "fixedInfo": {
    "firstName": "Chris",
    "lastName": "Smith"
  },
  "info": {
    "firstName": "CHRISTIAN",
    "firstNameEn": "CHRISTIAN",
    "lastName": "SMITH",
    "lastNameEn": "SMITH",
    "dob": "1989-07-16",
    "country": "DEU",
    "idDocs": [
      {
        "idDocType": "ID_CARD",
        "country": "DEU",
        "firstName": "CHRISTIAN",
        "firstNameEn": "CHRISTIAN",
        "lastName": "SMITH",
        "lastNameEn": "SMITH",
        "validUntil": "2028-09-04",
        "number": "LGXX359T8",
        "dob": "1989-07-16",
        "mrzLine1": "IDD<<LGXX359T88<<<<<<<<<<<<<<<",
        "mrzLine2": "8907167<2809045D<<<<<<<<<<<<<8",
        "mrzLine3": "SMITH<<CHRISTIAN<<<<<<<<<<<<<<",
        "nfcInfo": {
          "fullMrz": "MRZ IS HERE",
          "imageId": "IMAGE ID IS HERE"
        }        
      }
    ]
  },
  "agreement": { //present when SDK was initialized with Agreement screen enabled
    "items": [
      {
        "id": "aea6411c-4a34-4d16-9e2c-62bd2c850011",
        "acceptedAt": "2024-03-25 06:56:47",
        "source": "WebSDK",
        "type": "onboarding",
        "recordIds": [
          "6401202f39c56ebefd4497b9",
          "67f0c31bf26d8087f14d133d"
        ],
      }
    ],
  },  
  "email": "[email protected]",
  "applicantPlatform": "Android",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": [
          "PASSPORT",
          "ID_CARD"
        ]
      },
      {
        "idDocSetType": "SELFIE",
        "types": [
          "SELFIE"
        ]
      }
    ]
  },
  "review": {
    "elapsedSincePendingMs": 115879,
    "elapsedSinceQueuedMs": 95785,
    "reprocessing": true,
    "levelName": "basic-kyc",
    "createDate": "2020-06-24 05:11:02+0000",
    "reviewDate": "2020-06-24 05:12:58+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed"
  },
  "lang": "de",
  "type": "individual"
}

{
  "id": "5ecfbe9ad5ea48743f8dd1b8",
  "createdAt": "2020-05-28 13:37:30",
  "clientId": "coolclientid",
  "inspectionId": "5ecfbe9ad5ea48743f8dd1b9",
  "externalUserId": "externalCompanyId",
  "info": {
    "companyInfo": {
      "companyName": "Cool_company_name",
      "registrationNumber": "5555555",
      "country": "GBR",
      "legalAddress": "Street 123, London, England",
      "incorporatedOn": "2018-02-28 00:00:00",
      "applicantPosition": "Secretary",
      "type": "ltd",
      "email": "[email protected]",
      "phone": "(020) 0000 3333",
      "taxId": "55555276F",
      "registrationLocation": "UK Company Registration",
      "website": "www.website_name.com",
      "postalAddress": "10 St John Axe, London DT7R 00F",
      "noUBOs": true,
      "noShareholders": true,
      "beneficiaries": [
        {
          "applicantId": "5ecfbecad5ea48743f8dd438",
          "positions": [
            "director"
          ],
          "type": "ubo",
          "inRegistry": false,
          "imageIds": null,
          "applicant": null
        }
      ]
    }
  },
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "COMPANY",
        "types": [
          "COMPANY_DOC"
        ],
        "steps": [
          {
            "name": "company",
            "minDocsCnt": 1,
            "idDocTypes": [
              "COMPANY_DOC"
            ],
            "idDocSubTypes": null
          },
          {
            "name": "ubos",
            "minDocsCnt": null,
            "idDocTypes": null,
            "idDocSubTypes": null
          }
        ]
      }
    ]
  }
}

{
  "id" : "679762d6f1dbd5610000000f",
  "createdAt" : "2025-01-27 10:41:26",
  "clientId" : "cool_client_id",
  "inspectionId" : "679762d6f1dbd56171000000",
  "externalUserId" : "level-a543e802-b156-4375-8b68-000000000000",
  "info" : {
    "idDocs" : [ {
      "idDocType" : "COMPANY_DOC",
      "country" : "DEU"
    } ],
    "companyInfo" : {
      "companyName" : "COMPANY LTD",
      "registrationNumber" : "00000000",
      "country" : "GBR",
      "legalAddress" : "30 Street, London, England, 7DR",
      "incorporatedOn" : "2015-07-16 00:00:00",
      "applicantPosition" : "Secretary",
      "type" : "limitedLiabilityCompany",
      "email" : "[email protected]",
      "phone" : "(020) 0000 0000",
      "taxId" : "00000000F",
      "registrationLocation" : "UK Company Registration",
      "website" : "https://website.com/",
      "postalAddress" : "30 Street, London 7DR",
      "noShareholders" : true,
      "beneficiaries" : [ {
        "id" : "ba1ec4a0-6c39-47e0-b9a5-000000000000",
        "applicantId" : "6797633958c30f00000000gf",
        "shareSize" : 100.0,
        "types" : [ "ubo", "director" ],
        "beneficiaryInfo" : {
          "email" : "[email protected]",
          "firstName" : "John",
          "lastName" : "Doe",
          "taxResidenceCountry" : "PRT",
          "shareSize" : 100.0
        }
      } ]
    }
  },
  "fixedInfo" : {
    "companyInfo" : {
      "companyName" : "COMPANY LTD",
      "registrationNumber" : "00000000",
      "country" : "GBR",
      "legalAddress" : "30 Street, London, England",
      "incorporatedOn" : "2015-07-16 00:00:00",
      "applicantPosition" : "-",
      "type" : "limitedLiabilityCompany",
      "email" : "[email protected]",
      "phone" : "020-0000-0000",
      "taxId" : "00000000F",
      "registrationLocation" : "-",
      "website" : "https://website.com/",
      "postalAddress" : "30 Street, London 7DR",
      "noUBOs" : false,
      "noShareholders" : true,
      "beneficiaries" : [ {
        "id" : "ba1ec4a0-6c39-47e0-b9a5-000000000000",
        "applicantId" : "6797633958c30f00000000gf",
        "shareSize" : 100.0,
        "types" : [ "ubo", "director" ],
        "beneficiaryInfo" : {
          "email" : "[email protected]",
          "firstName" : "John",
          "lastName" : "Doe",
          "taxResidenceCountry" : "PRT",
          "shareSize" : 100.0
        }
      } ]
    }
  },
  "applicantPlatform" : "Web",
  "ipCountry" : "DEU",
  "authCode" : "dglkbnzd;fkjnLULHLugluhlUGlyuhgvlUH;ihj;IH;ughkuhg;0MTQzNiwic3ViIjoibGV2ZWwtYTU0M2U4MDItYjE1Ni00Mzc1LThiNjgtNWJhNzhkMzBiOGU1IiwiYXVkIjoic3KDjnfzvkdfnH:H>IHJ/lihfr/xfmQ2ZjFkYmQ1NjE3MWY4YTk2NiJ9._eRh4qLCRxJA6lk6hKJrt-H67X9fmggdFEMpxaAmn_Y",
  "agreement" : {
    "createdAt" : "2025-01-27 10:41:29",
    "acceptedAt" : "2025-01-27 10:41:29",
    "source" : "WebSDK"
  },
  "requiredIdDocs" : {
    "docSets" : [ {
      "idDocSetType" : "COMPANY_DATA",
      "fields" : [ {
        "name" : "companyName",
        "required" : true
      }, {
        "name" : "country",
        "required" : true
      }, {
        "name" : "registrationNumber",
        "required" : false
      }, {
        "name" : "incorporatedOn",
        "required" : false
      }, {
        "name" : "website",
        "required" : false
      }, {
        "name" : "legalAddress",
        "required" : false
      }, {
        "name" : "state",
        "required" : false
      } ]
    }, {
      "idDocSetType" : "COMPANY_BENEFICIARIES",
      "companyBeneficiaryDefinitions" : [ {
        "category" : "ubos",
        "canSkip" : true,
        "individual" : {
          "enabled" : true,
          "levelName" : "basic-kyc-level",
          "fields" : [ {
            "name" : "firstName",
            "required" : true
          }, {
            "name" : "lastName",
            "required" : true
          }, {
            "name" : "middleName",
            "required" : false
          }, {
            "name" : "dob",
            "required" : false
          }, {
            "name" : "taxResidenceCountry",
            "required" : true
          }, {
            "name" : "shareSize",
            "required" : true
          } ],
          "customFields" : null
        }
      }, {
        "category" : "shareholders",
        "canSkip" : true,
        "individual" : {
          "enabled" : true,
          "levelName" : "basic-kyc-level",
          "fields" : [ {
            "name" : "firstName",
            "required" : true
          }, {
            "name" : "lastName",
            "required" : true
          }, {
            "name" : "middleName",
            "required" : false
          }, {
            "name" : "dob",
            "required" : false
          }, {
            "name" : "taxResidenceCountry",
            "required" : false
          }, {
            "name" : "shareSize",
            "required" : true
          } ],
          "customFields" : null
        },
        "company" : {
          "enabled" : true,
          "levelName" : "Auto KYB demo",
          "fields" : [ {
            "name" : "companyName",
            "required" : true
          }, {
            "name" : "country",
            "required" : true
          }, {
            "name" : "registrationNumber",
            "required" : false
          } ],
          "customFields" : null
        }
      }, {
        "category" : "directors",
        "individual" : {
          "enabled" : true,
          "levelName" : "basic-kyc-level",
          "fields" : [ {
            "name" : "firstName",
            "required" : true
          }, {
            "name" : "lastName",
            "required" : true
          }, {
            "name" : "middleName",
            "required" : false
          }, {
            "name" : "dob",
            "required" : false
          }, {
            "name" : "email",
            "required" : true
          }, {
            "name" : "phone",
            "required" : false
          } ],
          "customFields" : null
        },
        "company" : {
          "enabled" : false,
          "levelName" : "Auto KYB demo",
          "fields" : [ {
            "name" : "companyName",
            "required" : true
          }, {
            "name" : "country",
            "required" : true
          }, {
            "name" : "registrationNumber",
            "required" : true
          } ],
          "customFields" : null
        }
      } ]
    }, {
      "idDocSetType" : "COMPANY_DOCUMENTS",
      "companyDocsGroupDefinitions" : [ {
        "label" : "legalPresence",
        "subTypes" : [ "INCORPORATION_CERT", "INCORPORATION_ARTICLES", "STATE_REGISTRY" ],
        "required" : true
      }, {
        "label" : "companyDetails",
        "subTypes" : [ "INFORMATION_STATEMENT", "PROOF_OF_ADDRESS", "STATE_REGISTRY", "INCORPORATION_ARTICLES", "INCORPORATION_CERT", "INCUMBENCY_CERT", "GOOD_STANDING_CERT" ],
        "required" : true
      } ]
    } ],
    "kybSettings" : {
      "shareholderThreshold" : 5.0,
      "uboThreshold" : 25.0
    }
  },
  "review" : {
    "reviewId" : "bUKIB",
    "attemptId" : "OKxAF",
    "attemptCnt" : 1,
    "elapsedSincePendingMs" : 219,
    "levelName" : "Auto KYB demo",
    "createDate" : "2025-01-27 10:44:39+0000",
    "reviewDate" : "2025-01-27 10:44:39+0000",
    "reviewResult" : {
      "reviewAnswer" : "GREEN"
    },
    "reviewStatus" : "completed"
  },
  "lang" : "en",
  "type" : "company",
  "riskLabels" : {
    "attemptId" : "SLfbz",
    "createdAt" : "2025-01-27 10:44:39",
    "device" : [ "vpnUsage" ],
    "crossCheck" : [ "manyAccountDuplicates" ]
  }
}

Applicant life-cycle

The following is a typical applicant life-cycle:

When you create an applicant, they receive an init status.
After uploading all required documents, the status changes to pending.
You must then let us know that the applicant is ready to be reviewed.
After the verification process is complete, the applicant status changes to completed.

Create applicant

Table of contents

Overview

📘
Note

👍
Tip

Specifics of creating company applicants

📘
Note

`companyInfo` arguments

`address` arguments

Request examples

Response explained

Root variables

`info` attributes

`companyInfo` attributes

`beneficiaries` element fields

`beneficiaryInfo` attributes

`idDocs` element fields

`address` attributes and `addresses` element fields

`nfcInfo` attributes

`fixedInfo` attributes

`agreement` attributes

🚧
Attention

`requiredIdDocs` attributes

`docSets` element fields

`companyBeneficiaryDefinitions` element fields

`individual` and `company` attributes

`companyDocsGroupDefinitions` element fields

`review` attributes

`reviewResult` attributes

`questionnaires` element fields

📘
Note

`sections` element fields

`items` element fields

`notes` element fields

`memberOf` element fields

Response examples

Applicant life-cycle

Table of contents

Overview

📘Note

👍Tip

Specifics of creating company applicants

📘Note

companyInfo arguments

address arguments

Request examples

Response explained

Root variables

info attributes

companyInfo attributes

beneficiaries element fields

beneficiaryInfo attributes

idDocs element fields

address attributes and addresses element fields

nfcInfo attributes

fixedInfo attributes

agreement attributes

🚧Attention

requiredIdDocs attributes

docSets element fields

companyBeneficiaryDefinitions element fields

individual and company attributes

companyDocsGroupDefinitions element fields

review attributes

reviewResult attributes

questionnaires element fields

📘Note

sections element fields

items element fields

notes element fields

memberOf element fields

Response examples

Applicant life-cycle

📘
Note

👍
Tip

📘
Note

`companyInfo` arguments

`address` arguments

`info` attributes

`companyInfo` attributes

`beneficiaries` element fields

`beneficiaryInfo` attributes

`idDocs` element fields

`address` attributes and `addresses` element fields

`nfcInfo` attributes

`fixedInfo` attributes

`agreement` attributes

🚧
Attention

`requiredIdDocs` attributes

`docSets` element fields

`companyBeneficiaryDefinitions` element fields

`individual` and `company` attributes

`companyDocsGroupDefinitions` element fields

`review` attributes

`reviewResult` attributes

`questionnaires` element fields

📘
Note

`sections` element fields

`items` element fields

`notes` element fields

`memberOf` element fields