Managing Beneficial Owners

How to retrieve, delete, and update existing Beneficial Owners.

Suggest Edits

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.1/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.1/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.1/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.1/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.1/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.1/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": "12345678-5d05-4562-a5e3-e61e12345678",
  "first_name": "New",
  "last_name": "Owner",
  "date_created": "2019-08-24T14:15:22Z",
  "dob": "1999-10-10",
  "address": [
    {
      "date_created": "2019-08-24T14:15:22Z",
      "address_id": "12374791-5d05-4e3e-a5e3-e61e3817622134",
      "address_type": "PHYSICAL",
      "street": "345 California St.",
      "street2": "Suite 600",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94104-2657",
      "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.1/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.1/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.1/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.1/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.1/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.1/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:22.000Z",
      "date_updated": "2019-08-24T14:15:22.000Z",
      "dob": "1980-04-04",
      "address": [
        {
          "address_id": "12348579-5d05-4e3e-a5e3-e61e3a5b1234",
          "address_type": "MAILING",
          "street": "345 California Ave.",
          "street2": "Suite 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:22.000Z",
      "date_updated": "2019-08-24T14:15:22.000Z",
      "dob": "1980-04-04",
      "address": [
        {
          "address_id": "12348579-5d05-4e3e-a5e3-e61e3a5b1234",
          "address_type": "MAILING",
          "street": "345 California Ave.",
          "street2": "Suite 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.

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.

ParameterTypeDescription
dobstringDate of birth in YYYY-MM-DD format, for example 1978-06-20.
first_namestringFirst 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_namestringLast 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.1/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.1/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.1/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.1/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.1/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.1/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.

{
  "first_name": "New",
  "last_name": "Owner",
  "dob": "1999-10-10",
  "address": [
    {
      "address_type": "PHYSICAL",
      "street": "345 California St.",
      "street2": "Suite 600",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94104-2657",
      "country": "US",
      "is_primary": true
    }
  ]
}

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

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.1/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.1/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.1/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.1/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.1/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.1/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":"Suite 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.

Updated over 1 year ago

Next Steps