Running KYB

Introduction

After your business has provided the information necessary to create a Business resource, you need to authenticate and verify that information. Using the Business object, you can perform a number of checks and screenings to ensure compliance. This process is controlled Bond Studio's KYBKYB - Know Your Business. The compliance that financial institutions put into their policies and procedures to verify the identity of the company they plan to have a business relationship with. service. ▶ Run in Postman

This process is a critical step where you validate the identity of your business and its documents to ensure that they're compliant with federal regulations.

Running the KYB process

To start the KYB process, use the POST /businesses/{business_id}/verification-kyb operation with no further parameters.

An example of a request to initiate a KYB process for the business ID 002e0f0e-e39d-4351-876c-afcad30d9c37 is shown below.

curl --request POST \
  --url https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Identity: YOUR-IDENTITY'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'

response = http.request(request)
puts response.read_body
const options = {
  method: 'POST',
  headers: {
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  }
};

fetch('https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/business/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb"

headers = {
  'Identity': YOUR-IDENTITY,
  'Authorization': YOUR-AUTHORIZATION,
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = None)

print(response.text.encode('utf8'))
var client = new RestClient("https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb");
var request = new RestRequest(Method.POST);
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb")
  .post(null)
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

Response response = client.newCall(request).execute();

When you initiate a KYB process, the KYB service responds with an initialized message similar to the one shown below.

{
    "business_id": "002e0f0e-e39d-4351-876c-afcad30d9c37",
    "kyb_status": "initialized"
}

The results of the KYB are sent via a webhook.

If a business fails the KYB check and they can't pass a manual check, you can't issue them a card.

For a complete specification and interactive examples, see Running KYB in the Bond API Reference.

KYB webhook events

Possible responses to a KYB request are shown in the following table.

Event enum values

Description

kyb.verification.approved

KYB passed.

kyb.verification.warning

KYB requires manual review. The response contains any business information which could not be verified.

kyb.verification.rejected

KYB failed due to low confidence in identity validation.

kyb.verification.error

KYB failed due to a server error. To retry, send a POST /businesses/{business_id}/verification-kyb.

Possible responses to a KYB check are shown below.

{
    "event": "kyb.verification.approved",
    "business_id": "002e0f0e-e39d-4351-876c-afcad30d9c37",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00"
}
{
    "event": "kyb.verification.rejected",
    "business_id": "002e0f0e-e39d-4351-876c-afcad30d9c37",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00"
}
{
   "event":"kyb.verification.warning",
   "business_id":"002e0f0e-e39d-4351-876c-afcad30d9c37",
   "occurred_at":"2021-02-02-00:50:58.484840+00:00",
   "business_info":{
      "kyb_info":[
        {
          "category": "sos",
          "key": "sos_unknown",
          "label": "SOS Filings",
          "message": "1 of 3 filings have no status provided",
          "status": "warning",
          "sub_label": "Partially Unknown"
        },
        {
          "category": "address",
          "key": "address_verification",
          "label": "Office Address",
          "message": "Identified an address within 0.2 miles of the submitted Office Address",
          "status": "warning",
          "sub_label": "Approximate Match"
        },
      ],
      "watchlist":{
         "hit_count":1,
         "agencies":[
            {
               "abbr":"OFAC",
               "name":"Office of Foreign Assets Control",
               "org":"U.S. Department of Treasury"
            },
            {
               "abbr":"BIS",
               "name":"Bureau of Industry and Security",
               "org":"U.S. Department of Commerce"
            },
            {
               "abbr":"DDTC",
               "name":"Directorate of Defense Trade Controls",
               "org":"U.S. Department of State"
            },
            {
               "abbr":"ISN",
               "name":"Bureau of International Security and Non-Proliferation",
               "org":"U.S. Department of State"
            }
         ],
         "lists":[
            {
               "abbr":"DTC",
               "title":"AECA/ITAR Debarred",
               "agency":"Directorate of Defense Trade Controls",
               "agency_abbr":"DDTC",
               "organization":"U.S. Department of State",
               "results":[
                  {
                     "listed_at":null,
                     "entity_name":"Gia An Du",
                     "entity_aliases":[
                        "Anthony Huynh",
                        "Simon Du",
                        "Gia Simon Du"
                     ],
                     "agency_list_url":"http://bit.ly/307FuRQ",
                     "agency_information_url":"http://bit.ly/307FuRQ"
                  }
               ]
            }
         ]
      }
   }
}
{
    "event": "kyb.verification.error",
    "business_id": "002e0f0e-e39d-4351-876c-afcad30d9c37",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00"
}

Retrieving the KYB status

To retrieve the KYB status of a business, use the GET /businesses/{business_id}/verification-kyb operation with no further parameters.

An example of a KYB status retrieval request is shown below.

curl --request GET \
  --url https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Identity: YOUR-IDENTITY'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'

response = http.request(request)
puts response.read_body
const options = {
  method: 'GET',
  headers: {
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  }
};

fetch('https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb"

headers = {
  'Identity': YOUR-IDENTITY,
  'Authorization': YOUR-AUTHORIZATION,
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

print(response.text.encode('utf8'))
import requests

url = "https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb"

headers = {
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("GET", url, headers=headers)

print(response.text)
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/businesses/002e0f0e-e39d-4351-876c-afcad30d9c37/verification-kyb")
  .get()
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

Response response = client.newCall(request).execute();

The response includes the overall status of the KYB and the KYB findings, as shown in the example below.

{
     "business_id":"002e0f0e-e39d-4351-876c-afcad30d9c37",
        "kyb_status":"warning",
        "business_info":{
        "object":"business",
        "id":"09352413-7c86-4f93-bfbc-4d1a400f3586",
        "external_id":"002e0f0e-e39d-4351-876c-afcad30d9c37",
        "name":"Gold Coffee",
        "created_at":"2021-06-28T09:15:49.306Z",
        "updated_at":"2021-06-28T09:15:49.306Z",
        "status":"open"
        "tags":[]
        "requester":{...}
        "assignee_id":NULL,
        "review":NULL,
        "tin":{...}
        "business_batch_id":NULL,
        "formation":NULL,
        "website":{...}
        "watchlist":NULL,
        "bankruptcies":[]
        "certifications":[]
        "documents":[]
        "names":[]
        "addresses":[...]
        "people":[...]
        "phone_numbers":[...]
        "profiles":[]
        "registrations":[]
        "orders":[...]
        "industry_classification":NULL,
        "tax_exempt_organization":NULL,
        "fmcsa_registrations":[]
}
}

For a complete specification and interactive examples, see Retrieving the KYB status in the Bond API Reference.

Testing in the sandbox

You can use the ein and legal_business_name properties of a Business resource to trigger various KYB events in the sandbox environment, as shown in the table below.

Mock event

Business resource

kyb.verification.warning

{
"ein": "11-0000099"
}

kyb.verification.rejected

{
"ein": "11-0000099",
"legal_business_name": "Unregistered Business"
}

kyb.verification.approved

Any


Did this page help you?