---
updatedAt: 2026-10-16T09:56:15.000Z
agentTools:
  projectIndex: https://docs.sumsub.com/llms.txt
---

# Link beneficiary to company

# Table of contents

* [Overview](#overview)
* [Required permissions](#required-permissions)
  * [Link existing applicant as beneficiary](#link-existing-applicant-as-beneficiary)
  * [Link non-existent applicant as beneficiary](#link-non-existent-applicant-as-beneficiary)
  * [Available values for \`types\` array](#available-values-for-types-array)
  * [Available values for \`subtypes\` array](#available-values-for-subtypes-array)
* [Response explained](#response-explained)
  * [Root variables](#root-variables)
  * [beneficiaryInfo attributes](#beneficiaryinfo-attributes)
  * [Response examples](#response-examples)

# Overview

Use this method to link a beneficiary to the control and ownership structure of a company, provided the company applicant relates to the **KYB** flow. You can add both an individual and a company applicant as a beneficiary.

Building a request may vary, depending on whether the [beneficiary already exists](#link-existing-applicant-as-beneficiary) as an applicant in the Sumsub system or the [beneficiary is not yet registered](#link-non-existent-applicant-as-beneficiary) and has no applicant profile created. See the description of cases and request examples below.

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

  The method updates the information on the beneficiary in the `fixedInfo` structure (**Provided info**).
</Callout>

# Required permissions

To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the **Change applicant's personal data** [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions).

## Link existing applicant as beneficiary

When you link a beneficiary that already exists in the Sumsub system as an applicant:

* `applicantId` and [`types`](#available-values-for-types-array) are mandatory to send.
* `beneficiaryInfo` must be excluded from the request.

### Request example

```curl
curl -X POST \
     'https://api.sumsub.com/resources/applicants/63e2428232f67079df8dc000/fixedInfo/companyInfo/beneficiaries' \
     -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>' \
     -d '{
            "applicantId": "63620c095cc65d0001ffc000",		  
            "types": [
              "shareholder"
            ],
            "shareSize": 42.52
          }'
```

## Link non-existent applicant as beneficiary

When you link a beneficiary that is not yet registered in the Sumsub system as an applicant and does not have an existing profile:

* [`types`](#available-values-for-types-array) and `beneficiaryInfo` are mandatory to send.
* `applicantId` must be excluded from the request.

If a verification step has a set level for either of the submitted beneficiary roles (`types`), the applicant profile will be created and linked to the specified company applicant. In case the verification level is disabled for roles, the submitted data will be added to the company applicant profile without creating a nested applicant.

### Request examples

```curl Link an individual
curl -X POST \
     'https://api.sumsub.com/resources/applicants/63e2428232f67079df8dc000/fixedInfo/companyInfo/beneficiaries' \
     -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>' \
     -d '{
            "beneficiaryInfo": {
              "firstName": "John",
              "lastName": "Reese",
              "countryOfBirth": "GBR",
              "placeOfBirth": "London"
            },
            "types": [
              "shareholder"
            ],
            "shareSize": 42.52
          }'
```
```curl Link a company
curl -X POST \
     'https://api.sumsub.com/resources/applicants/63e2428232f67079df8dc591/fixedInfo/companyInfo/beneficiaries' \
     -H 'X-App-Token: <token>' \
     -H 'X-App-Access-Sig: <sig>' \
     -H 'X-App-Access-Ts: <ts>' \
     -H 'Content-Type: application/json' \
     -d '{
            "beneficiaryInfo": {
              "companyName": "Acme Holdings Ltd",
              "registrationNumber": "12345678",
              "legalForm": "privateLimitedCompany"
            },
            "types": [
              "shareholder"
            ]
          }'
```

## Available values for `types` array

The following table describes the available types array values, which represent beneficiary roles in the new data structure, where a single entity can have multiple roles.

| Value                 | Role description                                                                                                                                                        |
| :-------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubo`                 | Ultimate beneficial owner of the company.                                                                                                                               |
| `shareholder`         | Owns shares in the company stock.                                                                                                                                       |
| `representative`      | Authorized to act or speak for or in support of the company.                                                                                                            |
| `director`            | Appointed to manage the company business and affairs.                                                                                                                   |
| `companyOfficer`      | Holds an executive position within the company (for example, CEO, CFO, COO).<br /><br />⚠️ Not verifiable by Sumsub, for your internal use only.                        |
| `investor`            | Provides capital to the company without necessarily holding controlling shares.<br /><br />⚠️ Not verifiable by Sumsub, for your internal use only.                     |
| `secretary`           | Responsible for administrative tasks and regulatory compliance of the company.                                                                                          |
| `founder`             | Established the company or contributed to its initial creation.                                                                                                         |
| `legalAdvisor`        | Professionally provides legal counsel or representation for the company.                                                                                                |
| `authorizedSignatory` | Officially authorized to sign documents and contracts on behalf of the company.                                                                                         |
| `trustee`             | Holds assets in a trust for the benefit of beneficiaries. Should be used exclusively for Trust flows.                                                                   |
| `trustBeneficiary`    | Entitled to benefit from assets held in a trust. Should be used exclusively for Trust flows.                                                                            |
| `trustSettlor`        | Creates a trust and transfers assets into it. Should be used exclusively for Trust flows.                                                                               |
| `trustProtector`      | Appointed to oversee the administration of a trust to safeguard the interests of beneficiaries. Should be used exclusively for Trust flows.                             |
| `managingPartner`     | Exercises management or decision-making authority over the partnership (for example, General Partner or Designated Partner).                                            |
| `equityPartner`       | Holds an interest in the partnership, including rights to its profits, assets, or capital (for example, Limited Partner, Member, or Partner).                           |
| `fundInvestor`        | Holds an ownership, investment, economic, or equivalent interest in the fund.                                                                                           |
| `fundManager`         | Exercises management or decision-making authority over the fund.                                                                                                        |
| `investmentManager`   | Manages the fund's investments or portfolio in accordance with the fund's investment strategy and applicable mandate, with authority to make investment decisions.      |
| `investmentAdviser`   | Provides investment advice or recommendations concerning the fund's investments or portfolio, and may have authority to make investment decisions on the fund's behalf. |
| `fundAdministrator`   | Performs administrative and operational functions for the fund, including maintaining fund records and supporting accounting, reporting, and investor servicing.        |
| `depositary`          | Oversees the safekeeping and custody of the fund's assets and performs the oversight functions required under the applicable regulatory framework. Company only.        |
| `custodian`           | Provides custody and safekeeping services for the fund's assets. Company only.                                                                                          |
| `primeBroker`         | Provides brokerage, financing, custody, and related services to the fund, typically in connection with its investment activities. Company only.                         |
| `accountUser`         | Is granted access to the account to be opened.                                                                                                                          |

## Available values for `subtypes` array

When `types` includes `ubo`, use `subtypes` to specify the exact basis on which the beneficiary qualifies as an ultimate beneficial owner. One beneficiary may have multiple subtypes.

| Value           | Description                                                                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownershipUbo`  | Individual with direct or indirect ownership above the threshold.<br /><br />Shown in the Dashboard as **Ownership UBO**. Use together with `shareSize` to report the ownership percentage.       |
| `controlUbo`    | Controls the company by voting rights, rather than through ownership.<br /><br />Shown in the Dashboard as **Control UBO**. Requires `natureOfControl` to describe how that control is exercised. |
| `substituteUbo` | Substitute (Senior Managing Official) UBO, designated when no natural person qualifies as an ownership or control UBO.<br /><br />Shown in the Dashboard as **Substitute UBO**.                   |

## Available values for `legalForm`

The following values are accepted for the `legalForm` field. Any other value is rejected.

| Value                            | Legal form                        |
| :------------------------------- | --------------------------------- |
| `privateLimitedCompany`          | Private Limited Company.          |
| `closedStockCorporation`         | Closed Stock Corporation.         |
| `cooperativeCompany`             | Cooperative Company.              |
| `jointStockCompany`              | Joint Stock Company.              |
| `openStockCorporation`           | Open Stock Corporation.           |
| `publicLimitedCompany`           | Public Limited Company.           |
| `unregisteredSoleProprietorship` | Unregistered Sole Proprietorship. |
| `registeredSoleProprietorship`   | Registered Sole Proprietorship.   |
| `selfEmployedProfessional`       | Self-Employed Professional.       |
| `generalPartnership`             | General Partnership.              |
| `limitedPartnership`             | Limited Partnership.              |
| `consortiumPartnership`          | Consortium Partnership.           |
| `jointVenture`                   | Joint Venture.                    |
| `trust`                          | Trust.                            |
| `investmentFund`                 | Investment Fund.                  |
| `communityInterestCompany`       | Community Interest Company.       |
| `friendlySociety`                | Friendly Society.                 |
| `foundation`                     | Foundation.                       |
| `association`                    | Association.                      |
| `charity`                        | Charity.                          |
| `stateOwnedEnterprise`           | State-Owned Enterprise.           |
| `publicInstitutionOrAgency`      | Public Institution or Agency.     |
| `nationalGovernmentDepartment`   | National Government Department.   |
| `localGovernmentDepartment`      | Local Government Department.      |

# Response explained

The response is a JSON file that represents augmented and structured information on the linked applicant.

## Root variables

The following table explains the core data elements of the response.

| Field             | Type                                  | Description                                                                                                                                                                                                                                                                                                                                             |
| :---------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | String                                | Beneficiary identifier that is autogenerated for all KYB beneficiaries when they are added to the company structure.                                                                                                                                                                                                                                    |
| `applicantId`     | String                                | Unique applicant identifier of the beneficiary in the Sumsub system.<br />This field is available if the applicant profile already existed or was created as a result of calling this endpoint.                                                                                                                                                         |
| `applicant`       | Object                                | Represents structured information about the applicant profile of the linked beneficiary. Refer to the [following page](https://docs.sumsub.com/sumsub/reference/get-applicant-data#root-variables) for detailed description of the attributes and element fields.<br />This field is available if the applicant profile already existed or was created as a result of calling this endpoint. |
| `shareSize`       | Double                                | Percentage of ownership if the beneficiary is a shareholder of the company. Also used to report the ownership percentage when `subtypes` includes `ownershipUbo`.                                                                                                                                                                                       |
| `types`           | Array of strings                      | List of beneficiary roles for the new data structure, when one entity may have multiple roles.<br /><br />See [Available values for `types` array](#available-values-for-types-array).                                                                                                                                                                  |
| `subtypes`        | Array of strings                      | When `types` includes `ubo`, specifies the basis on which the beneficiary qualifies as a UBO.<br /><br />Possible values: `ownershipUbo`, `controlUbo`, `substituteUbo`.<br /><br />See [Available values for `subtypes` array](#available-values-for-subtypes-array).                                                                                  |
| `natureOfControl` | String                                | Free-text description of how the beneficiary exercises control over the company (for example, via voting rights, a contractual arrangement, or another mechanism).<br /><br />Present and required when `subtypes` includes `controlUbo`. Maximum 255 characters.                                                                                       |
| `beneficiaryInfo` | [Object](#beneficiaryinfo-attributes) | Structure that contains the beneficiary data.<br />When adding a new applicant as a beneficiary, the object would include the data that was submitted in the request. When linking an existing applicant, the object would include the data taken from the associated applicant profile.                                                                |

## `beneficiaryInfo` attributes

The following table explains the `beneficiaryInfo` attributes. The existence of some fields depends on whether they were submitted in the request or present in the associated applicant profile.

| Field                  | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| :--------------------- | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                | String           | Email address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `phone`                | String           | Phone number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `firstName`            | String           | First name of the beneficiary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `lastName`             | String           | Last name of the beneficiary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `middleName`           | String           | Middle name of the beneficiary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `dob`                  | Date             | Date of birth. Format `YYYY-mm-dd`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `countryOfBirth`       | String           | Country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `stateOfBirth`         | String           | State, region, district, county or another territorial entity of birth inside a country, if applicable.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `placeOfBirth`         | String           | Place of birth. This can be a city, a town or another settlement type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `legalName`            | String           | Legal name of the company the beneficiary is related to (UBO or shareholder). You can keep this information and use it for your personal navigation.<br />Note that the `legalName` field is not checked and you might need it just in case.                                                                                                                                                                                                                                                                                                        |
| `gender`               | String           | Beneficiary gender (`M` or `F`). If the gender was not specified in the applicant profile, this field will not be present.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `nationality`          | String           | Country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `country`              | String           | Beneficiary country. This is usually a country of the last uploaded ID document, and it may differ from the country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).                                                                                                                                                                                                                                                                                                                                   |
| `tin`                  | String           | Taxpayer identification number that is unique to each taxpayer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `taxResidenceCountry`  | String           | Country where the beneficiary pays taxes. Presented as an alpha-3 code (for example, `DEU`, `GBR`, `ARG`, and so on).                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `companyName`          | String           | Name of the company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `registrationNumber`   | String           | Unique number assigned to the company when it was registered as a legal entity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `registrationLocation` | String           | City, town, or another location where the company was registered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `type`                 | String           | Type of legal entity. For example, `Private Company Limited by Shares`, `Public Limited Company`, `Limited Partnership`, and so on.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `legalForm`            | String           | Standardized legal form of the company. Unlike the free-text `type` field, this value is validated against a fixed set of codes — see [Available values for `legalForm`](#available-values-for-legalform).<br /><br />Applicable to company beneficiaries only.                                                                                                                                                                                                                                                                                     |
| `incorporatedOn`       | Date             | Date of company incorporation (format `YYYY-mm-dd`, e.g. `2001-09-25`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `legalAddress`         | String           | The address a legal entity uses to register with a legal authority.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `postalAddress`        | String           | Company postal address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `controlScheme`        | String           | Description of the control scheme of the company ownership or group of entities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `taxId`                | String           | Taxpayer registration number/Code of taxpayer registration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `website`              | String           | Website URL of the company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `street`               | String           | Street name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `subStreet`            | String           | Additional information related to the street. This could be a house number or any other details.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `buildingNumber`       | String           | Building number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `flatNumber`           | String           | Flat or apartment number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `town`                 | String           | City, town, or another settlement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `state`                | String           | State, region, district, county or another territorial entity inside a country.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `postCode`             | String           | Address postal code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `externalUserId`       | String           | Unique applicant identifier as registered on your side. <ul><li>This identifier can be used to [get the applicant data](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid)  in case the <code>applicantId</code> in the Sumsub system is unknown to you.</li><li>When creating an applicant, you can generate and add the <code>externalUserId</code> manually, or it will be automatically generated and added by Sumsub.</li><li>You can change the <code>externalUserId</code> by the [following method](https://docs.sumsub.com/sumsub/reference/changing-top-level-information) .</li></ul> |
| `metadata`             | Array of objects | Additional information in custom fields that is not displayed to the applicant and not checked by Sumsub.<br />You can specify any information related to the applicant you want. For example: `[{"key": "keyFromClient", "value": "valueFromClient"}]`.                                                                                                                                                                                                                                                                                            |

## Response examples

If the request is successfully sent and processed, you will get a response like the one below.

```json
// This example shows a UBO beneficiary qualified as a Control UBO (`subtypes: ["controlUbo"]`), with `natureOfControl` populated accordingly:

{
  "id": "ace6bbda-1a58-4f4a-8e93-8a85fc0f27f8",
  "applicantId": "673f42e5bb38d64e0ba6c000",
  "applicant": {
    "id": "673f42e5bb38d64e0ba6c000",
    "createdAt": "2024-11-21 14:25:41",
    "createdBy": "service-prd-EJBDYWTFWAQXSH-app-all for test",
    "clientId": "your_cool_id",
    "inspectionId": "673f42e5bb38d64e0ba6ceac",
    "externalUserId": "25252525",
    "info": {},
    "fixedInfo": {
      "firstName": "John",
      "firstNameEn": "John",
      "lastName": "Reese",
      "lastNameEn": "Reese",
      "dob": "1980-05-30",
      "placeOfBirth": "London",
      "placeOfBirthEn": "London",
      "countryOfBirth": "GBR"
    },
    "applicantPlatform": "API",
    "requiredIdDocs": {
      "videoIdent": true,
      "videoIdentUploadTypes": [
        "ID_CARD",
        "PASSPORT"
      ],
      "docSets": [
        {
          "idDocSetType": "IDENTITY",
          "types": [
            "ID_CARD",
            "PASSPORT",
            "RESIDENCE_PERMIT",
            "DRIVERS"
          ],
          "subTypes": [
            "FRONT_SIDE",
            "BACK_SIDE"
          ],
          "videoRequired": "disabled",
          "captureMode": "manualAndAuto",
          "uploaderMode": "always"
        },
        {
          "idDocSetType": "IDENTITY2",
          "types": [
            "VISA"
          ]
        }
      ]
    },
    "review": {
      "reviewId": "vTuar",
      "attemptId": "jZlQY",
      "attemptCnt": 0,
      "levelName": "basic-kyc-level",
      "createDate": "2024-11-21 14:25:41+0000",
      "reviewStatus": "init",
      "priority": 0
    },
    "type": "individual",
    "memberOf": [
      {
        "applicantId": "673f390478c5cc60a492aa39"
      }
    ]
  },
  "shareSize": 10,
  "types": [
    "ubo"
  ],
  "subtypes": [
    "controlUbo"
  ],
  "natureOfControl": "Holds 60% of voting rights through Class B shares",
  "beneficiaryInfo": {
    "firstName": "John",
    "lastName": "Reese",
    "countryOfBirth": "GBR",
    "dob": "1980-05-30 00:00:00",
    "placeOfBirth": "London",
    "country": "GBR",
    "externalUserId": "25252525"
  }
}
```

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

```json
{
  "description": "Beneficiary's info is required",
  "code": 400,
  "correlationId": "a3493169a6247bdcd22580722366fcee"
}
```

# 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/{applicantId}/fixedInfo/companyInfo/beneficiaries": {
      "post": {
        "summary": "Link beneficiary to company",
        "description": "",
        "operationId": "link-beneficiary-to-company-kyb-20",
        "parameters": [
          {
            "name": "applicantId",
            "in": "path",
            "description": "Unique identifier of the company applicant in the Sumsub system to which the nested applicant should be linked. <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, and can be found in the [Dashboard](https://cockpit.sumsub.com/checkus/#/applicants/company?limit=10&page=0). <br><br>If the `applicantId` is unknown to you, use the [Get applicant data (externalUserId)](ref:get-applicant-data-via-externaluserid) method to fetch it.",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "types"
                ],
                "properties": {
                  "applicantId": {
                    "type": "string",
                    "description": "Applicant identifier of the beneficiary in the Sumsub system. <br><br>⚠️ Required when linking an existing applicant to the company. Leave empty when adding a new beneficiary with no profile in the Sumsub system yet."
                  },
                  "types": {
                    "type": "array",
                    "description": "Each string represents a beneficiary role for the new data structure, when one entity may have multiple roles.\n\nPossible values: `shareholder`, `ubo`, `representative`, `director`, `companyOfficer`, `investor`, `secretary`, `founder`, `legalAdvisor`, `authorizedSignatory`, `trustee`, `trustBeneficiary`, `trustSettlor`, `trustProtector`, `managingPartner`, `equityPartner`, `fundInvestor`, `fundManager`, `investmentManager`, `investmentAdviser`, `fundAdministrator`, `depositary`, `custodian`, `primeBroker`, `accountUser`.\n\nSee [Available values for `types` array](#available-values-for-types-array).",
                    "items": {
                      "type": "string"
                    }
                  },
                  "subtypes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Each string further qualifies the basis on which the beneficiary is a UBO. Only applicable when `types` includes `ubo`. Possible values: `ownershipUbo`, `controlUbo`, `substituteUbo`. <br><br>See [Available values for `subtypes` array](#available-values-for-subtypes-array)."
                  },
                  "natureOfControl": {
                    "type": "string",
                    "description": "Free-text description of how the beneficiary exercises control over the company. Maximum 255 characters.<br><br>⚠️ Required when `subtypes` includes `controlUbo`."
                  },
                  "shareSize": {
                    "type": "number",
                    "description": "Percentage of ownership if the beneficiary is a shareholder of the company. Also used to report the ownership percentage when `subtypes` includes `ownershipUbo`.",
                    "format": "double"
                  },
                  "beneficiaryInfo": {
                    "type": "object",
                    "description": "Structure that contains the beneficiary data. <br><br>⚠️ Required when adding a new beneficiary with no profile in the Sumsub system. Leave empty when linking an existing applicant to the company.",
                    "properties": {
                      "email": {
                        "type": "string",
                        "description": "Email address."
                      },
                      "phone": {
                        "type": "string",
                        "description": "Phone number."
                      },
                      "firstName": {
                        "type": "string",
                        "description": "First name of the beneficiary."
                      },
                      "lastName": {
                        "type": "string",
                        "description": "Last name of the beneficiary."
                      },
                      "middleName": {
                        "type": "string",
                        "description": "Middle name of the beneficiary."
                      },
                      "dob": {
                        "type": "string",
                        "description": "Date of birth.\n\n⚠️ The date of birth must not be in the future or earlier than 150 years before the current date. Otherwise, the request is rejected with a `400` error.",
                        "format": "date"
                      },
                      "countryOfBirth": {
                        "type": "string",
                        "description": "Country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`)."
                      },
                      "stateOfBirth": {
                        "type": "string",
                        "description": "State, region, district, county or another territorial entity of birth inside a country, if applicable."
                      },
                      "placeOfBirth": {
                        "type": "string",
                        "description": "Place of birth. This can be a city, a town or another settlement type."
                      },
                      "legalName": {
                        "type": "string",
                        "description": "Legal name of the company the beneficiary is related to (UBO or shareholder). You can keep this information and use it for your personal navigation.  <br><br>Note that the `legalName` field is not checked and you might need it just in case."
                      },
                      "gender": {
                        "type": "string",
                        "description": "Beneficiary gender (`M` or `F`)."
                      },
                      "nationality": {
                        "type": "string",
                        "description": "Country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`)."
                      },
                      "country": {
                        "type": "string",
                        "description": "Beneficiary country. This is usually a country of the last uploaded ID document, and it may differ from the country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`)."
                      },
                      "tin": {
                        "type": "string",
                        "description": "Taxpayer identification number that is unique to each taxpayer."
                      },
                      "taxResidenceCountry": {
                        "type": "string",
                        "description": "Country where the beneficiary pays taxes. Presented as an alpha-3 code (for example, `DEU`, `GBR`, `ARG`)."
                      },
                      "companyName": {
                        "type": "string",
                        "description": "Name of the company.<br><br>⚠️ Applicable to company applicants only."
                      },
                      "registrationNumber": {
                        "type": "string",
                        "description": "Unique number assigned to the company when it was registered as a legal entity.<br><br>⚠️ Applicable to company applicants only."
                      },
                      "registrationLocation": {
                        "type": "string",
                        "description": "City, town, or another location where the company was registered.<br><br>⚠️ Applicable to company applicants only."
                      },
                      "type": {
                        "type": "string",
                        "description": "Type of legal entity. For example, `Private Company Limited by Shares`, `Public Limited Company`, `Limited Partnership`, and so on.\n\n⚠️ Applicable to company applicants only."
                      },
                      "legalForm": {
                        "type": "string",
                        "description": "Standardized legal form of the company, validated against a fixed set of codes. See [Available values for `legalForm`](#available-values-for-legalform).\n\n⚠️ Applicable to company applicants only.",
                        "enum": [
                          "privateLimitedCompany",
                          "closedStockCorporation",
                          "cooperativeCompany",
                          "jointStockCompany",
                          "openStockCorporation",
                          "publicLimitedCompany",
                          "unregisteredSoleProprietorship",
                          "registeredSoleProprietorship",
                          "selfEmployedProfessional",
                          "generalPartnership",
                          "limitedPartnership",
                          "consortiumPartnership",
                          "jointVenture",
                          "trust",
                          "investmentFund",
                          "communityInterestCompany",
                          "friendlySociety",
                          "foundation",
                          "association",
                          "charity",
                          "stateOwnedEnterprise",
                          "publicInstitutionOrAgency",
                          "nationalGovernmentDepartment",
                          "localGovernmentDepartment"
                        ]
                      },
                      "incorporatedOn": {
                        "type": "string",
                        "description": "Date of company incorporation (format `YYYY-mm-dd`, e.g. `2001-09-25`).\n\n⚠️ Applicable to company applicants only.",
                        "format": "date"
                      },
                      "legalAddress": {
                        "type": "string",
                        "description": "The address a legal entity uses to register with a legal authority.\n\n⚠️ Applicable to company applicants only."
                      },
                      "postalAddress": {
                        "type": "string",
                        "description": "Company postal address.\n\n⚠️ Applicable to company applicants only."
                      },
                      "controlScheme": {
                        "type": "string",
                        "description": "Description of the control scheme of the company ownership or group of entities.\n⚠️ Applicable to company applicants only."
                      },
                      "taxId": {
                        "type": "string",
                        "description": "Taxpayer registration number/Code of taxpayer registration.\n\n⚠️ Applicable to company applicants only."
                      },
                      "website": {
                        "type": "string",
                        "description": "Website URL of the company.\n\n⚠️ Applicable to company applicants only."
                      },
                      "street": {
                        "type": "string",
                        "description": "Street name."
                      },
                      "subStreet": {
                        "type": "string",
                        "description": "Additional information related to the street. This could be a house number or any other details."
                      },
                      "buildingNumber": {
                        "type": "string",
                        "description": "Building number."
                      },
                      "flatNumber": {
                        "type": "string",
                        "description": "Flat or apartment number."
                      },
                      "town": {
                        "type": "string",
                        "description": "City, town, or another settlement."
                      },
                      "state": {
                        "type": "string",
                        "description": "State, region, district, county or another territorial entity inside a country."
                      },
                      "postCode": {
                        "type": "string",
                        "description": "Address postal code."
                      },
                      "externalUserId": {
                        "type": "string",
                        "description": "Unique applicant identifier as registered on your side. <ul><li>This identifier can be used to [get the applicant data](/reference/get-applicant-data-via-externaluserid) in case the <code>applicantId</code> in the Sumsub system is unknown to you.</li><li>When creating an applicant, you can generate and add the <code>externalUserId</code> manually, or it will be automatically generated and added by Sumsub.</li><li>You can change the <code>externalUserId</code> by the [following method](ref:changing-top-level-information).</li></ul>"
                      },
                      "metadata": {
                        "type": "array",
                        "description": "Additional information in custom fields that is not displayed to the applicant and not checked by Sumsub. <br><br>You can specify any information related to the applicant you want. For example: `[{\"key\": \"keyFromClient\", \"value\": \"valueFromClient\"}]`."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```