API Documentation

/link_business_member

Links individuals as members of a registered business with roles, descriptions, and ownership stakes. Necessary to begin business verification process.

Suggest Edits

📘

Advanced KYC

Updates to this page coming soon.

After having created a business user at a handle with /register, you will need to link at least one individual entity as a controlling officer. If the business type requires certification (most business types do), you will need to link an entity as an administrator and link all major beneficial owners.

It is possible for one entity to be linked multiple times with different roles, but one entity cannot hold the same role multiple times over.

Requests

header.user_handle should have either the registered individual entity to be linked or the administrator performing the link. (If an administrator is performing a membership link, specify the registered individual to be linked in the member_handle key.)

header.business_handle should have the registered business entity to be linked.

The details key in the request body is not required and can be any descriptive (non-empty, non-null) string.

The ownership_stake key can only be specified for (and is required for) beneficial owners. The value must be a float greater than 0 and equal to or less than 100 (0 < n <= 100).

Either key role or role_uuid may be specified in the request body to identify a role to be assigned to a business member. The role_uuid comes from the response to /get_business_roles.

If you would prefer to have an applicant link business members, you can have an “administrator” member authenticate with the usersignature and assign other users to business roles using the optional member_handle key. Otherwise, the authenticated user is assigned the specified business role if no member_handle is sent in the request.

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

Both authsignature and usersignature headers are required for this request. The usersignature header should be generated with a keypair registered to the user (either registered from the /register endpoint or the /register_wallet endpoint). The businesssignature header should be generated with a keypair registered to the business user (either registered from the /register endpoint or the /register_wallet endpoint).

See the section on ECDSA Authentication for more detail about ECDSA signature generation.

Note - We recently renamed the field auth_handle to app_handle. For backward compatibility, auth_handle is still valid but has been removed from our documentation.

📘

A Note On Roles

There are currently three roles to be linked.

Administrator
Required. An administrator is the user who is responsible for setting up the business and must be used to certify the validity of the information provided for the business and Beneficial Owners. An administrator is also required to link a controlling officer or beneficial owner.

Controlling Officer
Required. A controlling_officer is an individual who is in a leadership position and has the ability to sign contracts for the business.

Beneficial Owner
Conditional. Some business types need to have all individuals with a greater than 25% ownership stake in the company--a beneficial_owner--linked and certified by the Administrator. See /get_business_roles for more information.

📘

The Admin Role

When linking the first business member (Administrative), you must omit the member_handle, so that it links the authenticated user as an Administrative Business Member. After that, the Admin user can link other users with the member_handle field.

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": "your_admin_user_handle",
        "business_handle": "your_business_user_handle",
        "reference": "<your unique id>"
    },
    "role": "controlling_officer",
    "member_handle": "your_individual_user_handle"
}

---

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,
        "auth_handle": "your_app_handle",
        "user_handle": "your_individual_user_handle",
        "business_handle": "your_business_user_handle",
        "reference": "<your unique id>"
    },
    "role": "beneficial_owner",
    "details": "Private investor",
    "ownership_stake": 66.7
}

***

HTTP/1.1 200 OK

{
    "success": true,
    "status": "SUCCESS",
    "message": "User \"Example User\" has been made a Controlling Officer for business Your Business Co.",
    "role": "controlling_officer",
    "details": null,
    "verification_uuid": null,
    "response_time_ms": "171",
    "reference": "<your unique id>"
}

---
  
HTTP/1.1 200 OK

{
    "success": true,
    "status": "SUCCESS",
    "message": "User \"Example User\" has been made a Beneficial Owner for business .",
    "role": "beneficial_owner",
    "details": "Private investor",
    "verification_uuid": null,
    "response_time_ms": "171",
    "reference": "<your unique 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.silamoney.eth';
$businessPrivateKey = 'some private key';
$userHandle = 'user.silamoney.eth'; // 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 = 'other_user.silamoney.eth'; // 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

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 Codesuccess AttributeDescription
200trueThe business and specified individual have been successfully linked.
400falseBad request format - check validation_details for more information.
403falseauthsignature, businesssignature, or usersignature header was absent or incorrect.

Updated 4 months ago