/link_business_member
Links an individual entity to a business entity.
This page has been updated with Priority specs.
Use this endpoint to link an existing individual entity to an existing business entity.
In addition to linking, this endpoint assigns the new business member one of three business roles, and assigns ownership percentage to Beneficial Owners.
Recommendation: if you're new with Sila, begin with our KYB Overview page
Order of Operations
- Within the KYB Flow -
A single individual entity can be linked as a member to multiple business entities
No entities have begun KYB or KYC
Ideally, neither the business entity nor any of the linked members have begun their own individual KYC or KYB verification before they are all linked together. This helps keep all verification records neatly tied together.
In this scenario, you only need to call /kyc once.
Once all members have been linked, calling /kyc on the business user_handle will kick off unique verification records for the business and all its linked members.
Members have already started KYC
If you do have members that have already started the KYC process, just wait until the individual has fully passed KYC, then link them and call /kyc on the business user_handle.
- For each business, link admin first -
Having a linked admin is required in order to link a controlling officer or beneficial owner. You'll need to provide the admin's user_handle in the request bodies when linking one of the two other roles.
Since each link request can only assign one role to one member, make sure to link the admin first.
Linking another business entity as a member of another business
We do not generally support this scenario, so we do not have functionality built out for a business entity to be linked to another business entity and assigned a role using this endpoint.
If a business (Child Biz) does legitimately need to be linked as a business member of another business (Parent Biz):
- One individual from Child Biz must be designated as representative/controlling person to be linked as a BO to Parent Biz. Call
/register
for that individual - includeid_document
data since they will be linked as a BO. Pass this ind- For the purposes of calling /link_business_member, link with 25% for the ownership percentage
Business Roles
To pass through KYB, the ownership structure of a business must be provided. Using Sila and Priority's KYB system, this means linking individuals to the business entity.
There are three total roles, two of which are required for every business - administrators and controlling officers.
A single member can hold all business roles if needed and appropriate.
Only one role can be assigned per /link_business_member request
Role Descriptions
Role | Description | Required? |
---|---|---|
Administrator | Used to link other business members and certify beneficial owners and the business. | Y |
Controlling Officer (CO) | Individuals with the authority to bind the company specifically by delegation in the company’s organizational documents (or by action of the board, voting members, partners, etc.). In other words, Controlling Officers are individuals with leadership positions that have the ability to sign contracts for the business. | Y |
Beneficial Owner (BO) | Individuals with an ownership stake in the business. | Required depending on business type |
Beneficial Owner Requirements by Business Type
Business Type | BO Required? | ownership_stake requirement |
---|---|---|
Public Corporation / Corporation / LLC / LLP / LP | Optional | Required minimum total percentage is 0%. |
Non-Profit | Optional | A maximum of 4 BO's can be added. |
Partnership | Required | Required minimum total ownership percentage is 50%. |
Sole Proprietorship | Required | Only one BO can be linked. Required minimum total percentage is 100%. |
Requests
Authorization / Authentication
Apps using Access Token Authorization
Use a valid access token in an Authorization: Bearer request header.
See Authenticating with an Access Token for more details.
Apps using ECDSA Authentication
Backwards compatibility support for ECDSA authentication.
Linking the Admin
Start with linking an individual with the admin role, as the user_handle for the admin is required to link a BO or a CO.
Admin Link Request
POST /0.2/link_business_member HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
businesssignature: [GENERATED BUSINESSSIGNATURE HEX STRING HERE]
{
"header": {
"created": 1234567890,
"app_handle": "<your_app_handle>",
"user_handle": "user_handle to be linked as admin>",
"business_handle": "<business_user_handle>",
"reference": "<your unique uuid>"
},
// role or role_uuid required
"role": "administrator"
}
***
HTTP/1.1 200 OK
{
"success": true,
"status": "SUCCESS",
"message": "User <admin_user_handle> has been made an Administrator for business <business name>",
"role": "administrator",
"details": null,
"verification_uuid": null,
"response_time_ms": "171",
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
}
const res = await sila.linkBusinessMember(
user_handle,
user_private_key,
business_handle,
business_private_key,
role,
member_handle,
details,
ownership_stake
);
//success response object
console.log(res.statusCode); // 200
console.log(res.data.success); // TRUE
console.log(res.data.message); // Response message
console.log(res.data.status);
console.log(res.data.role);
console.log(res.data.details);
console.log(res.data.verification_uuid);
payload = {
"user_handle": user_handle,
"business_handle": business_handle,
"role": "controlling_officer",
"details": "this is the business administrator"
}
response = BusinessOperations.linkBusinessMember(app, payload, user_private_key, business_private_key)
# Success Response
{
"status_code": 200,
"status": "SUCCESS",
"success": true,
"message": "User \"Postman User\" has been made a Controlling Officer for business Sila, Inc.",
"role": "controlling_officer",
"details": "this is the business administrator",
"verification_uuid": None
}
BusinessRole businessRole = ((GetBusinessRolesResponse)api.getBusinessRoles().getData()).getBusinessRoles().get(0);
float ownershipStake = 0.30f;
ApiResponse response = api.linkBusinessMember("user handle", "user private key", "business handle", "business private key", businessRole, (optional) "member handle", (optional) "test details", (optional) ownershipStake);
// Success Object Response
System.out.println(response.getStatusCode()); // 200
System.out.println(((LinkBusinessMemberResponse) response.getData()).getDetails());// test details
System.out.println(((LinkBusinessMemberResponse) response.getData()).getRole());// business role name
System.out.println(((LinkBusinessMemberResponse) response.getData()).getVerificationUuid());// verification uuid
System.out.println(((LinkBusinessMemberResponse) response.getData()).getMessage());// user has been made a beneficial owner
System.out.println(((LinkBusinessMemberResponse) response.getData()).isSuccess());// true
System.out.println(((LinkBusinessMemberResponse) response.getData()).getStatus());// SUCCESS
$businessHandle = 'business_handle';
$businessPrivateKey = 'some private key';
$userHandle = 'user_handle'; // The user handle to apply the role to. See the $memberHandle for more information
$userPrivateKey = 'some other private key';
$businessRole = 'administrator'; // Required if $businessRoleUuid is not set. The business role to set
$businessRoleUuid = null; // Required if $businessRole is not set. The business role uuid to set
$ownershipStake = null; // Required only if the role is 'beneficial_owner'
$memberHandle = 'member_handle'; // If set the $userHandle must be a user with the administrator role in the business
$details = 'some details about the operation'; // Optional. A text description of the operation
$response = $client->linkBusinessMember($businessHandle, $businessPrivateKey, $userHandle, $userPrivateKey, $businessRole, $businessRoleUuid, $ownershipStake, $memberHandle, $details);
// Response 200
echo $response->getStatusCode(); // 200
echo $response->getData()->status;
echo $response->getData()->success; // TRUE
echo $response->getData()->message; // User has been made a... for business...
echo $response->getData()->role; // The role name applied
echo $response->getData()->details; // The details set in the request
echo $response->getData()->verification_uuid; // Is null if KYC hasn't been applied to the business
var responseRole = api.GetBusinessRoles();
Console.WriteLine(responseRole.StatusCode); // 200
var ResponseRole = (BusinessRolesResponse)responseRole.Data;
BusinessRole businessRole = new BusinessRole();
businessRole.Name = ResponseRole.BusinessRoles[0].Name; // 0 index for "controlling_officer", 1 index for "beneficial_owner", 2 index for "administrator"
businessRole.Label = ResponseRole.BusinessRoles[0].Label; // 0 index for "Controlling Officer", 1 index for "Beneficial Owner", 2 index for "Administrator"
businessRole.Uuid = ResponseRole.BusinessRoles[0].Uuid; // 0 index for "9a350e54-0ce9-48fc-b437-9c7b7cfdd1ac", 1 index for "0adb5421-3395-4f81-9e26-dd8d5abae590", 2 index for "977bc3be-8f79-4e83-9df1-29525c06f23e"
ApiResponse<object> response = api.LinkBusinessMember(userHandle, userPrivateKey, businessHandle, businessPrivateKey, businessRole, details, memberHandle, ownershipStake);
// Success object response
Console.WriteLine(response.StatusCode); // 200
var parsedData = (LinkOperationResponse)response.Data;
Console.WriteLine(parsedData.Details); // details
Console.WriteLine(parsedData.Role); // Linkekd business member role
Console.WriteLine(parsedData.VerificationUuid); // Verification uuid
Console.WriteLine(parsedData.Message); // Message
Console.WriteLine(parsedData.Status); // Status
Console.WriteLine(parsedData.Success); // Success
Admin Request Attributes
Key | Type | Description |
---|---|---|
header | JSON object | Required. Required keys: created - Unix epoch timestamp in seconds. Must not be future-dated and must not be dated more than 5 minutes in the past.app_handle - your app handleuser_handle - the user_handle to link as an adminbusiness_handle - the business the individual entity is being linked toOptional keys: reference : Can be any value for your own reference. If not provided, one will be assigned.version : Cannot be null if key is present. Valid values: 0.2, v0.2, V0.2 |
role | string | Either role OR role_uuid required.administrator |
role_uuid | string | Either role OR role_uuid required. Can be found calling /get_business_roles |
details | string | Optional. Cannot be set to null or an empty string. |
Linking the CO
CO Link Request
POST /0.2/link_business_member HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
businesssignature: [GENERATED BUSINESSSIGNATURE HEX STRING HERE]
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
{
"header": {
"created": 1234567890,
"app_handle": "your_app_handle",
"user_handle": "linked_admin_user_handle",
"business_handle": "business_user_handle",
"reference": "<your unique uuid>"
},
"member_handle": "user_handle to be linked as CO", // required
"role": "controlling_officer" // either role or role_uuid required
}
***
HTTP/1.1 200 OK
{
"success": true,
"status": "SUCCESS",
"message": "User <CO_user_handle> has been made a Controlling Officer for business <business name>",
"role": "controlling_officer",
"details": null,
"verification_uuid": null,
"response_time_ms": "171",
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
}
CO Request Attributes
Key | Type | Description |
---|---|---|
header | JSON object | Required. Required keys: created - Unix epoch timestamp in seconds. Must not be future-dated and must not be dated more than 5 minutes in the past.app_handle - your app handleuser_handle - the user_handle for the linked adminbusiness_handle - the business the individual entity is being linked toOptional keys: reference : Can be any value for your own reference. If not provided, one will be assigned.version : Cannot be null if key is present. Valid values: 0.2, v0.2, V0.2 |
role | string | Either role OR role_uuid required.controlling_officer |
role_uuid | string | Either role OR role_uuid required. Can be found calling /get_business_roles |
member_handle | string | Required. user_handle for the individual to be linked as CO. |
details | string | Optional. Cannot be set to null or an empty string. |
Linking a BO
BO Link Request
POST /0.2/link_business_member HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
businesssignature: [GENERATED BUSINESSSIGNATURE HEX STRING HERE]
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
{
"header": {
"created": 1234567890,
"app_handle": "your_app_handle",
"user_handle": "linked_admin_user_handle",
"business_handle": "business_user_handle",
"reference": "<your unique uuid>"
},
"member_handle": "user_handle to be linked as BO", // required
"role": "beneficial_owner", // either role or role_uuid required
"ownership_stake": 50.5 // required
}
***
HTTP/1.1 200 OK
{
"success": true,
"status": "SUCCESS",
"message": "User <BO_user_handle> has been made a Beneficial Owner for business <business name>",
"role": "beneficial_owner",
"details": null,
"verification_uuid": null,
"response_time_ms": "171",
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
}
BO Request Attributes
Key | Type | Description |
---|---|---|
header | JSON object | Required. Required keys: created - Unix epoch timestamp in seconds. Must not be future-dated and must not be dated more than 5 minutes in the past.app_handle - your app handleuser_handle - the user_handle for the linked adminbusiness_handle - the business the individual entity is being linked toOptional keys: reference : Can be any value for your own reference. If not provided, one will be assigned.version : Cannot be null if key is present. Valid values: 0.2, v0.2, V0.2 |
role | string | Either role OR role_uuid required.beneficial_owner |
role_uuid | string | Either role OR role_uuid required. Can be found calling /get_business_roles |
member_handle | string | Required. user_handle for the individual to be linked as BO. |
ownership_stake | float | Required. Can be whole number (30) or decimal (30.5) Greater than 0 Less than or equal to 100 |
details | string | Optional. Cannot be set to null or an empty string. |
Responses
The verification_uuid
in the response is null if KYC has never been started on the business. However, if KYC has already been started on the business, a new individual verification will be started on the linked member automatically and this field will contain a UUID4 string.
Status Code | success | Description |
---|---|---|
200 | true | The business and specified individual have been successfully linked. |
400 | false | Bad request format - check validation_details for more information. |
400 | false | "id_document information must be provided before attempting to link member {user_handle}" No id_document data was provided during /register. Please use /add/id_document to add this information and try again. No need to upload an actual document |
400 | false | "Priority Bank rejected this member linking. Please try again or reach out for support." Reach out to Sila for next steps. Please provide individual and business user_handles. |
Updated 4 days ago