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.

For tin and taxId fields, the required format depends on the country. For example:

USA: ###-##-####, for example, 123-45-6789

Colombia: #.###.###.###, for example, 1.123.456.789

Malaysia: ######-##-####, for example, 010101-11-1234

Hong Kong: [A-Z]{1,2}[0-9]{6}[0-9A], for example, AZ123456A

Japan: 11-12 digits, for example, 123456789012

Chile: ########-[0-9A-Za-z], for example, 12345678-9

Kazakhstan: 12 digits, for example, 123456789012

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 fixedInfo.companyInfo object within the request. The fixedInfo.companyInfo object attributes are required to validate the company data during verification. It should cover all steps enabled in the level. This information should be provided before requesting a check.

The info.companyInfo object in the response is used to gather and generate the Extracted Company Data output which is based on the data from documents and Company checks. It's not provided at the moment of applicant creation, unless you have already collected some verified data.

📘
Note
For KYB 2.0, embed companyInfo inside the fixedInfo object. See the request examples below.

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",
        "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 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
- companyInfo
  - beneficiaries
  - beneficiaryInfo
- address, addresses
agreement
requiredIdDocs
- docSets
review
- reviewResult
assessment
- scores
- rules
questionnaires
- sections
- items
notes
memberOf
Response examples

`info` attributes

📘
Note
In the response to this API call, the info object is returned empty. You can retrieve this data using this method once the applicant profile contains information recognized from documents. See possible info content on this page.

`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).

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`).

`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. 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. `true` — uploading company documents is optional. `false` (default) — at least one document must be uploaded.
`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 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: `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. `companyOfficer` — holds an executive position within the company (for example, CEO, CFO, COO). ⚠️ Not verifiable by Sumsub, for your internal use only. `investor` — provides capital to the company without necessarily holding controlling shares. ⚠️ Not verifiable by Sumsub, for your internal use only. `secretary` — responsible for administrative tasks and regulatory compliance of the company. `founder` — established the company or contributed to its initial creation. `legalAdvisor` — professionally provides legal counsel or representation for the company. `authorizedSignatory` — officially authorized to sign documents and contracts on behalf of the company. Trust roles that should be used exclusively for Trust flows. `trustee` — holds assets in a trust for the benefit of beneficiaries. `trustBeneficiary` — entitled to benefit from assets held in a trust. `trustSettlor` — creates a trust and transfers assets into it. `trustProtector` — appointed to oversee the administration of a trust to safeguard the interests of beneficiaries.
`shareSize`	Double	Percentage of ownership if the beneficiary is a shareholder of the company.

`beneficiaryInfo` attributes

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

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

`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 (for example, during onboarding, via reusable KYC, and so on).
`recordIds`	Array of strings	Each `recordId` corresponds to an individual accepted agreement text.

`customFields` element fields

The 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

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

`companyDocsGroupDefinitions` element fields

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

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

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 information, see Resubmission requested and Rejected .
`reviewRejectType`	String	Indicates the type of rejection. `FINAL` — Rejected status 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 in this status will not be able to resubmit the documents for verification. `RETRY` — Resubmission requested status in case of minor violations. For example, a name or address mismatch, incorrect TIN was provided, and so on. The applicant is sent a resubmission request. Thus the applicant has a chance to upload new documents or resubmit correct data. 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

The 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

The 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

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

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

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": {}, // Returned empty.
  "fixedInfo": {
    "firstName": "Daniel",
    "lastName": "Brooks",
    "aliasName": "Dan Brooks"
  },
  "agreement": { // Present when the 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": {
    "reviewId": "QtIxN",
    "attemptId": "zlZlO",
    "attemptCnt": 0,
    "levelName": "test_level",
    "createDate": "2020-06-24 05:05:14",
    "reviewStatus": "init"
  },
  "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": {}, // Returned empty.
  "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": "78f4988e0d611cb0ba6fa52603f4b2b0",
   "description": “Existing level should be specified to create an applicant”
}

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

Request examples

Response explained

`info` attributes

Note

`fixedInfo` attributes

`companyInfo` attributes

`beneficiaries` element fields

`beneficiaryInfo` attributes

`address` attributes and `addresses` element fields

`agreement` attributes

Attention

`customFields` element fields

`companyBeneficiaryDefinitions` element fields

`companyDocsGroupDefinitions` element fields

`review` attributes

`reviewResult` attributes

`assessment` attributes

`scores` element fields

`rules` element fields

`notes` element fields

Response examples

Applicant life-cycle

Table of contents

Overview

Note

Tip

Specifics of creating company applicants

Note

Request examples

Response explained

info attributes

Note

fixedInfo attributes

companyInfo attributes

beneficiaries element fields

beneficiaryInfo attributes

address attributes and addresses element fields

agreement attributes

Attention

customFields element fields

companyBeneficiaryDefinitions element fields

companyDocsGroupDefinitions element fields

review attributes

reviewResult attributes

assessment attributes

scores element fields

rules element fields

notes element fields

Response examples

Applicant life-cycle

`info` attributes

`fixedInfo` attributes

`companyInfo` attributes

`beneficiaries` element fields

`beneficiaryInfo` attributes

`address` attributes and `addresses` element fields

`agreement` attributes

`customFields` element fields

`companyBeneficiaryDefinitions` element fields

`companyDocsGroupDefinitions` element fields

`review` attributes

`reviewResult` attributes

`assessment` attributes

`scores` element fields

`rules` element fields

`notes` element fields