---
updatedAt: 2026-09-17T15:18:33.000Z
agentTools:
  projectIndex: https://docs.sumsub.com/llms.txt
---

# Check applicant existence by externalUserId

# Overview

Use this method to look up an applicant by your `externalUserId` and check whether the applicant exists under the calling client's license.

* If found, the `applicant` object containing the applicant's full view is returned along with the `exists` flag.
* If not found, the response is `{ "exists": false }`, and the `applicant` object is omitted.

<Callout icon="📘" theme="info">
  ### Note

  To retrieve full applicant data by `externalUserId`, use [this API method](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid).
</Callout>

## Required permissions

To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the **View applicants** [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions).

# Request example

```curl
curl -X GET \
     'https://api.sumsub.com/resources/applicants/-/byExternalUserId/your-external-user-id' \
     -H 'content-type: application/json' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>'
```

# Response explained

The response is a JSON object indicating whether an applicant with the specified `externalUserId` exists under the caller's license and, if so, includes the applicant's full view.

| Field       | Type                            | Description                                                                                                        |
| :---------- | :------------------------------ | :----------------------------------------------------------------------------------------------------------------- |
| `exists`    | Boolean                         | `true` when an applicant with the specified `externalUserId` exists under the caller's license; `false` otherwise. |
| `applicant` | [Object](#applicant-attributes) | The applicant view. Present only when `exists` is `true`.                                                          |

## `applicant` attributes

The applicant view. Present only when `exists` is `true`.

This endpoint returns only a subset of the attributes available in the `applicant` object returned by the standard [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) and [Get applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data) endpoints.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `id`
      </td>

      <td>
        String
      </td>

      <td>
        Unique applicant identifier in the Sumsub system (`applicantId`).<br /><br />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.
      </td>
    </tr>

    <tr>
      <td>
        `createdAt`
      </td>

      <td>
        String
      </td>

      <td>
        Date and time (GMT) when the applicant profile was created in the Sumsub system, in the format: `YYYY-MM-DD HH:MI:SS`.
      </td>
    </tr>

    <tr>
      <td>
        `externalUserId`
      </td>

      <td>
        String
      </td>

      <td>
        Unique applicant identifier as registered on your side.<br /><br />When [creating an applicant](https://docs.sumsub.com/sumsub/reference/create-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.<br /><br />For this endpoint, the value matches the `externalUserId` path parameter.
      </td>
    </tr>

    <tr>
      <td>
        `sourceKey`
      </td>

      <td>
        String
      </td>

      <td>
        [Source key](https://docs.sumsub.com/sumsub/docs/source-keys) that helps you group clients that send applicants.
      </td>
    </tr>

    <tr>
      <td>
        `clientId`
      </td>

      <td>
        String
      </td>

      <td>
        Unique identifier of you as our client in the Sumsub system.<br /><br />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.
      </td>
    </tr>

    <tr>
      <td>
        `applicantPlatform`
      </td>

      <td>
        String
      </td>

      <td>
        The platform from which the applicant registered in the system and/or provided profile data (`API`, `Web`, `Android`, `iOS`).
      </td>
    </tr>

    <tr>
      <td>
        `requiredIdDocs`
      </td>

      <td>
        [Object](#requirediddocs-attributes)
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `deleted`
      </td>

      <td>
        Boolean
      </td>

      <td>
        Indicates whether the applicant profile has has a [deactivation](https://docs.sumsub.com/sumsub/reference/deactivate-applicant-profile) history.

        - `true` — applicant profile is currently deactivated.
        - `false` — applicant profile was previously deactivated but has since been reactivated.
        - omitted — profile has never been deactivated.
      </td>
    </tr>

    <tr>
      <td>
        `type`
      </td>

      <td>
        String
      </td>

      <td>
        Defines the [applicant type](https://docs.sumsub.com/sumsub/docs/applicants). 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.
      </td>
    </tr>

    <tr>
      <td>
        `tags`
      </td>

      <td>
        Array of String
      </td>

      <td>
        Contains [tags](https://docs.sumsub.com/sumsub/docs/review-results-in-applicant-profile#assign-tags) that you have created and then assigned to the applicant. Omitted when empty.
      </td>
    </tr>

    <tr>
      <td>
        `review`
      </td>

      <td>
        [Object](#review-attributes)
      </td>

      <td>
        Explains the details of the current applicant verification status and check result.
      </td>
    </tr>

    <tr>
      <td>
        `info`
      </td>

      <td>
        [Object](#info-and-fixedinfo-attributes)
      </td>

      <td>
        General applicant information recognized from the documents that Sumsub cross-validates with the applicant data provided (`fixedInfo`).<br /><br />Note that `info` and `fixedInfo` objects have the same attributes.
      </td>
    </tr>

    <tr>
      <td>
        `fixedInfo`
      </td>

      <td>
        [Object](#info-and-fixedinfo-attributes)
      </td>

      <td>
        General applicant information that is submitted by the applicant via the [Web](https://docs.sumsub.com/sumsub/docs/web-sdk) or [Mobile](https://docs.sumsub.com/sumsub/docs/mobile-sdk) SDK or by you via [this API method](https://docs.sumsub.com/sumsub/reference/create-applicants). Sumsub should not change this information, but uses it to cross-validate with the data recognized from the applicant documents (`info`).<br /><br />Note that `info` and `fixedInfo` objects have the same attributes.
      </td>
    </tr>

    <tr>
      <td>
        `riskLabels`
      </td>

      <td>
        Object
      </td>

      <td>
        Contains information on the [applicant risk labels](https://docs.sumsub.com/sumsub/docs/applicant-risk-labels).
      </td>
    </tr>

    <tr>
      <td>
        `assessment`
      </td>

      <td>
        [Object](#assessment-attributes)
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `memberOf`
      </td>

      <td>
        [Array of objects](#memberof-element-fields)
      </td>

      <td>
        Includes data objects with the applicant companies' IDs the beneficiary of which the applicant is and which are registered in the Sumsub system. Omitted when empty.
      </td>
    </tr>
  </tbody>
</Table>

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

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "`videoIdent`",
    "0-1": "Boolean",
    "0-2": "Specifies if the video identification is required (`true`) or not required (`false`) to pass verification.",
    "1-0": "`videoIdentSettings`",
    "1-1": "Object",
    "1-2": "<p>Contains the <code>resetAllStepsOnEachAttempt</code> boolean field that indicates whether each new <a href=\"doc:video-identification\">video identification</a> resubmission must start from the beginning with all required steps defined for the verification level, regardless of which steps were previously completed successfully.</p><ul><li>If enabled (<code>true</code>) — the applicant must repeat all verification steps on every new attempt from the beginning.</li><li>If disabled (<code>false</code>) — only incomplete or failed steps must be repeated.</li></ul><p>⚠️ This field is available only if the setting is configured for the level.</p>",
    "2-0": "`videoIdentUploadTypes`",
    "2-1": "Array of strings",
    "2-2": "Lists the document types that can be uploaded during a video interview, if such documents are specified in the level settings.  \n  \nThe field is available if the video identification is required on the level.",
    "3-0": "`stepsOutsideVideoId`",
    "3-1": "Array of strings",
    "3-2": "Lists the verification steps that can be passed outside the video identification.  \n  \nThe field is available if the video identification is required on the level.",
    "4-0": "`includedCountries`",
    "4-1": "Array of strings",
    "4-2": "Countries (in ISO 3166-1 alpha-3 country code, for example, `DEU`, `GBR`, `ARG`) that are included in the list of supported.",
    "5-0": "`excludedCountries`",
    "5-1": "Array of strings",
    "5-2": "Countries (in ISO 3166-1 alpha-3 country code, for example, `DEU`, `GBR`, `ARG`) that are excluded from the list of supported.",
    "6-0": "`docSets`",
    "6-1": "[Array of objects](#docsets-element-fields)",
    "6-2": "Includes the objects representing specific document sets and their attributes.",
    "7-0": "`kybSettings`",
    "7-1": "[Object](#kybsettings-attributes)",
    "7-2": "<p>Available for company applicants.</p><p>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.</p>"
  },
  "cols": 3,
  "rows": 8,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

## `docSets` element fields

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

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "`idDocSetType`",
    "0-1": "String",
    "0-2": "A human-readable [identifier of the document set type](https://docs.sumsub.com/sumsub/reference/iddocsettypes) (for example, `IDENTITY`, `SELFIE`, `PROOF_OF_RESIDENCE`).",
    "1-0": "`types`",
    "1-1": "Array of strings",
    "1-2": "Includes the [types of documents](https://docs.sumsub.com/sumsub/reference/add-verification-documents#supported-document-types) that are required for a particular `idDocSetType` to pass verification.",
    "2-0": "`subTypes`",
    "2-1": "Array of strings",
    "2-2": "List of [document subtypes](https://docs.sumsub.com/sumsub/reference/add-verification-documents#supported-iddocsubtypes-for-company_doc) required for verification (applicable only to company documents).",
    "3-0": "`videoRequired`",
    "3-1": "String",
    "3-2": "Method of passing the document upload step that can be set up when [configuring a verification level](/docs/get-started-with-verification-level#configure-required-steps).<ul><li><code>disabled</code> — selfie with a document.</li><li><code>enabled</code> — video selfie with a phrase.</li><li><code>photoRequired</code> — web camera photo (still face image).</li><li><code>passiveLiveness</code> — <a href=\"/docs/liveness\">liveness check</a>.</li><li><code>docapture</code> — enables the camera for the steps with ID documents, so applicants can take pictures of their documents in real time.</li></ul>",
    "4-0": "`captureMode`",
    "4-1": "String",
    "4-2": "<p>Applicable only when <code>videoRequired=docapture</code>.</p><ul><li><code>manualAndAuto</code> — 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.</li><li><code>manualOnly</code> — allows only manually hitting a button to take a photo.</li><li><code>seamless</code> — Seamless ID Capture mode for <a href=\"doc:qualified-electronic-signature-qes-verification#qes-verification-faq\">QES</a>.</li></ul>",
    "5-0": "`uploaderMode`",
    "5-1": "String",
    "5-2": "<p>Applicable only when <code>videoRequired=docapture</code>.</p><ul><li><code>always</code> — always allows uploading a ready-made photo instead of using a camera.</li><li><code>never</code> — does not allow uploading a ready-made photo.</li><li><code>fallback</code> — allows uploading a ready-made photo only if a camera is not available.</li></ul>",
    "6-0": "`fields`",
    "6-1": "[Array of objects](#fields-element-fields)",
    "6-2": "Contains objects that define the document data fields to be populated with personal information for verifying the applicant during the **Applicant data** verification step.",
    "7-0": "`customFields`",
    "7-1": "[Array of objects](#customfields-element-fields)",
    "7-2": "Contains objects that describe custom fields if they are created for the **Applicant data** verification step.",
    "8-0": "`questionnaireDefId`",
    "8-1": "String",
    "8-2": "Identifier of the questionnaire that is added to the verification level and is to be or has already been filled by the applicant.",
    "9-0": "`questionnaireProcessingSettings`",
    "9-1": "Object",
    "9-2": "Contains configuration parameters for the `QUESTIONNAIRE` step that modify how previously submitted questionnaire answers are handled.",
    "10-0": "`skipIfFilled`",
    "10-1": "Boolean",
    "10-2": "Defines whether the `QUESTIONNAIRE` step should be automatically accepted (`true`) or not (`false`) if the applicant has previously completed the same questionnaire.",
    "11-0": "`poaStepSettingsId`",
    "11-1": "String",
    "11-2": "Identifier of the selected [Proof of Address preset](https://docs.sumsub.com/sumsub/docs/customize-supported-address-documents#create-poa-preset).",
    "12-0": "`companyBeneficiaryDefinitions`",
    "12-1": "[Array of objects](#companybeneficiarydefinitions-element-fields)",
    "12-2": "Specification of level steps to be fulfilled. Stands for **Associated parties**.  \n  \nAvailable for company applicants.",
    "13-0": "`companyDocsGroupDefinitions`",
    "13-1": "[Array of objects](#companydocsgroupdefinitions-element-fields)",
    "13-2": "Definitions of the required document groups for verification.  \n  \nAvailable for company applicants.",
    "14-0": "`captureParams`",
    "14-1": "Object",
    "14-2": "<p>Describes the capture method and related settings for this step.</p><p>Contains the <code>inputType</code> enum attribute, which defines how data is captured. Possible values:</p><ul><li><code>fileUpload</code> — upload a file.</li><li><code>cameraStream</code> — capture a web camera photo or a short video fragment.</li><li><code>liveness</code> — perform an advanced liveness check.</li><li><code>docapture</code> — perform live document capture.</li></ul><p>If <code>inputType=cameraStream</code>, the <code>cameraStream.contentType</code> field is returned:</p><ul><li><code>image</code> — for web camera photo</li><li><code>video</code> — for short video fragment.</li></ul><p>If <code>inputType=docapture</code>, the <code>docapture.captureMode</code> and <code>docapture.uploaderMode</code> fields are returned.</p>",
    "15-0": "`ekycAllowed`",
    "15-1": "Boolean",
    "15-2": "Indicates if [Non-Doc Verification](https://docs.sumsub.com/sumsub/docs/no-document-verification) for the step is allowed (`true`) or not (`false`).",
    "16-0": "`checkSourceSettings`",
    "16-1": "Object",
    "16-2": "Describes the configuration of the [Database Validation](https://docs.sumsub.com/sumsub/docs/database-validation) setting for the verification level.",
    "17-0": "`esignSettings`",
    "17-1": "Object",
    "17-2": "Contains configuration for the [E-sign verification step](https://docs.sumsub.com/sumsub/docs/qualified-electronic-signature-qes-verification), including objects that define the document to be signed (ID and name) and signature settings.",
    "18-0": "`restrictCountries`",
    "18-1": "Boolean",
    "18-2": "Returns `true` if the verification step [restricts applicants from specific countries](https://docs.sumsub.com/sumsub/docs/configure-verification-levels#location-settings). Otherwise the field is not returned.",
    "19-0": "`skipAllowed`",
    "19-1": "Boolean",
    "19-2": "Indicates whether this verification step can be skipped (`true`) or not (`false`).  \n  \nAvailable only for steps that support the skip option.",
    "20-0": "`nfcVerificationSettings`",
    "20-1": "Object",
    "20-2": "<p>Contains the <code>mode</code> parameter that defines <a href=\"doc:nfc-based-id-verification\">NFC-based ID verification</a> behavior. Possible values:\n</p><ul><li><code>disabled</code> — NFC chip reading is not requested from applicants.</li><li><code>optional</code> — if the document contains an NFC chip, the system requests a chip reading. Applicants may complete or skip this step. If skipped or if scanning fails, verification continues using the standard document-based flow.</li><li><code>required</code> — if the document contains an NFC chip, the system requires a successful chip reading. Skipping or fallback to document-based verification is not allowed.</li></ul>",
    "21-0": "`phoneVerificationSettings`",
    "21-1": "Object",
    "21-2": "<p>Contains the <code>immutablePhoneIfPresent</code> boolean field, which controls whether applicants can edit their pre-filled phone number.</p><ul><li><code>true</code> — editing is disabled.</li><li><code>false</code> — editing is allowed.</li><li><b>not returned</b> — editing is allowed, or the setting is not supported for the verification step.</li></ul>",
    "22-0": "`emailVerificationSettings`",
    "22-1": "Object",
    "22-2": "<p>Contains the <code>immutableEmailIfPresent</code> boolean field, which controls whether applicants can edit their pre-filled email address.</p><ul><li><code>true</code> — editing is disabled.</li><li><code>false</code> — editing is allowed.</li><li><b>not returned</b> — editing is allowed, or the setting is not supported for the verification step.</li></ul>",
    "23-0": "`selfieProcessingSettings`",
    "23-1": "Object",
    "23-2": "<p>Contains the <code>skipLivenessCheck</code> boolean field, which indicates whether the <b>Skip liveness check</b> setting is enabled.</p><ul><li><code>true</code> — enabled.</li><li><code>false</code> — disabled.</li><li><b>not returned</b> — disabled, or the setting is not supported for the verification step.</li></ul>",
    "24-0": "`applicantDataSettings`",
    "24-1": "Object",
    "24-2": "<p>Contains the <code>prefill</code> boolean field, which indicates whether the applicant data form is prefilled in the SDK step.</p><ul><li><code>true</code> — pre-fill is enabled.</li><li><code>false</code> — pre-fill is disabled.</li><li><b>not returned</b> — pre-fill is disabled, or the setting is not supported for the verification step.</li></ul>"
  },
  "cols": 3,
  "rows": 25,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

## `fields` element fields

The 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

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](#individual-and-company-attributes) | Contains information on the associated party as an individual applicant. |
| `company`    | [Object](#individual-and-company-attributes) | Contains information on the associated party as a company applicant.     |

## `individual` and `company` attributes

the 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](#fields-element-fields)       | Includes the objects describing the data fields that should be filled with personal information to verify the applicant.                          |
| `customFields` | [Array of objects](#customfields-element-fields) | Includes the objects each of those represents an additional custom field (`applicantIdDocSetCustomField`) that should be filled for verification. |

## `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](https://docs.sumsub.com/sumsub/reference/add-verification-documents#supported-iddocsubtypes-for-company_doc) included into the verification group.                                                    |
| `required` | Boolean          | Indicates if this is required (`true`) or optional (`false`).                                                                                                                             |

## `kybSettings` attributes

The following table explains the `kybSettings` attributes.

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "`shareholderThreshold`",
    "0-1": "Integer",
    "0-2": "Ownership percentage threshold used to classify an individual beneficiary as a shareholder.  \n  \nIf `shareholderThreshold` is less and `uboThreshold` is greater than the ownership percentage, then the individual is a shareholder.  \n  \nCompanies are always classified as shareholders.",
    "1-0": "`uboThreshold`",
    "1-1": "Integer",
    "1-2": "Ownership percentage threshold used to classify an individual beneficiary as a UBO (Ultimate Beneficial Owner).  \n  \nIf the ownership percentage is greater than or equal to `uboThreshold`, then the individual is a UBO.  \n  \nCompanies are always classified as shareholders.",
    "2-0": "`disableCompanySearchAndPrefill`",
    "2-1": "Boolean",
    "2-2": "Indicates whether company search in selected corporate registry databases for pre-filling company and associated parties’ data is disabled (`true`) or enabled (`false`).",
    "3-0": "`enableBeneficiariesAutoCheck`",
    "3-1": "Boolean",
    "3-2": "<p>Indicates whether automatic verification of the company’s ownership and control structure against selected corporate registries is enabled.</p><ul><li>When enabled (<code>true</code>), the system compares the applicant-provided ownership and management information (for example, shareholders and directors) with official registry data and flags discrepancies.</li><li>When disabled (<code>false</code>), this verification is not performed.</li></ul>"
  },
  "cols": 3,
  "rows": 4,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

## `review` attributes

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

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "`reviewId`",
    "0-1": "String",
    "0-2": "Unique identifier of the applicant profile review in the Sumsub system.",
    "1-0": "`levelName`",
    "1-1": "String",
    "1-2": "Name of the [verification level](/docs/verification-levels) the applicant has to go through. There is no length limit for this field.",
    "2-0": "`attemptId`",
    "2-1": "String",
    "2-2": "Unique identifier of the current verification attempt.  \n  \nApplicants 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.",
    "3-0": "`attemptCnt`",
    "3-1": "Integer",
    "3-2": "Counting number of the current verification attempt on the same verification level.",
    "4-0": "`elapsedSincePendingMs`",
    "4-1": "Long",
    "4-2": "Elapsed time since the applicant verification passed to the `pending` status.",
    "5-0": "`createDate`",
    "5-1": "Date",
    "5-2": "Date and time (UTC) when the applicant profile was created in the Sumsub system.",
    "6-0": "`reviewDate`",
    "6-1": "Date",
    "6-2": "Date and time (UTC) when the current applicant check was completed.",
    "7-0": "`reviewResult`",
    "7-1": "[Object](#reviewresult-attributes)",
    "7-2": "Contains extra details of the applicant verification result.",
    "8-0": "`reviewStatus`",
    "8-1": "String",
    "8-2": "Indicates the applicant [review status](/reference/get-applicant-review-status#possible-review-statuses)."
  },
  "cols": 3,
  "rows": 9,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

## `reviewResult` attributes

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

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "`reviewAnswer`",
    "0-1": "String",
    "0-2": "Explains the review result. <ul><li><code>GREEN</code> — the applicant is approved.</li><li><code>RED</code> — the applicant is declined.</li></ul>",
    "1-0": "`rejectLabels`",
    "1-1": "Array of strings",
    "1-2": "Includes one or more reasons for rejection. The field is available if `reviewAnswer` returns `RED`.  \n  \nFor more information, see [Resubmission requested](https://docs.sumsub.com/sumsub/reference/resubmission-requested)  and [Rejected](https://docs.sumsub.com/sumsub/reference/rejected) .",
    "2-0": "`reviewRejectType`",
    "2-1": "String",
    "2-2": "Indicates the type of rejection. <ul><li><code>FINAL</code> — <b>Rejected</b> 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.</li><li><code>RETRY</code> — <b>Resubmission requested</b> 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.</li></ul>  \nFor more information, see [Resubmission requested](https://docs.sumsub.com/sumsub/reference/resubmission-requested)   and [Rejected](https://docs.sumsub.com/sumsub/reference/rejected)  .",
    "3-0": "`clientComment`",
    "3-1": "String",
    "3-2": "Human-readable comment that explains the reasons for rejection in detail, and that must not be shown to the applicant.",
    "4-0": "`moderationComment`",
    "4-1": "String",
    "4-2": "Human-readable comment that explains the reasons for rejection in detail, and that can be shown to the applicant.",
    "5-0": "`buttonIds`",
    "5-1": "Array of strings",
    "5-2": "Button identifiers that have been used for applicant rejection.  \n  \nA specific `buttonId` is automatically assigned to each rejection type. For more information, see [Resubmission requested](https://docs.sumsub.com/sumsub/reference/resubmission-requested)   and [Rejected](https://docs.sumsub.com/sumsub/reference/rejected)  ."
  },
  "cols": 3,
  "rows": 6,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

## `info` and `fixedInfo` attributes

This endpoint returns only a subset of the attributes available in the `info` and `fixedInfo` objects returned by the standard [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) and [Get applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data) endpoints.

| Field          | Type                                       | Description                                                                                                                                                                           |
| :------------- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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.                                                                  |
| `country`      | String                                     | Country that issued the applicant's document. Presented as an [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code (for example, `DEU`, `GBR`, `ARG`). |
| `dob`          | String                                     | Applicant date of birth ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format `yyyy-MM-dd`, for example, `2001-09-25`).                                                          |
| `idDocs`       | [Array of objects](#iddocs-element-fields) | Contains data objects with information extracted from the applicant's documents. This information can be useful after verification has been completed.                                |
| `companyInfo`  | [Object](#companyinfo-attributes)          | Contains general company information, such as the company name and location.                                                                                                          |

## `idDocs` element fields

This endpoint returns only a subset of the element fields available in the `idDocs` array returned by the standard [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) and [Get applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data) endpoints.

| 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.<br /><br />See the lists of [supported document types](https://docs.sumsub.com/sumsub/reference/add-verification-documents#supported-document-types) and [supported company document types](https://docs.sumsub.com/sumsub/reference/add-verification-documents#supported-company-document-types) for details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `idDocSubType` | String | <p>Specifies the document subtype as a full type identifier (for example, cyp.rp.type1, nga.nins.type2, and so on). The identifier typically follows this structure:</p><ol><li>Alpha-3 country code (`deu`, `gbr`, `arg`, and so on).</li><li>Document type, (for example, ID card `id`, driving license `drvlic`, residence permit `rp`, and so on).</li><li>Subtype category (for example, `type1`, `type2`, `type3`) – often used to determine different varieties of the document type.</li></ol><p>Additional variations may be the following:</p><ul><li>State-level identifiers for supported countries (for example, `usa.drvlic.al.type2`, `can.drvlic.on.type1`).</li><li>Unique document identifiers when supported (for example, `sgp.work.type1`, `gbr.drvlic.provisional.type1`, `ind.aadhaar.type1`).</li></ul><p>If the subtype cannot be determined, the field is returned empty.</p><p>⚠️ <strong>Note:</strong> 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.</p> |
| `country`      | String | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code (for example, `DEU`, `GBR`, `ARG`) of the country where the document was issued.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## `companyInfo` attributes

This endpoint returns only a subset of the attributes available in the `companyInfo` object returned by the standard [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) and [Get applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data) endpoints.

| Field              | Type            | Description                                                                                                                                                                 |
| :----------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyName`      | String          | The name of the company. There is no length limit for this field.                                                                                                           |
| `country`          | String          | [ISO 3166-1 alpha-3 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the country where the company is legally registered (for example, `DEU`, `GBR`).             |
| `alternativeNames` | Array of String | 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". |

## `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](#scores-element-fields) | 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](#rules-element-fields) | 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. |

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

If the applicant exists, you will get a response like the following:

```json
{
  "exists": true,
  "applicant": {
    "id": "5b594ade0a975a36c9349e66",
    "createdAt": "2020-06-24 05:05:14",
    "externalUserId": "SomeExternalUserId",
    "sourceKey": "partner-portal",
    "clientId": "your_cool_id",
    "applicantPlatform": "Android",
    "requiredIdDocs": {
      "docSets": [
        {
          "idDocSetType": "IDENTITY",
          "types": ["PASSPORT", "ID_CARD"]
        },
        {
          "idDocSetType": "SELFIE",
          "types": ["SELFIE"]
        }
      ]
    },
    "deleted": false,
    "type": "individual",
    "tags": ["vip", "manual-review"],
    "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"
    },
    "info": {
      "firstName": "DANIEL",
      "firstNameEn": "DANIEL",
      "lastName": "BROOKS",
      "lastNameEn": "BROOKS",
      "dob": "1989-07-16",
      "country": "DEU",
      "idDocs": [
        {
          "idDocType": "ID_CARD",
          "country": "DEU"
        }
      ]
    },
    "fixedInfo": {
      "firstName": "Daniel",
      "lastName": "Brooks",
      "dob": "1989-07-16"
    },
    "assessment": {
      "totalScore": 12.5
    },
    "memberOf": [
      {
        "applicantId": "63f9b1a20a975a36c9349e70",
        "fullName": "The Megacorp ABC Inc.",
        "inactive": false
      }
    ]
  }
}
```

If no applicant matches the specified `externalUserId` under the caller's license:

```json
{
  "exists": false
}
```

If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:

```json
{
  "code": 401,
  "description": "Unauthorized",
  "correlationId": "0d3457fdac54803edf23c90000000000"
}
```

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "sumsub-api",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.sumsub.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "X-App-Token",
        "in": "header",
        "x-default": ""
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/resources/applicants/-/byExternalUserId/{externalUserId}": {
      "get": {
        "responses": {
          "200": {
            "description": ""
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "externalUserId",
            "schema": {
              "type": "string"
            },
            "required": true,
            "description": "Unique identifier of the applicant on your side. Must be non-null.\n\n⚠️ If `externalUserId` is missing or violates the `@NotNull` constraint, the request returns HTTP 400 with the standard error envelope."
          }
        ],
        "summary": "Check applicant existence by externalUserId",
        "operationId": "get_resources-applicants-byexternaluserid-externaluserid"
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```