Table of contents

• Overview
• Specifics of creating company applicants
• Request examples
• Response explained
• Response examples
• Applicant life-cycle

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.

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.

beneficiaries arguments

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

address arguments

The following table explains available details of the company address.

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

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.

companyInfo attributes

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

⚠️ This object is only available for company applicants.

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.

beneficiaryInfo attributes

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

⚠️ Available for company applicants and KYB 2.0 only.

idDocs element fields

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

address attributes and addresses element fields

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

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.

agreement attributes

The following table explains the details of the applicant consent to the submitting and processing of personal data.

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.

docSets element fields

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

review attributes

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

reviewResult attributes

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

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.

📘

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.

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.

notes element fields

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

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.

Response examples

{
  "id": "5b594ade0a975a36c9349e66",
  "createdAt": "2020-06-24 05:05:14",
  "clientId": "ClientName",
  "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<<<<<<<<<<<<<<"
      }
    ]
  },
  "agreement": {  //present when SDK was initialized with Agreement screen enabled
    "createdAt": "2020-06-24 04:18:40",
    "source": "WebSDK",
    "targets": [
      "By clicking Next, I accept [the Terms and Conditions](https://www.sumsub.com/consent-to-personal-data-processing/)",
      "I agree to the processing of my personal data, as described in [the Consent to Personal Data Processing](https://sumsub.com/consent-to-personal-data-processing/)"
    ]
  },
  "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": "SUMSUB LIMITED",
      "registrationNumber": "1555555",
      "country": "GBR",
      "incorporatedOn": "2018-02-28 00:00:00",
      "type": "ltd",
      "website": "www.sumsub.com",
      "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
          }
        ]
      }
    ]
  },
  "review": {
    "elapsedSincePendingMs": 308656,
    "elapsedSinceQueuedMs": 26993,
    "reprocessing": true,
    "createDate": "2020-05-29 12:22:11+0000",
    "reviewDate": "2020-05-29 12:27:19+0000",
    "startDate": "2020-05-29 12:26:52+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed"
  },
  "lang": "en",
  "type": "company"
}

Applicant life-cycle

The following is a typical applicant life-cycle:

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