Guides

Creating Beneficial Owners

How to create a Beneficial Owner and how to add their details to the system.

Suggest Edits

A business must have one or more Beneficial Owners. To add a Beneficial Owner to a Business, use the POST /businesses/{business_id}/beneficial_owners operation and provide parameters as shown in the table below.

▶ Run in Postman

ParameterType (* Required)Description
dob
required		stringDate of birth in YYYY-MM-DD format, for example 1978-06-20.
first_name
required		stringFirst name, between 1 and 20 characters. Must start with a letter and can only contain letters, spaces, and apostrophes.
middle_namestringMiddle name, between 1 and 20 characters. Must start with a letter and can only contain letters, spaces, and apostrophes.
last_name
required		stringLast name, between 2 and 20 characters. Must start with a letter and can only contain letters, spaces, and apostrophes.
addresses
partially required		arrayOne or more official addresses, see table below.

The addresses array within business_id has the following structure.

address ObjectTypeDescription
address_type
required		stringEither MAILING or PHYSICAL.
street
required		stringFreeform name between 1 and 40 characters. May contain only alphanumeric and these special characters . , _ - #
street2stringFreeform name, maximum 40 characters.
city
required		stringFreeform name between 2 and 20 characters.
state
required		stringTwo-character US state code. Non-US state code maximum 20 characters.
zip_code
required		stringFive-digit US zip code, (for example 12345) or nine-digit US zip code, (for example 12345-1234).
Non-US state code between 2 and 20 characters.
country
required		stringISO 3166-1 alpha-2 country code, maximum two characters.
is_primary
required		booleanIs this the primary address; either true or false.

An example of a request to create a Beneficial Owner of a business is shown in the example below. 

curl --request POST \
  --url https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Content-Type: application/json' \
  --header 'Identity: YOUR-IDENTITY' \
  --data '
{
  "addresses": [
    {
      "address_type": "PHYSICAL",
      "street": "5 California Ave.",
      "street2": "Suit 770",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "12345-1234",
      "country": "US",
      "is_primary": true
    }
  ],
  "dob": "1992-03-23",
  "first_name": "Boris",
  "middle_name": "Jim",
  "last_name": "Pasakovitch"
}

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"addresses\":[{\"address_type\":\"PHYSICAL\",\"street\":\"5 California Ave.\",\"street2\":\"Suit 770\",\"city\":\"San Francisco\",\"state\":\"CA\",\"zip_code\":\"12345-1234\",\"country\":\"US\",\"is_primary\":true}],\"dob\":\"1992-03-23\",\"first_name\":\"Boris\",\"middle_name\":\"Jim\",\"last_name\":\"Pasakovitch\"}"

response = http.request(request)
puts response.read_body

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({
    addresses: [
      {
        address_type: 'PHYSICAL',
        street: '5 California Ave.',
        street2: 'Suit 770',
        city: 'San Francisco',
        state: 'CA',
        zip_code: '12345-1234',
        country: 'US',
        is_primary: true
      }
    ],
    dob: '1992-03-23',
    first_name: 'Boris',
    middle_name: 'Jim',
    last_name: 'Pasakovitch'
  })
};

fetch('https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners', 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/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners"

payload = {
    "addresses": [
        {
            "address_type": "PHYSICAL",
            "street": "5 California Ave.",
            "street2": "Suit 770",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "12345-1234",
            "country": "US",
            "is_primary": True
        }
    ],
    "dob": "1992-03-23",
    "first_name": "Boris",
    "middle_name": "Jim",
    "last_name": "Pasakovitch"
}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"addresses\":[{\"address_type\":\"PHYSICAL\",\"street\":\"5 California Ave.\",\"street2\":\"Suit 770\",\"city\":\"San Francisco\",\"state\":\"CA\",\"zip_code\":\"12345-1234\",\"country\":\"US\",\"is_primary\":true}],\"dob\":\"1992-03-23\",\"first_name\":\"Boris\",\"middle_name\":\"Jim\",\"last_name\":\"Pasakovitch\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"addresses\":[{\"address_type\":\"PHYSICAL\",\"street\":\"5 California Ave.\",\"street2\":\"Suit 770\",\"city\":\"San Francisco\",\"state\":\"CA\",\"zip_code\":\"12345-1234\",\"country\":\"US\",\"is_primary\":true}],\"dob\":\"1992-03-23\",\"first_name\":\"Boris\",\"middle_name\":\"Jim\",\"last_name\":\"Pasakovitch\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

A successful response contains all the information related to the new Beneficial Owner in a JSON file. It also includes a beneficial_owner_id which is the unique Bond Studio identifier for the Beneficial Owner that must be provided in API calls, such as when initiating a KYC request.

An example of a response to a successful request to add a Beneficial Owner is shown below.

{
  "beneficial_owner_id": "12345678-5d05-4562-a5e3-e61e12345678",
  "first_name": "William",
  "last_name": "Pasakovitch",
  "date_created": "2021-05-24T14:15:22Z",
  "dob": "1999-10-10",
  "address": [
    {
        "date_created":"2021-05-24T14:15:22Z",
        "address_id": "12374791-5d05-4e3e-a5e3-e61e3817622134",
        "address_type": "PHYSICAL",
        "street": "770 California St.",
        "street2": "Suit 333",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94104-2657",
        "country": "US",
        "is_primary": true,
        "deliverability": "deliverable"
    }
  ]
}

For a complete specification and interactive examples, see Creating a Beneficial Owner in the Bond API Reference.

To manage Beneficial Owners, see Managing Beneficial Owners.

Trying to add a Beneficial Owner with a missing field

If you try to add a Beneficial Owner with a missing field, you receive a JSON response similar to that shown below. 

{
     'Message': "{'last_name': ['Missing data for required field.']}",
      'Status': 400,
      'Code': 'create_beneficial_owner_schema',
      'Type': 'Request Error'
}

Updated over 2 years ago

Next Steps