Overview
- Link existing applicant as beneficiary
- Link non-existent applicant as beneficiary
Response explained

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 2.0 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 as an applicant in the Sumsub system or the beneficiary is not yet registered and has no applicant profile created. See the description of cases and request examples below.

📘
Note
The method updates the information on the beneficiary in the fixedInfo structure (Provided info).

Link existing applicant as beneficiary

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

applicantId and types are mandatory to send.
beneficiaryInfo must be excluded from the request.

Request example

curl -X POST \
     'https://api.sumsub.com/resources/applicants/63e2428232f67079df8dc591/fixedInfo/companyInfo/beneficiaries' \
     -d '{
            "applicantId": "63620c095cc65d0001ffc8d7",		  
            "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 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 example

curl -X POST \
     'https://api.sumsub.com/resources/applicants/63e2428232f67079df8dc591/fixedInfo/companyInfo/beneficiaries' \
     -d '{
            "beneficiaryInfo": {
              "firstName": "John",
              "lastName": "Reese",
              "countryOfBirth": "GBR",
              "placeOfBirth": "London"
            },
            "types": [
              "shareholder"
            ],
            "shareSize": 42.52
          }'

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 2.0 beneficiaries when they are added to the company structure.
`applicantId`	String	Unique applicant identifier of the beneficiary in the Sumsub system. 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 for detailed description of the attributes and element fields. 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.
`types`	Array of strings	List of beneficiary roles for the new data structure, when one entity may have multiple roles. Possible values: `ubo` — ultimate beneficial owner of the company. `shareholder` — owns shares in the company stock. `representative` — authorized to act or speak for or in support of the company. `director` — appointed to manage the company business and affairs.
`beneficiaryInfo`	Object	Structure that contains the beneficiary data. 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. 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.
`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. This identifier can be used to get the applicant data in case the `applicantId` in the Sumsub system is unknown to you. When creating an applicant, you can generate and add the `externalUserId` manually, or it will be automatically generated and added by Sumsub. You can change the `externalUserId` by the following method .
`metadata`	Array of objects	Additional information in custom fields that is not displayed to the applicant and not checked by Sumsub. 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.

{
  "id": "ace6bbda-1a58-4f4a-8e93-8a85fc0f27f8",
  "applicantId": "673f42e5bb38d64e0ba6ceac",
  "applicant": {
    "id": "673f42e5bb38d64e0ba6ceac",
    "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": [
    "shareholder"
  ],
  "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:

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

Link beneficiary to company (KYB 2.0)

Table of contents

Overview

📘
Note

Link existing applicant as beneficiary

Request example

Link non-existent applicant as beneficiary

Request example

Response explained

Root variables

`beneficiaryInfo` attributes

Response examples

Table of contents

Overview

📘Note

Link existing applicant as beneficiary

Request example

Link non-existent applicant as beneficiary

Request example

Response explained

Root variables

beneficiaryInfo attributes

Response examples

📘
Note

`beneficiaryInfo` attributes