Managing Beneficial Owners

Use the operations below to manage Beneficial Owners.

Retrieving Beneficial Owners

To retrieve a single Beneficial Owner, use the GET /businesses/{business_id}/beneficial_owners/{beneficial_owner_id} operation with no other parameters, as shown in the example below.

curl --request GET \
  --url https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/4943fc81-e7e8-43b5-8be6-9c43fcec505a \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Identity: YOUR-IDENTITY'

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

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

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/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38', 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/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38"

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

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

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38");
var request = new RestRequest(Method.GET);
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/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38")
  .get()
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

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

{
    "beneficial_owner_id":"4943fc81-e7e8-43b5-8be6-9c43fcec505a",
    "first_name":"David",
    "last_name":"Letterman",
    "date_created":"2019-08-24T14:15:22Z",
    "date_updated":"2019-08-24T14:15:22Z",
    "dob": "1999-10-10",
    "address":[
        {
            "date_created":"2019-08-24T14:15:22Z",
            "date_updated":"2019-08-24T14:15:22Z",
            "address_id":"12348579-5d05-4e3e-a5e3-e61e3a5b1234",
            "address_type":"MAILING",
            "street":"345 California Ave.",
            "street2":"Suit 600",
            "city":"San Francisco",
            "state":"CA",
            "zip_code":"12345-1234",
            "country":"US",
            "is_primary":true,
            "deliverability":"deliverable"
        }
    ]
}

To retrieve all Beneficial Owners, use the GET /businesses/{business_id}/beneficial_owners operation with no further parameters, as shown in the example below.

curl --request GET \
  --url https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Identity: YOUR-IDENTITY'

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::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/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"

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

response = requests.request("GET", url, 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.GET);
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/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners")
  .get()
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

An example of a successful request to retrieve all Beneficial Owners for a business is shown below.

{
   "page_info":{
      "page_size":2,
      "page":1,
      "pages":1
   },
   "data":[
      {
         "beneficial_owner_id":"4943fc81-e7e8-43b5-8be6-9c43fcec505a",
         "first_name":"David",
         "last_name":"Letterman",
         "date_created":"2019-08-24T14:15:22Z",
         "date_updated":"2019-08-24T14:15:22Z",
         "dob": "1999-10-10",
         "address":[
            {
               "address_id":"12348579-5d05-4e3e-a5e3-e61e3a5b1234",
               "address_type":"MAILING",
               "street":"345 California Ave.",
               "street2":"Suit 600",
               "city":"San Francisco",
               "state":"CA",
               "zip_code":"12345-1234",
               "country":"US",
               "is_primary":true,
               "deliverability":"deliverable"
            }
         ]
      },
      {
         "beneficial_owner_id":"29ec6db6-4e12-4521-8ba7-7afc5c4730dd",
         "first_name":"Conan",
         "last_name":"O'Brian",
         "date_created":"2019-08-24T14:15:22Z",
         "date_updated":"2019-08-24T14:15:22Z",
         "dob": "1989-01-01",
         "address":[
            {
               "address_id":"12348579-5d05-4e3e-a5e3-e61e3a5b1234",
               "address_type":"MAILING",
               "street":"345 California Ave.",
               "street2":"Suit 600",
               "city":"San Francisco",
               "state":"CA",
               "zip_code":"12345-1234",
               "country":"US",
               "is_primary":true,
               "deliverability":"deliverable"
            }
         ]
      }
   ]
}

For a complete specification and interactive examples, see Retrieving Beneficial Owners.

Deleting a Beneficial Owner

To delete a Beneficial Owner, use the DELETE /businesses/{business_id}/beneficial_owners/{beneficial_owner_id} operation with no other parameters, as shown in the example below.

curl --request DELETE \
  --url https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38 \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Identity: YOUR-IDENTITY'

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

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

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

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

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

const options = {
  method: 'DELETE',
  headers: {
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  }
};

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

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

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

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0/businesses/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38");
var request = new RestRequest(Method.DELETE);
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/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38/beneficial_owners/96df8579-5d05-4e3e-a5e3-e61e3a5bdb38")
  .delete(null)
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

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

{
    "beneficial_owner_id":"4943fc81-e7e8-43b5-8be6-9c43fcec505a",
    "first_name":"David",
    "last_name":"Letterman",
    "date_created":"2019-08-24T14:15:22Z",
    "date_deleted":"2019-10-24T14:15:22Z",
    "dob": "1999-10-10",
    "address":[
        {
            "date_created":"2019-08-24T14:15:22Z",
            "date_deleted":"2019-10-24T14:15:22Z",
            "address_id":"12348579-5d05-4e3e-a5e3-e61e3a5b1234",
            "address_type":"MAILING",
            "street":"345 California Ave.",
            "street2":"Suit 600",
            "city":"San Francisco",
            "state":"CA",
            "zip_code":"12345-1234",
            "country":"US",
            "is_primary":true,
            "deliverability":"deliverable"
        }
    ]
}

For a complete specification and interactive examples, see Deleting a Beneficial Owner.

Updating a Beneficial Owner

To update a Beneficial Owner, use the PATCH /businesses/{business_id}/beneficial_owners/{beneficial_owner_id} operation and provide the relevant parameters, as shown in the table below.

Parameter	Type	Description
`dob`	string	Date of birth in `YYYY-MM-DD` format, for example `1978-06-20`.
`first_name`	string	First name, between 1 and 20 characters. Must start with a letter and can only contain letters, spaces, and apostrophes.
`middle_name`	string	Middle name, between 1 and 20 characters. Must start with a letter and can only contain letters, spaces, and apostrophes.
`last_name`	string	Last name, between 2 and 20 characters. Must start with a letter and can only contain letters, spaces, and apostrophes.

An example of a request to update a Beneficial Owner is shown below.

curl --request PATCH \
  --url https://sandbox.bond.tech/api/v0/businesses/4943fc81-e7e8-43b5-8be6-9c43fcec505a/beneficial_owners/12348579-5d05-4e3e-a5e3-e61e3a5b1234 \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Content-Type: application/json' \
  --header 'Identity: YOUR-IDENTITY'

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

url = URI("https://sandbox.bond.tech/api/v0/businesses/4943fc81-e7e8-43b5-8be6-9c43fcec505a/beneficial_owners/12348579-5d05-4e3e-a5e3-e61e3a5b1234")

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

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'

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

const options = {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  }
};

fetch('https://sandbox.bond.tech/api/v0/businesses/4943fc81-e7e8-43b5-8be6-9c43fcec505a/beneficial_owners/12348579-5d05-4e3e-a5e3-e61e3a5b1234', 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/4943fc81-e7e8-43b5-8be6-9c43fcec505a/beneficial_owners/12348579-5d05-4e3e-a5e3-e61e3a5b1234"

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

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

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0/businesses/4943fc81-e7e8-43b5-8be6-9c43fcec505a/beneficial_owners/12348579-5d05-4e3e-a5e3-e61e3a5b1234");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
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/4943fc81-e7e8-43b5-8be6-9c43fcec505a/beneficial_owners/12348579-5d05-4e3e-a5e3-e61e3a5b1234")
  .patch(null)
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

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

{
    "beneficial_owner_id":"4943fc81-e7e8-43b5-8be6-9c43fcec505a",
    "first_name":"David",
    "last_name":"Letterman",
    "date_created":"2019-08-24T14:15:22Z",
    "date_updated":"2019-18-24T14:15:22Z",
    "dob": "1999-10-10",
    "address":[
        {
            "address_id":"12348579-5d05-4e3e-a5e3-e61e3a5b1234",
            "address_type":"MAILING",
            "street":"345 California Ave.",
            "street2":"Suit 600",
            "city":"San Francisco",
            "state":"CA",
            "zip_code":"12345-1234",
            "country":"US",
            "is_primary":true,
            "deliverability":"deliverable"
        }
    ]
}

For a complete specification and interactive examples, see Updating a Beneficial Owner.