Overview
Use this method in cases the applicant ID is not yet known to you. For example, when the WebSDK has created an applicant for you and we called your webhook endpoint.
Request example
curl -X GET \
'https://api.sumsub.com/resources/applicants/5b594ade0a975a36c9349e66/one'
Note
- Some data is shown only if it was recognized from the documents or provided by the applicant.
- To make sure you have fetched the data from a relevant document, you can get what
idDocTypeandcountrywas approved using this method.
Tip
To retrieve applicant data by a known applicant ID in the Sumsub system, use the following method.
Response explained
The response is a JSON object representing the applicant profile that you created (or that Sumsub created for you, for example via the WebSDK), enriched with structured data.
The presence of certain fields depends on the documents and data submitted for verification, applicable verification rules, and the permissions assigned to the app token at creation time.
Below, you can see the response structure, possible content with descriptions, and examples of response:
- Root variables
- info
- fixedInfo
- agreement
- requiredIdDocs
- review
- assessment
- 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, in the 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.This field supports up to 512 characters. |
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. This field must contain a valid email address in an RFC 5321/5322 format with TLD verification. |
phone | String | Applicant phone number. It is mandatory if the phone verification is required. This field must contain a valid phone number in ITU-T E.164 format. |
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 (for example, DEU, GBR, ARE) 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 (for example, IDENTITY, SELFIE) and the documents appropriate for each step (for example, 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. |
deleted | Boolean | Indicates whether the applicant profile has ever been deactivated.
|
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 | The metadata field contains additional information in the form of key-value pairs (keys must not be null). This data is 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:
|
registrationDate | Date | Date and time when the applicant was initially registered in your system. Format: YYYY-MM-DD hh:mm:ss (for example, 2025-01-15 10:20:35). |
riskLabels | Object | Contains information on the applicant risk labels. |
assessment | Object | Includes applicant assessment data, such as the total score, scores based on specific factors, scoring tags, score weights, whether scores are included in the total score, related transactions with dates, and other assessment details. |
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
info attributesThe following table explains the info object attributes — general applicant information recognized from the documents that Sumsub cross-validates with the applicant data provided (fixedInfo).
| Field | Type | Description |
|---|---|---|
companyInfo | Object | 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. There is no length limit for this field. |
firstNameEn | String | Automatic transliteration of the applicant first name into Latin characters. There is no length limit for this field. |
middleName | String | Applicant middle name in the original language. There is no length limit for this field. |
middleNameEn | String | Automatic transliteration of the applicant middle name into Latin characters. There is no length limit for this field. |
lastName | String | Applicant last name in the original language. There is no length limit for this field. |
lastNameEn | String | Automatic transliteration of the applicant last name into Latin characters. There is no length limit for this field. |
aliasName | String | Alternative first/last name. |
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.There is no length limit for this field. |
gender | String | Gender of the applicant (M, F, or X). This field is omitted if gender is not specified in the applicant profile. |
dob | Date | Applicant date of birth (ISO 8601 format yyyy-MM-dd, for example, 2001-09-25). |
placeOfBirth | String | Applicant place of birth. This can be a city, a town or another settlement type. There is no length limit for this field. |
placeOfBirthEn | String | Automatic transliteration of the applicant place of birth. There is no length limit for this field. |
countryOfBirth | String | Applicant country of birth. Presented as an ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
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 ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
nationality | String | Applicant country of origin. Presented as an ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
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. ⚠️This field has a country-specific format. |
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
companyInfo attributesThe 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. There is no length limit for this field. |
registrationNumber | String | Unique number that is assigned to the company when it was registered as a legal entity. |
country | String | ISO 3166-1 alpha-3 code of the country where the company is legally registered (for example, DEU, GBR). |
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 (ISO 8601 format yyyy-MM-dd, for example, 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 (RFC 5321/5322 format). |
phone | String | Company phone number (ITU-T E.164 format). |
taxId | String | Taxpayer registration number/Code of taxpayer registration. ⚠️This field has a country-specific format. |
leiCode | String | Legal Entity Identifier (LEI) code. Refers to the public identifier from the financial entities registry. |
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. |
skippedTypes | Array of strings | Includes the required values (shareholder, ubo, representative, director) to verify a company applicant without the corresponding entities specified in the company profile.⚠️ Applicable to the fixedInfo object only. |
noDocs | Boolean | Indicates whether company documents must be uploaded to proceed verification.
|
beneficiaries | Array of objects | Contains applicantIds of beneficiaries and additional information such as position and type. |
beneficiaries element fields
beneficiaries element fieldsThe following table describes the beneficiaries array of objects containing applicantIds of beneficiaries and additional information such as their position and type within the company.
⚠️ The beneficiaries array is only available for company applicants.
| 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. |
types | Array of strings | Beneficiary roles for the new data structure, when one entity may have multiple roles. Possible values:
|
shareSize | Double | Percentage of ownership if the beneficiary is a shareholder of the company. |
beneficiaryInfo attributes
beneficiaryInfo attributesThe following table explains the beneficiaryInfo attributes representing the beneficiary contact data.
⚠️ Available for company applicants only.
| Field | Type | Description |
|---|---|---|
firstName | String | First name of the beneficiary. There is no length limit for this field. |
lastName | String | Last name of the beneficiary. There is no length limit for this field. |
dob | Date | Beneficiary date of birth. |
email | String | Beneficiary email address (RFC 5321/5322format). |
taxResidenceCountry | String | Country where the beneficiary pays taxes. Presented as an alpha-3 code (for example, DEU, GBR, ARG). |
shareSize | Double | Percentage of ownership if the beneficiary is a shareholder of the company. |
idDocs element fields
idDocs element fieldsThe 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. |
ocrDocType | String | Specifies the document subtype as a full type identifier (for example,
Additional variations may be the following:
If the subtype cannot be determined, the field is returned empty. ⚠️ Note: This field is intended for analytical purposes only. Do not rely on its value for critical business logic, as it may not always be determinable with full accuracy. |
country | String | ISO 3166-1 alpha-3 code (for example, DEU, GBR, ARG) of the country where the document was issued. |
firstName | String | Applicant first name in the original language as it is in the document. There is no length limit for this field. |
firstNameEn | String | Automatic transliteration of the applicant first name into Latin characters. There is no length limit for this field. |
middleName | String | Applicant middle name in the original language as it is in the document. There is no length limit for this field. |
middleNameEn | String | Automatic transliteration of the applicant middle name into Latin characters. There is no length limit for this field. |
lastName | String | Applicant last name in the original language as it is in the document. There is no length limit for this field. |
lastNameEn | String | Automatic transliteration of the applicant last name into Latin characters. There is no length limit for this field. |
aliasName | String | Alternative first/last name. |
title | String | A word or abbreviation placed before a person's name to indicate their profession, social rank, academic degree, or form of address (Dr, Mr, Ms, Prof, and so on). |
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 Issuing Authority that is in charge of issuing the uploaded document. |
termless | Boolean | Indicates whether the document is marked as valid indefinitely (true) or not (false); see the validUntil field for the expiration date.⚠️ For now, "validUntil": "2099-01-01" will be returned for documents marked as indefinite ("termless": true). This is a temporary behavior and will be discontinued in the coming months. |
validUntil | Date | Date when the document validity expires. |
extendedValidUntil | Date | Additional date when the document validity expires, in case the document validity has been extended (format: YYYY-MM-DD, for example, 2029-05-20).ⓘ Returned only if custom rules are applied to extend validUntil, or if country-specific document prolongation rules are in effect. |
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 (ISO 8601, in the format yyyy-MM-dd (for example, 2001-09-25) as it is specified in the document. |
address | Object | Includes the applicant address details. |
ethnicity | String | Indicates the applicant's ethnic background. Presented as a custom value. |
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
address attributes and addresses element fieldsThe 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. |
stateCode | String | Applicant state code based on the address. A list of state codes is based on the ISO 3166-2 format (for example, TR-34, AD-07). |
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 | ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
formattedAddress | String | Address in a human readable format. For example, Design Offices, Philipsbornstraße 2, 30165 Hannover, Germany. |
source | String | Address data source. This information can be obtained from Applicant data, Proof of Address, and Geo as PoA. |
nfcInfo attributes
nfcInfo attributesThe 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
fixedInfo attributesThe 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).
| Field | Type | Description |
|---|---|---|
companyInfo | Object | 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. There is no length limit for this field. |
firstNameEn | String | Automatic transliteration of the applicant first name into Latin characters. There is no length limit for this field. |
middleName | String | Applicant middle name in the original language. There is no length limit for this field. |
middleNameEn | String | Automatic transliteration of the applicant middle name into Latin characters. There is no length limit for this field. |
lastName | String | Applicant last name in the original language. There is no length limit for this field. |
lastNameEn | String | Automatic transliteration of the applicant last name into Latin characters. There is no length limit for this field. |
aliasName | String | Alternative first/last name. |
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.There is no length limit for this field. |
gender | String | Gender of the applicant (M, F, or X). This field is omitted if gender is not specified in the applicant profile. |
dob | Date | Applicant date of birth (ISO 8601 format yyyy-MM-dd, for example, 2001-09-25). |
placeOfBirth | String | Applicant place of birth. This can be a city, a town or another settlement type. There is no length limit for this field. |
placeOfBirthEn | String | Automatic transliteration of the applicant place of birth. There is no length limit for this field. |
countryOfBirth | String | Applicant country of birth. Presented as an ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
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 ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
nationality | String | Applicant country of origin. Presented as an ISO 3166-1 alpha-3 country code (for example, DEU, GBR, ARG). |
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 ISO 3166-1 alpha-3 code (for example, DEU, GBR, ARG). |
agreement attributes
agreement attributesAttention
A new data format for the
agreementobject 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
acceptedAttimestamp.
| 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 (for example, during onboarding, via reusable KYC, and so on). |
recordIds | Array of strings | Each recordId corresponds to an individual accepted agreement text. |
requiredIdDocs attributes
requiredIdDocs attributesThe 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. |
videoIdentSettings | Object | Contains the
⚠️ This field is available only if the setting is configured for the level. |
videoIdentUploadTypes | Array of strings | Lists the document types that can be uploaded during a video interview, if such documents are specified in the level settings. The field is available if the video identification is required on the level. |
stepsOutsideVideoId | Array of strings | Lists the verification steps that can be passed outside the video identification. The field is available if the video identification is required on the level. |
includedCountries | Array of strings | Countries (in ISO 3166-1 alpha-3 country code, for example, DEU, GBR, ARG) that are included in the list of supported. |
excludedCountries | Array of strings | Countries (in ISO 3166-1 alpha-3 country code, for example, DEU, GBR, ARG) that are excluded from the list of supported. |
docSets | Array of objects | Includes the objects representing specific document sets and their attributes. |
kybSettings | Object | Available for company applicants. Includes the settings that are used to identify the types of company beneficiaries, to enable/disable company search in selected registry databases and automatic verification of the company's ownership and control structure. |
docSets element fields
docSets element fieldsThe following table explains the element fields of the docSets array representing specific document sets and their attributes.
| Field | Type | Description |
|---|---|---|
idDocSetType | String | A human-readable identifier of the document set type (for example, IDENTITY, SELFIE, PROOF_OF_RESIDENCE). |
types | Array of strings | Includes the types of documents that are required for a particular idDocSetType to pass verification. |
subTypes | Array of strings | List of document subtypes required for verification (applicable only to company documents). |
videoRequired | String | Method of passing the document upload step that can be set up when configuring a verification level.
|
captureMode | String | Applicable only when
|
uploaderMode | String | Applicable only when
|
fields | Array of objects | Contains objects that define the document data fields to be populated with personal information for verifying the applicant during the Applicant data verification step. |
customFields | Array of objects | Contains objects that describe custom fields if they are created for the Applicant data verification step. |
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. |
poaStepSettingsId | String | Identifier of the selected Proof of Address preset. |
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. |
captureParams | Object | Describes the capture method and related settings for this step. Contains the
If
If |
ekycAllowed | Boolean | Indicates if Non-Doc Verification for the step is allowed (true) or not (false). |
checkSourceSettings | Object | Describes the configuration of the Database Validation setting for the verification level. |
esignSettings | Object | Contains configuration for the E-sign verification step, including objects that define the document to be signed (ID and name) and signature settings. |
restrictCountries | Boolean | Returns true if the verification step restricts applicants from specific countries. Otherwise the field is not returned. |
skipAllowed | Boolean | Indicates whether this verification step can be skipped (true) or not (false).Available only for steps that support the skip option. |
nfcVerificationSettings | Object | Contains the
|
phoneVerificationSettings | Object | Contains the
|
emailVerificationSettings | Object | Contains the
|
selfieProcessingSettings | Object | Contains the
|
applicantDataSettings | Object | Contains the
|
fields element fields
fields element fieldsThe following table explains the fields element fields.
| Field | Type | Description |
|---|---|---|
name | String | Field name (for example, firstName, lastName, email). |
required | Boolean | true if the field is required for verification, false if not (still, it can be optionally filled in the SDK). |
prefill | Boolean | true if the field is pre-populated in the SDK, false if not. |
immutableIfPresent | Boolean | true if the field is locked and cannot be edited by the applicant; false otherwise. |
customFields element fields
customFields element fieldsThe following table explains the customFields element fields.
| Field | Type | Description |
|---|---|---|
name | String | System name of the custom field. |
displayName | String | Name of the field as it is shown to the applicant. |
required | Boolean | Returns true if the field is required for verification, false if not (still, it can be optionally filled in the SDK). |
companyBeneficiaryDefinitions element fields
companyBeneficiaryDefinitions element fieldsThe following table explains the 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
individual and company attributesthe following table explains the 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. There is no length limit for this field. |
fields | Array of objects | Includes the objects describing the data fields that should be filled with personal information to verify the applicant. |
customFields | Array of objects | Includes the objects each of those represents an additional custom field (applicantIdDocSetCustomField) that should be filled for verification. |
companyDocsGroupDefinitions element fields
companyDocsGroupDefinitions element fieldsThe following table explains the companyDocsGroupDefinitions element fields.
| Field | Type | Description |
|---|---|---|
label | String | Label of the document group. Available labels: legalPresence, companyDetails, ownershipStructure, controlStructure, representativesAuthorization, other1, other2, other3. |
subTypes | Array of strings | List of document types included into the verification group. |
required | Boolean | Indicates if this is required (true) or optional (false). |
kybSettings attributes
kybSettings attributesThe following table explains the kybSettings attributes.
| Field | Type | Description |
|---|---|---|
shareholderThreshold | Integer | Ownership percentage threshold used to classify an individual beneficiary as a shareholder. If shareholderThreshold is less and uboThreshold is greater than the ownership percentage, then the individual is a shareholder.Companies are always classified as shareholders. |
uboThreshold | Integer | Ownership percentage threshold used to classify an individual beneficiary as a UBO (Ultimate Beneficial Owner). If the ownership percentage is greater than or equal to uboThreshold, then the individual is a UBO.Companies are always classified as shareholders. |
disableCompanySearchAndPrefill | Boolean | Indicates whether company search in selected corporate registry databases for pre-filling company and associated parties’ data is disabled (true) or enabled (false). |
enableBeneficiariesAutoCheck | Boolean | Indicates whether automatic verification of the company’s ownership and control structure against selected corporate registries is enabled.
|
review attributes
review attributesThe 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. There is no length limit for this field. |
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 | Long | 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
reviewResult attributesThe following table explains the reviewResult attributes representing the applicant verification result details.
| Field | Type | Description |
|---|---|---|
reviewAnswer | String | Explains the review result.
|
rejectLabels | Array of strings | Includes one or more reasons for rejection. The field is available if reviewAnswer returns RED.For more information, see Resubmission requested and Rejected . |
reviewRejectType | String | Indicates the type of rejection.
For more information, see Resubmission requested and Rejected . |
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 type. For more information, see Resubmission requested and Rejected . |
assessment attributes
assessment attributesThe following table explains the assessment attributes.
| Field | Type | Description |
|---|---|---|
totalScore | Float | Final aggregated assessment score calculated from all scores included in the total score. |
scores | Array of objects | Each object represents an individual assessment score based on a specific factor contributing to the overall evaluation. |
scores element fields
scores element fieldsThe following table explains the scores element fields.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier of the score entry. |
tag | String | Tag associated with the score, indicating the factor it relates to. |
createdAt | Date | Date and time when the score was generated, in the format YYYY-MM-DD hh:mm:ss+0000 (for example, 2025-12-12 13:04:59+0000). |
score | Float | Raw score value produced by the evaluation logic. |
scoreWeight | Float | Weight applied to the score when calculating the total score. |
includeInTotalScore | Boolean | Indicates whether this score is included in the totalScore calculation (true), or not (false). |
txnId | String | Unique identifier of the transaction in the Sumsub system related to this score, if applicable. |
rules | Array of objects | List of rules that contributed to this score. |
rules element fields
rules element fieldsThe following table explains the rules element fields.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier of the rule. |
name | String | System name of the rule. |
title | String | Human-readable title of the rule. |
revision | Integer | Revision number of the rule definition. |
tags | Array of strings | Tags associated with the rule for categorization and filtering. |
questionnaires element fields
questionnaires element fieldsThe 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, country (countrySelect or countryMultiSelect).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
IDattribute should be unique. If you intend to change the questionnaire structure, IDs should not be reused.
sections element fields
sections element fieldsThe 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}. |
score | Double | Score that is an estimation of the sum of all scores in one section. |
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
items element fieldsThe 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 (for example, 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:
|
notes element fields
notes element fieldsThe 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
memberOf element fieldsThe 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
If the request is successfully sent and processed, you will get a response like one of those below.
{
"id": "5b594ade0a975a36c9349e66",
"createdAt": "2020-06-24 05:05:14",
"clientId": "your_cool_id",
"inspectionId": "5b594ade0a975a36c9379e67",
"externalUserId": "SomeExternalUserId",
"info": {
"firstName": "CHRISTIAN",
"firstNameEn": "CHRISTIAN",
"lastName": "SMITH",
"lastNameEn": "SMITH",
"aliasName": "BROOKS",
"dob": "1989-07-16",
"country": "DEU",
"idDocs": [
{
"idDocType": "ID_CARD",
"country": "DEU",
"firstName": "CHRISTIAN",
"firstNameEn": "CHRISTIAN",
"lastName": "SMITH",
"lastNameEn": "SMITH",
"aliasName": "BROOKS",
"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"
}
}
]
},
"fixedInfo": {
"firstName": "Chris",
"lastName": "Smith",
"aliasName": "Brooks"
},
"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": "679762d6f1dbd5610000000f",
"createdAt": "2025-01-27 10:41:26",
"clientId": "cool_client_id",
"inspectionId": "679762d6f1dbd56171000000",
"externalUserId": "level-a543e802-b156-4375-8b68-000000000000",
"info": { // The results of verification are stored here.
"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",
"beneficiaries": [
{
"id": "ba1ec4a0-6c39-47e0-b9a5-000000000000",
"applicantId": "6797633958c30f00000000gf",
"shareSize": 100,
"types": [
"ubo",
"director"
],
"beneficiaryInfo": {
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"taxResidenceCountry": "PRT",
"shareSize": 100
}
}
]
}
},
"fixedInfo": { // This is what is expected to get from the applicant input.
"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",
"skippedTypes": [
"director",
"representative"
],
}
},
"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,
"uboThreshold": 25
}
},
"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"
]
}
}
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:
{
"code": 400,
"correlationId": "345fd9bcc7d3a7670c5a6b25fcd7d0dd",
"description": "Invalid parameters provided"
}