--- title: "Link beneficiary to company" method: POST path: "/resources/applicants/{applicantId}/fixedInfo/companyInfo/beneficiaries" --- # Link beneficiary to company `POST /resources/applicants/{applicantId}/fixedInfo/companyInfo/beneficiaries` ## Request - Base URL: `https://api.sumsub.com` - URL: `https://api.sumsub.com/resources/applicants/{applicantId}/fixedInfo/companyInfo/beneficiaries` - Auth: API key in header `X-App-Token` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Path parameters - `applicantId` string, required ## Request body - object - `applicantId` string: Applicant identifier of the beneficiary in the Sumsub system.

⚠️ 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` string[], required: Each string represents a beneficiary role for the new data structure, when one entity may have multiple roles. Possible 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`. See [Available values for `types` array](#available-values-for-types-array). - `subtypes` string[]: Each string further qualifies the basis on which the beneficiary is a UBO. Only applicable when `types` includes `ubo`. Possible values: `ownershipUbo`, `controlUbo`, `substituteUbo`.

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. Maximum 255 characters.

⚠️ Required when `subtypes` includes `controlUbo`. - `shareSize` number, double: Percentage of ownership if the beneficiary is a shareholder of the company. Also used to report the ownership percentage when `subtypes` includes `ownershipUbo`. - `beneficiaryInfo` object: Structure that contains the beneficiary data.

⚠️ Required when adding a new beneficiary with no profile in the Sumsub system. Leave empty when linking an existing applicant to the company. - `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` string, date: Date of birth. ⚠️ 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. - `countryOfBirth` string: Country of birth. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`). - `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`). - `nationality` string: Country of origin. Presented as an alpha-3 country code (for example, `DEU`, `GBR`, `ARG`). - `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`). - `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`). - `companyName` string: Name of the company.

⚠️ Applicable to company applicants only. - `registrationNumber` string: Unique number assigned to the company when it was registered as a legal entity.

⚠️ Applicable to company applicants only. - `registrationLocation` string: City, town, or another location where the company was registered.

⚠️ Applicable to company applicants only. - `type` string: Type of legal entity. For example, `Private Company Limited by Shares`, `Public Limited Company`, `Limited Partnership`, and so on. ⚠️ Applicable to company applicants only. - `legalForm` 'privateLimitedCompany' | 'closedStockCorporation' | 'cooperativeCompany' | 'jointStockCompany' | 'openStockCorporation' | 'publicLimitedCompany' | 'unregisteredSoleProprietorship' | 'registeredSoleProprietorship' | 'selfEmployedProfessional' | 'generalPartnership' | 'limitedPartnership' | 'consortiumPartnership' | 'jointVenture' | 'trust' | 'investmentFund' | 'communityInterestCompany' | 'friendlySociety' | 'foundation' | 'association' | 'charity' | 'stateOwnedEnterprise' | 'publicInstitutionOrAgency' | 'nationalGovernmentDepartment' | 'localGovernmentDepartment': Standardized legal form of the company, validated against a fixed set of codes. See [Available values for `legalForm`](#available-values-for-legalform). ⚠️ Applicable to company applicants only. - `incorporatedOn` string, date: Date of company incorporation (format `YYYY-mm-dd`, e.g. `2001-09-25`). ⚠️ Applicable to company applicants only. - `legalAddress` string: The address a legal entity uses to register with a legal authority. ⚠️ Applicable to company applicants only. - `postalAddress` string: Company postal address. ⚠️ Applicable to company applicants only. - `controlScheme` string: Description of the control scheme of the company ownership or group of entities. ⚠️ Applicable to company applicants only. - `taxId` string: Taxpayer registration number/Code of taxpayer registration. ⚠️ Applicable to company applicants only. - `website` string: Website URL of the company. ⚠️ Applicable to company applicants only. - `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. - `metadata` unknown[]: 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"}]`. - unknown ## Changes - **2026-11-03** `fcc702e558a2`: 3 info - added the new optional request property `beneficiaryInfo/legalForm` - added the new optional request property `natureOfControl` - added the new optional request property `subtypes` [Operation history](https://skmtc.dev/sumsub/apis/sumsub-api/changes/resources/applicants/:applicantId/fixedInfo/companyInfo/beneficiaries/post.md) --- [API](https://skmtc.dev/sumsub/apis/sumsub-api.md) - [All operations](https://skmtc.dev/sumsub/apis/sumsub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sumsub/apis/sumsub-api/revisions/fcc702e558a2?raw)