Guides

Managing customers

How to retrieve, delete, and update existing customers.

Suggest Edits

Use the operations shown below to manage customers.

Retrieving customers

To retrieve all customers, use the GET /customers operation and provide the optional query parameters from the table below.

Query parameterTypeDescription
pageint32The required page number to return.
per_pageint32Number of customers to return per page. One of: 1, 2, 5, 10, 20, 50

An example of a request to retrieve all customers is shown below.

curl --request GET \
     --url 'https://sandbox.bond.tech/api/v0/customers?page=1&per_page=5' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'

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

url = URI("https://sandbox.bond.tech/api/v0/customers?page=1&per_page=5")

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/customers?page=1&per_page=5', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.bond.tech/api/v0/customers"

querystring = {"page":"1","per_page":"5"}

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

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

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0/customers?page=1&per_page=5");
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/customers?page=1&per_page=5")
  .get()
  .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 retrieve all customers is shown below.

[
    {
        "customer_id": "5fec3f30-dc2e-4b20-9e07-53c31400bbe3",
        "bond_brand_id": "807b0f2a-7193-4629-af07-848087d454ef",
        "brand_person_id": "deb1af0f-c7b1-4d6b-882d-d0ba6116a080",
        "date_created": "2021-10-26T00:31:05.378083+00:00",
        "dob": "1990-01-01",
        "first_name": "Alice",
        "middle_name": "",
        "last_name": "Smith",
        "kyc_requests_available": 3,
        "addresses": [
            {
                "address_id": "5f0da597-c5d3-4c10-9120-d6efc0b9cb09",
                "address_type": "PHYSICAL",
                "street": "345 California Ave.",
                "street2": "Suit 600",
                "city": "San Francisco",
                "state": "CA",
                "zip_code": "12345-1234",
                "country": "US",
                "is_primary": true,
                "deliverability": "undeliverable",
                "date_created": "2021-10-26T00:31:05.380693+00:00"
            }
        ],
        "business_id": null
    },
    {
        "customer_id": "41223669-ec23-4459-917b-cebe34978e19",
        "bond_brand_id": "807b0f2a-7193-4629-af07-848087d454ef",
        "brand_person_id": "deb1af0f-c7b1-4d6b-882d-d0ba6116a080",
        "date_created": "2021-10-26T00:47:47.504240+00:00",
        "dob": "1990-01-01",
        "first_name": "Alice",
        "middle_name": "",
        "last_name": "Smith",
        "kyc_requests_available": 3,
        "addresses": [
            {
                "address_id": "1830dacb-3a82-4412-86fe-b909d12b96a7",
                "address_type": "PHYSICAL",
                "street": "345 California Ave.",
                "street2": "Suit 600",
                "city": "San Francisco",
                "state": "CA",
                "zip_code": "12345-1234",
                "country": "US",
                "is_primary": true,
                "deliverability": "undeliverable",
                "date_created": "2021-10-26T00:47:47.506598+00:00"
            }
        ],
        "business_id": null
    }
]

To retrieve a single customer, use the GET /customers/{customer_id} operation with no other parameters, as shown in the example below.

curl --request GET \
     --url https://sandbox.bond.tech/api/v0/customers/931e2341-c3eb-4681-97d4-f6e09d90da14 \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'

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

url = URI("https://sandbox.bond.tech/api/v0/customers/931e2341-c3eb-4681-97d4-f6e09d90da14")

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/customers/931e2341-c3eb-4681-97d4-f6e09d90da14', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.bond.tech/api/v0/customers/931e2341-c3eb-4681-97d4-f6e09d90da14"

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/customers/931e2341-c3eb-4681-97d4-f6e09d90da14");
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/customers/931e2341-c3eb-4681-97d4-f6e09d90da14")
  .get()
  .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 retrieve a customer is shown below.

{
       "customer_id":"931e2341-c3eb-4681-97d4-f6e09d90da14",
       "bond_brand_id":"e0cb152c-51dc-44b0-af3c-5c68341068da",
       "brand_person_id":"8dd4e2de-33be-4bb3-9a19-25069033a5e2",
       "date_created":"2021-02-11T13:26:50.553841+00:00"
       "dob":"1961-03-03",
       "first_name":"sam",
       "middle_name":"amazed",
       "last_name":"smith",
       "kyc_requests_available":3,
       "addresses":[{
              "address_id":"ea1c9454-aa65-46d7-b644-aa757bdc7b2c",
              "address_type":"PHYSICAL",
              "street":"345 California st",
              "street2":"Suit 6002",
              "city":"San Francisco",
              "state":"CA",
              "zip_code":"12345-1234",
              "country":"US",
              "is_primary":true,
              "deliverability":"undeliverable",
              "date_created":"2021-02-11T13:26:50.563963+00:00"
           }
    ],
    "business_id": null
}

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

Deleting a customer

To delete a customer, use the DELETE /customers/{customer_id} operation with no other parameters, as shown in the example below.

curl --request DELETE \
     --url https://sandbox.bond.tech/api/v0/customers/931e2341-c3eb-4681-97d4-f6e09d90da14 \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'

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

url = URI("https://sandbox.bond.tech/api/v0/customers/931e2341-c3eb-4681-97d4-f6e09d90da14")

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/customers/931e2341-c3eb-4681-97d4-f6e09d90da14', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.bond.tech/api/v0/customers/931e2341-c3eb-4681-97d4-f6e09d90da14"

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/customers/931e2341-c3eb-4681-97d4-f6e09d90da14");
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/customers/931e2341-c3eb-4681-97d4-f6e09d90da14")
  .delete(null)
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

If the request is successful, you receive the following response:
Customer resource deleted

For a complete specification and interactive examples, see Deleting a customer in the Bond API Reference.

Updating a customer

Most customer details can't be updated after they've passed KYC as the new information needs to be verified before the update can occur.

📘

Note

Only email_address, phone_number, and any secondary addresses can be updated after a customer has passed KYC.

Other fields require additional information to be confirmed. If you need to update information for a customer that has passed KYC, contact Bond directly.

To update a customer that has not yet passed KYC, use the PATCH /customers/{customer_id} operation and provide the relevant, optional parameters that you want to update, as shown in the table below.

ParameterTypeDescription
brand_person_idstringCustomer ID in UUID format provided by your brand.
dobdateBirthday in YYYY-MM-DD format, for example 1994-03-20.
first_namestringFirst name, between 2 and 50 characters. Must start with a letter and can only be letters, spaces, and apostrophes.
middle_namestringMiddle name, between 2 and 50 characters. Must start with a letter and can only be letters, spaces, and apostrophes.
last_namestringLast name, between 2 and 50 characters. Must start with a letter and can only be letters, spaces, and apostrophes.
addresses
At least one primary address required		arrayArray of one or more physical or mailing addresses (see address Object table below).

The addresses array within customer_id has the following structure.

address ObjectTypeDescription
address_id
required		stringAddress ID in UUID format corresponding to the address to be updated.
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 40 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 update a customer's state is shown below.

curl --request PATCH \
     --url https://sandbox.bond.tech/api/v0/customers/customer_id \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "addresses": [
          {
               "address_type": "MAILING",
               "street": "345 California Ave.",
               "state": "WA"
          }
     ]
}

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

url = URI("https://sandbox.bond.tech/api/v0/customers/customer_id")

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'
request.body = "{\"addresses\":[{\"address_type\":\"MAILING\",\"street\":\"345 California Ave.\",\"state\":\"WA\"}]}"

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

const options = {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({
    addresses: [{address_type: 'MAILING', street: '345 California Ave.', state: 'WA'}]
  })
};

fetch('https://sandbox.bond.tech/api/v0/customers/customer_id', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.bond.tech/api/v0/customers/customer_id"

payload = {"addresses": [
        {
            "address_type": "MAILING",
            "street": "345 California Ave.",
            "state": "WA"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

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

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0/customers/customer_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"addresses\":[{\"address_type\":\"MAILING\",\"street\":\"345 California Ave.\",\"state\":\"WA\"}]}", 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\":\"MAILING\",\"street\":\"345 California Ave.\",\"state\":\"WA\"}]}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/customers/customer_id")
  .patch(body)
  .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 customer is shown below.

{
       "customer_id":"931e2341-c3eb-4681-97d4-f6e09d90da14",
       "bond_brand_id":"e0cb152c-51dc-44b0-af3c-5c68341068da",
       "brand_person_id":"8dd4e2de-33be-4bb3-9a19-25069033a5e2",
       "date_created":"2021-02-11T13:26:50.553841+00:00"
       "dob":"1961-03-03",
       "first_name":"sam",
       "middle_name":"amazed",
       "last_name":"McKorkindale",
       "kyc_requests_available":3,
       "addresses":[...]
}

For a complete specification and interactive examples, see Updating a customer in the Bond API Reference.

Updated over 2 years ago

Next Steps