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.

Example request

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 idDocType and country was 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 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.

Field	Type	Description
`id`	String	A unique applicant identifier in the Sumsub system (`applicantId`). This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant profile is created on the Sumsub side.
`createdAt`	Date	Date and time (GMT) when the applicant profile was created in the Sumsub system. Format: `YYYY-MM-DD HH:MI:SS`.
`clientId`	String	A 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	A 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	A unique applicant identifier as it is registered on your side. You can generate and add it manually when creating the applicant. If not, the external user ID is added automatically.
`sourceKey`	String	A 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’s email address. It is mandatory if the email verification is required. If not provided, the applicant cannot receive verification status emails.
`phone`	String	Applicant’s phone number. It is mandatory if the phone verification is required.
`applicantPlatform`	String	The platform from which the applicant registered in the system and/or provided profile data (`API`, `Web`, `Android`, `iOS`).
`ipCountry`	String	Alpha-3 country code (`DEU`, `GBR`, `ARE`, and so on) of the country that owns the IP address from which the applicant got registered and/or submitted the data.
`authCode`	String	JWT token to sign in a user. For more details, refer to WebSDK Settings.
`agreement`	Object	Contains information about the applicant consent to submitting and processing the personal data.
`requiredIdDocs`	Object	Configuration of steps for the applicant to complete verification. It includes step types (e.g. `IDENTITY`, `SELFIE`) and the documents appropriate for each step (e.g. `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`), or necessary data fields to be filled in. For example, the `APPLICANT_DATA` step type includes a list of fields the applicant must fill in, so we could proceed with verification.
`review`	Object	Explains the details of the current applicant verification status and check result.
`lang`	String	Two-letter code of the language (ISO 639-1 format, for example, `en`, `fr`, `de`) for the SDK and emails sent to the applicant. The verification results should be displayed to the applicant in this language as well. As a rule, it is detected by the applicant IP address. You can set the language when initializing the SDK (MSDK), or via API when creating an applicant.
`type`	Enum	Defines the applicant type. Added automatically when the applicant is created. The following entity types are available: `individual` — for applicants registered and checked as individuals. `company` — for applicants registered and checked as legal entities.
`questionnaires`	Array of objects	Includes the objects describing questionnaires that the applicant is given to complete during (or after) verification. If the applicant has already filled a questionnaire, you can see the submitted answers in the `value` fields.
`notes`	Array of objects	Includes the objects representing notes added to the applicant profile by you or by Sumsub operators.
`tags`	Array of strings	Contains tags that you have created and then assigned to the applicant.
`memberOf`	Array of objects	Includes data objects with the applicant companies' IDs the beneficiary of which the applicant is and which are registered in the Sumsub system.

`info` attributes

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

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

Field	Type	Description
`companyInfo`	Object	⚠ Available for company applicants only. The object contain general information about the company, such as the company name, location and country of registration, legal entity type, contacts and other details.
`firstName`	String	Applicant first name in the original language.
`firstNameEn`	String	Automatic transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant middle name in the original language.
`middleNameEn`	String	Automatic transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant last name in the original language.
`lastNameEn`	String	Automatic transliteration of the applicant last name into Latin characters.
`legalName`	String	Legal name of the company the applicant is related to (UBO or shareholder). You can keep this information and use it for your personal navigation. Note that the `legalName` field is not checked and you might need it just in case.
`gender`	String	Applicant gender (`M` or `F`). If the gender was not specified in the applicant profile, this field will not be present.
`dob`	Date	Applicant date of birth (format `YYYY-mm-dd`, e.g. `2001-09-25`).
`placeOfBirth`	String	Applicant place of birth. This can be a city, a town or another settlement type.
`country`	String	Applicant country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`nationality`	String	Applicant country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`addresses`	Array of objects	Includes data objects containing the applicant address details extracted from the PoA documents submitted by the applicant.
`tin`	String	Taxpayer identification number that is unique to each taxpayer.
`idDocs`	Array of objects	Includes data objects containing information extracted from the applicant documents, which can be useful in cases where a verification has been completed.

`companyInfo` attributes

The following table explains the companyInfo object attributes that you can provide when creating a company applicant, or obtain when getting the company applicant data.

Mind that the companyInfo object is available for company applicants only.

Field	Type	Required	Description
`companyName`	String	Yes	The name of the company.
`registrationNumber`	String	Yes	A unique number assigned to the company when it was registered as a legal entity.
`country`	String	Yes	A three-letter code of the country where the company is legally registered (for example, `DEU`, `GBR`, and so on).
`legalAddress`	String	No	The address a legal entity uses to register with a legal authority.
`incorporatedOn`	String	No	The date of company incorporation (format `YYYY-mm-dd`, e.g. `2001-09-25`).
`type`	String	No	A type of legal entity. For example, private company limited by shares, public limited company, state-owned enterprise, and so on.
`email`	String	No	Company email address.
`phone`	String	No	Company phone number.
`controlScheme`	String	No	Description of the control scheme of the company or group of entities.
`taxId`	String	No	Taxpayer registration number/Code of taxpayer registration.
`registrationLocation`	String	No	A city, town, or another location where the company was registered.
`website`	String	No	Website URL of the company.
`postalAddress`	String	No	Company postal address.
`beneficiaries`	Array of objects	No	Contains `applicantId`s of beneficiaries and additional information such as position and type.
`addresses`	Array of objects	No	A list of available company addresses.

`beneficiaries` element fields

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

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

Field	Type	Required	Description
`applicantId`	String	Yes	Applicant identifier of the beneficiary.
`positions`	Array of strings	No	Positions in the company ([`director`, `shareholder`, `other`]) that the beneficiary is holding.
`type`	String	Yes	Type of beneficiary: `ubo` or `shareholder` or ‘director’ or `representative`.
`inRegistry`	Boolean	No	Matching to a Corporate registry. `true` — found in the registry. `false` — not found. `null` — unknown
`imageIds`	Array of strings	No	Image IDs represent a document uploaded. If `imageIds` array contains more than one element, the first one would be the front side and the others — back sides.
`applicant`	Object	No	Structure to create a new beneficiary.

`idDocs` element fields

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

Field	Type	Description
`idDocType`	String	The 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.
`country`	String	Alpha-3 code (for example, `DEU`, `GBR`, `ARG`, and so on) of the country where the document was issued.
`firstName`	String	Applicant first name in the original language as it is in the document.
`firstNameEn`	String	Automatic transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant middle name in the original language as it is in the document.
`middleNameEn`	String	Automatic transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant last name in the original language as it is in the document.
`lastNameEn`	String	Automatic transliteration of the applicant last name into Latin characters.
`issuedDate`	Date	The date when the identity document was issued (format `YYYY-MM-DD`).
`issueAuthorityCode`	String	The code of the Issuing Authority that is in charge of issuing the uploaded document.
`validUntil`	Date	The date when the document validity expires.
`number`	String	Unique registration number of the document.
`dob`	Date	Applicant date of birth (format `YYYY-mm-dd`, e.g. `2001-09-25`) as it is specified in the document.
`address`	Object	Includes the applicant address details.

`address` attributes and `addresses` element fields

The following table explains the address attributes and addresses element fields containing the applicant address details extracted from the documents or provided by the applicant.

Field	Name	Description
`country`	String	Alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`postCode`	String	Address postal code.
`town`	String	The city, town, or another settlement where the applicant lives and/or is registered.
`street`	String	The street where the applicant lives and/or is registered.
`subStreet`	String	Additional information related to the applicant street. This could be a house number or any other details.
`state`	String	The state, region, district, county or another territorial entity inside a country.

`fixedInfo` attributes

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

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

Field	Type	Description
`firstName`	String	Applicant first name in the original language.
`firstNameEn`	String	Automatic transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant middle name in the original language.
`middleNameEn`	String	Automatic transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant last name in the original language.
`lastNameEn`	String	Automatic transliteration of the applicant last name into Latin characters.
`legalName`	String	Legal name of the company the applicant is related to (UBO or shareholder). You can keep this information and use it for your personal navigation. Note that the `legalName` field is not checked and you might need it just in case.
`gender`	String	Applicant gender that can be male or female (`M` or `F`). If the gender is not specified in the applicant profile, this field is absent.
`dob`	Date	Applicant date of birth (format `YYYY-mm-dd`, e.g. `2001-09-25`).
`placeOfBirth`	String	Applicant place of birth. This can be a city, a town or another settlement type.
`country`	String	Applicant country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`nationality`	String	Applicant country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`addresses`	Array of objects	Includes data objects containing the applicant address details extracted from the PoA documents the applicant submitted.
`tin`	String	Taxpayer identification number that is unique to each taxpayer.

`agreement` attributes

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

Field	Type	Description
`createdAt`	Date	Date and time (GMT) when the applicant confirmed his/her consent to the submitting and processing of personal data.
`source`	String	Specifies the source from which the applicant confirmed the agreement (`WebSDK`, `MSDK`).

`requiredIdDocs` attributes

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

Field	Type	Description
`videoIdent`	Boolean	Specifies if the video identification is required (`true`) or not required (`false`) to pass verification.
`docSets`	Array of objects	Includes the objects representing specific document sets and their attributes.

`docSets` element fields

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

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

`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.
`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	The counting number of the current verification attempt on the same verification level.
`elapsedSincePendingMs`	Integer	Elapsed time since the applicant verification passed to the `pending` status.
`createDate`	Date	Date and time (UTC) when the applicant profile was created in the Sumsub system.
`reviewDate`	Date	Date and time (UTC) when the current applicant check was completed.
`reviewResult`	Object	Contains extra details of the applicant verification result.
`reviewStatus`	String	Indicates the applicant review status.

`reviewResult` attributes

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

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

`questionnaires` element fields

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

Field	Type	Description
`id`	String	Unique identifier of the questionnaire. You give this ID to the questionnaire when creating it.
`sections`	Object	Includes the objects each of those is a separate group of questions added to the questionnaire. A section object has a name representing the section title 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.
`items`	Object	Includes the objects each of those stands for a single question added to the questionnaire. An item object has a name representing the question. Each item has the `value` field which contains the applicant answer, and may have its own score assigned.
`score`	Integer	A score is a sort of rating that can be assigned to each item, each section, and a questionnaire as a whole. You can see the `score` element in the corresponding object it belongs to. When configuring a questionnaire, you have the option to set up risk scoring. It means you can add a value to each possible answer. When the applicant selects this answer, the assigned value is added to the score. 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.

`notes` element fields

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

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

`memberOf` element fields

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

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

Response examples

{
  "id": "5b594ade0a975a36c9349e66",
  "createdAt": "2020-06-24 05:05:14",
  "clientId": "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"
}

Get applicant data (externalUserId)

Overview

Example request

📘
Note

👍
Tip

Response explained

Root variables

`info` attributes

`companyInfo` attributes

`beneficiaries` element fields

`idDocs` element fields

`address` attributes and `addresses` element fields

`fixedInfo` attributes

`agreement` attributes

`requiredIdDocs` attributes

`docSets` element fields

`review` attributes

`reviewResult` attributes

`questionnaires` element fields

`notes` element fields

`memberOf` element fields

Response examples

Overview

Example request

📘Note

👍Tip

Response explained

Root variables

info attributes

companyInfo attributes

beneficiaries element fields

idDocs element fields

address attributes and addresses element fields

fixedInfo attributes

agreement attributes

requiredIdDocs attributes

docSets element fields

review attributes

reviewResult attributes

questionnaires element fields

notes element fields

memberOf element fields

Response examples

📘
Note

👍
Tip

`info` attributes

`companyInfo` attributes

`beneficiaries` element fields

`idDocs` element fields

`address` attributes and `addresses` element fields

`fixedInfo` attributes

`agreement` attributes

`requiredIdDocs` attributes

`docSets` element fields

`review` attributes

`reviewResult` attributes

`questionnaires` element fields

`notes` element fields

`memberOf` element fields