Guides
Start typing to search…

Business Clients

When onboarding a customer who is a business, there are additional steps needed in order to complete the KYB process. At a high level, the entity itself as well as the highest shareholder(beneficial owner) will need their information programmatically entered in through the API. If the entity has more than one beneficial owner, then you will need to create a personal-identity for each BO.

Who are the beneficial owners? Any shareholder in the business who owns 25% or more of the primary business. This can include both persons as well as other entities.

1. Add beneficial owners

Create all beneficial owners before creating your business Identity. You will need to onboard anyone who is either 25%+ ownership of the primary entity, or an authorised signer/agent on behalf of the entity.

You can only add a maximum of 5 beneficial owners

See API reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/beneficial-owners \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+12223334444",
    "address": {
      "street1": "80 Queens Road",
      "street2": "Suite 3B",
      "postalCode": "M11AE",
      "city": "Manchester",
      "state": "MAN", // ISO 3166-2 Subdivision code without the country prefix
      "country": "GB" // ISO 3166-1 alpha3 Country code,
    },
    "taxIdentificationNumber": "111111111",
    "birthDate": "2019-08-24",
    "isSigner": true,
    "hasOwnership": true,
    "hasControl": true,
    "relationshipEstablishedAt": "2015-01-01",
    "jobTitle": "CEO" // required when hasControl is TRUE for Beneficial owners
  }'

Example response:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", // beneficialOwnerId
  "email": "string",
  "phone": "string",
  ...
}

📘

Supported Countries and States List

To retrieve the list of supported countries and states, use the Get List of Countries API. This endpoint provides up-to-date information on all available regions.

2. Upload documents for beneficial owners

  • Allowed GovIdType values: passport driversLicense permanentResidencyId visa
See API reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/beneficial-owners/{beneficialOwnerId}/documents \
  --header 'Accept: application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --form ProofOfAddress= \
  --form GovIdImageFront= \
  --form GovIdImageBack= \
  --form GovIdCountry="GB" \ // ISO 3166-1 alpha-2 country code
  --form GovIdNumber="12749595851"  \
  --form GovIdType="passport"

3. Create a business client

  • Allowed businessType values: Cooperative, Corporation, Llc, Other, Partnership, SoleProp, Trust
  • For businessIndustry code see Business Industry list
  • Allowed accountPurpose values: charitableDonations ecommerceRetailPayments investmentPurposes other paymentsToFriendsOrFamilyAbroad payroll personalOrLivingExpenses protectWealth purchaseGoodsAndServices receivePaymentsForGoodsAndServices taxOptimization treasuryManagement
See API reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/business \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --data '{
    "name": "string",
    "description": "string",
    "businessType": "Corporation", // See values listed above
    "email": "string",
    "website": "string",
    "address": {
      "street1": "80 Queens Road",
      "street2": "Suite 3B",
      "postalCode": "M1 1AE",
      "city": "Manchester",
      "state": "MAN", // ISO 3166-2 Subdivision code without the country prefix
      "country": "GB" // ISO 3166-1 alpha-2 country code
    },
    "taxIdentificationNumber": "string",
    "beneficialOwners": [
      {beneficialOwnerId} // Add previously created beneficial Owner Id's here
    ],
    "businessIndustryCode": "1153", // See link busienss industry codes above
     "accountPurpose": "purchaseGoodsAndServices",
     "accountPurposeOther": "string" // only required when accountPurpose value is other
}'

Example response:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", // businessClientId
  "taxIdentificationNumber": "string",
  "email": "string",
  "complianceStatus": "Pending",
  ...
}

4. Upload business documents

See API reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/{businessClientId}/business-documents \
  --header 'Accept: application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --form StatementOfFunds= \
  --form OwnershipDocument= \
  --form ProofOfCompanyFormation=

5. Accept the Terms of Service

When you register a new client, they must agree to the terms of service.

See API reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/{businessClientId}/terms-of-service \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'
import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.sandbox.keyrails.com/api/v1/clients/{businessClientId}/terms-of-service',
  headers: {
    'Content-Type': 'application/json', 
    Accept: 'application/json',
    Authorization: 'Bearer {{AccessToken}}'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Example response:

{
  "url": "https://example.co/accept-terms-of-service?session_token=xxxx&redirect_uri=https://api.sandbox.keyrails.com/api/v1/terms-of-service-agreements/xxxxx"
}

Use this url to guide the client towards accepting the Terms of Service. You can embed this URL in an iFrame or open it in a new browser window. Upon acceptance of the Terms of Service, the page will redirect to our application, and you may then close the browser.


Webhooks Examples

Before proceeding, ensure that your webhook configuration is set up. Refer to the setup guide for detailed instructions.

Webhook types: - Identity

Client approved

{
  "tenantId": "64790ea8-f9b1-4b52-aff6-f6177bb3fcee",
  "action": "Update",
  "id": "cfc05dcb-5983-413b-8d8b-f8ef69a14787",
  "resourceId": "d8d01119-4b78-41a6-b868-0849b9ecf2ff",
  "resourceType": "Identity",
  "createdAtUtc": "0001-01-01T00:00:00",
  "changes": {
    "complianceStatus": "Approved"
  }
}

Client rejected

{
  "tenantId": "47dce736-7fe1-42f9-a317-2676733823fe",
  "action": "Update",
  "id": "fa85e3f4-99cb-46be-bbd3-4faad0bf565d",
  "resourceId": "51777f07-8b43-468f-8808-c7cb1405f254",
  "resourceType": "Identity",
  "createdAtUtc": "0001-01-01T00:00:00",
  "changes": {
    "complianceStatus": "Rejected",
    "rejectionReasons": [
      "Failed to verify proof of address",
      "Poor quality of the document"
    ]
  }
}

Updated 12 days ago