Overview
Use this method to link an existing applicant in the Sumsub system to the control and ownership structure of a company. You can link both an individual and a company applicant as a beneficiary to the company profile.
Linking a beneficiary applicant to a company applicant does not affect the verification status of one another as they are independent. For example, the applicant X in the pending status is linked as a beneficiary to the company applicant Y that is already verified and has the completed status. The applicant X is staying in pending until verification is complete and the verdict is returned. The status of the company applicant Y does not change.
Note
The method cannot create a new applicant; only an existing applicant can be added as a beneficiary to a company. For information on creating an applicant, refer to this method.
Attention
If you call this endpoint for a KYB 2.0 applicant, the method will add beneficiary data to the
infostructure (Extracted Info). For KYB 2.0 applicants, it is highly recommended to use this method.
Request example
curl -X POST \
'https://api.sumsub.com/resources/applicants/5e9412223cc1813b4db0b0e3/info/companyInfo/beneficiaries' \
-H 'Content-Type: application/json' \
-d '{
"applicant": {
"id": "5f6490a55584b510013e87df"
},
"applicantId": "5f6490a55584b510013e87df",
"positions": [
"director",
"shareholder"
],
"type": "ubo"
}'
Response explained
If the request is successfully sent and processed, you will get a JSON file that contains the object representing the newly added beneficiary applicant. The following table explains the fields available within the (beneficiary) object.
| Field | Type | Description |
|---|---|---|
id | String | Autogenerated key for all KYB 2.0 beneficiaries. |
applicantId | String | Applicant identifier of the beneficiary in the Sumsub system. |
positions | Array of strings | Positions in the company that the beneficiary is holding. Possible values:
|
type | String | Beneficiary single role in the company control and ownership structure. Possible values:
|
inRegistry | Boolean | Matching to a Corporate registry.
|
imageIds | Array of strings | Image IDs represent a document uploaded. If imageIds array contains more than one element, the first one would be the front side and the others — back sides. |
applicant | Object | Structure to create a new beneficiary. |
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:
|
beneficiaryInfo | Object | Structure that contains the beneficiary contact data. |
beneficiaryInfo attributes
beneficiaryInfo attributesThe following table explains the beneficiaryInfo attributes representing the beneficiary contact data.
| Field | Type | Description |
|---|---|---|
firstName | String | First name of the beneficiary. |
lastName | String | Last name of the beneficiary. |
dob | Date | Beneficiary date of birth. |
email | String | Beneficiary email address. |
taxResidenceCountry | String | Country where the beneficiary pays taxes. Presented as an alpha-3 code (for example, DEU, GBR, ARG, and so on). |
Response example
{
"id": null,
"applicantId": "63e096c51b6b400000000000",
"positions": [
"shareholder",
"other"
],
"type": "shareholder",
"inRegistry": null,
"imageIds": null,
"applicant": {
"id": "63e096c51b6b4030f2e01154",
"createdAt": "2023-02-06 05:57:25",
"clientId": "someCoolId",
"inspectionId": "63e096c51b6b400000000000",
"externalUserId": "11111111111111",
"sourceKey": "newSourceKey",
"info": {
"firstName": "John",
"firstNameEn": "John",
"lastName": "Doe",
"lastNameEn": "Doe"
},
"email": "[email protected]",
"phone": "+44 123456789",
"requiredIdDocs": {
"docSets": [
{
"idDocSetType": "IDENTITY",
"types": [
"ID_CARD"
]
},
{
"idDocSetType": "PHONE_VERIFICATION"
},
{
"idDocSetType": "EMAIL_VERIFICATION"
}
]
},
"deleted": false,
"review": {
"reviewId": "TBJoW",
"attemptId": "KLUSg",
"attemptCnt": 0,
"levelName": "basic-kyc-level",
"createDate": "2024-06-17 08:34:37+0000",
"reviewStatus": "pending"
},
"lang": "en",
"type": "individual"
},
"shareSize": null,
"types": null,
"beneficiaryInfo": null
}
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:
{
"description": "Malformed data provided in the request",
"code": 400,
"correlationId": "62825afad452fb4007534e1529f000e5"
}