Creating a business resource

business object

To create a Business resource, use the POST /businesses operation and provide parameters, as shown in the table below.

▶ Run in Postman

ParameterTypeDescription
einstringUnique type of tax identification number used to identify the business with the IRS.
legal_business_name
required
stringLegal name of the business.
dba_business_namestringAlphanumeric, "doing business as" name (trade name).
business_typestringValid values are one of:
  • cooperative
  • corporation
  • limited_liability_company
  • limited_partnership
  • partnership
  • sole_proprietorship
date_establisheddateDate of incorporation in YYYY-MM-DD format, for example 2021-06-28
phonestringBusiness phone number with or without hyphens.
emailstringBusiness contact email address.
websitestringThe official website of the business
addresses
required
arrayArray of one or more physical or mailing addresses (see addresses Object table below).
beneficial_owners arrayArray of one or more beneficial owners (see beneficial_owners Object table below).

addresses array

The addresses array is within the Business object and has the following structure.

ParametersTypeDescription
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
stringCity name, freeform 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.
Note: This field is deprecated.

beneficial_owners array

The beneficial_owners array is within the Business object and has the following structure.

ParametersType (* 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 Addresses array table above.

Example request

An example of a request to create a business resource is shown below.

curl --request POST \
     --url https://sandbox.bond.tech/api/v0.1/businesses \
     --header 'Accept: application/json' \
     --header 'Authorization: <YOUR_AUTHENTICATION>' \
     --header 'Content-Type: application/json' \
     --header 'Identity: <YOUR_IDENTITY>' \
     --data '
{
     "addresses": [
          {
               "address_type": "MAILING",
               "street": "345 California Ave.",
               "street2": "Suite 600",
               "city": "San Francisco",
               "state": "CA",
               "zip_code": "12345-1234",
               "country": "US",
               "is_primary": true
          }
     ],
     "beneficial_owners": [
    {
        "first_name": "James",
        "last_name": "Bond",
        "dob": "1970-12-12",
        "addresses": [
        {
            "address_type": "MAILING",
            "street": "345 California Ave.",
            "street2": "Suit 600",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "12345-1234",
            "country": "US",
            "is_primary": true
        }
        ]
    },
    {
        "first_name": "Le",
        "last_name": "Chiffre",
        "dob": "1980-04-04",
        "addresses": [
        {
            "address_type": "MAILING",
            "street": "345 California Ave.",
            "street2": "Suit 600",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "12345-1234",
            "country": "US",
            "is_primary": true
        }
        ]
    }
    ],
     "ein": "12-1234567",
     "legal_business_name": "John Doe Business Corporation",
     "dba_business_name": "John Doe & Co.",
     "business_type": "limited_liability_company",
     "phone": "+14157485052",
     "email": "[email protected]",
     "website": "www.business.com"
}
'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0.1/businesses")

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

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Identity"] = '<YOUR_IDENTITY>'
request["Authorization"] = 'YOUR-AUTHENTICATION'
request.body = "{\"addresses\":[{\"address_type\":\"MAILING\",\"street\":\"345 California Ave.\",\"street2\":\"Suite 600\",\"city\":\"San Francisco\",\"state\":\"CA\",\"zip_code\":\"12345-1234\",\"country\":\"US\",\"is_primary\":true}],\"ein\":\"12-1234567\",\"legal_business_name\":\"John Doe Business Corporation\",\"dba_business_name\":\"John's\",\"business_type\":\"limited_liability_company\",\"date_established\":\"2020-01-01T00:00:00.000Z\",\"phone\":\"+14157485052\",\"email\":\"[email protected]\",\"website\":\"www.business.com\"}"

response = http.request(request)
puts response.read_body
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Identity: '<YOUR_IDENTITY>',
    Authorization: 'YOUR-AUTHENTICATION'
  },
  body: JSON.stringify({
    addresses: [
      {
        address_type: 'MAILING',
        street: '345 California Ave.',
        street2: 'Suite 600',
        city: 'San Francisco',
        state: 'CA',
        zip_code: '12345-1234',
        country: 'US',
        is_primary: true
      }
    ],
    ein: '12-1234567',
    legal_business_name: 'John Doe Business Corporation',
    dba_business_name: 'John\'s',
    business_type: 'limited_liability_company',
    date_established: '2020-01-01T00:00:00.000Z',
    phone: '+14157485052',
    email: '[email protected]',
    website: 'www.business.com'
  })
};

fetch('https://sandbox.bond.tech/api/v0.1/businesses', 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"

payload = {
    "addresses": [
        {
            "address_type": "MAILING",
            "street": "345 California Ave.",
            "street2": "Suite 600",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "12345-1234",
            "country": "US",
            "is_primary": True
        }
    ],
    "ein": "12-1234567",
    "legal_business_name": "John Doe Business Corporation",
    "dba_business_name": "John's",
    "business_type": "limited_liability_company",
    "date_established": "2020-01-01T00:00:00.000Z",
    "phone": "+14157485052",
    "email": "[email protected]",
    "website": "www.business.com"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Identity": "<YOUR_IDENTITY>",
    "Authorization": "YOUR-AUTHENTICATION"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0.1/businesses");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "<YOUR_IDENTITY>");
request.AddHeader("Authorization", "YOUR-AUTHENTICATION");
request.AddParameter("application/json", "{\"addresses\":[{\"address_type\":\"MAILING\",\"street\":\"345 California Ave.\",\"street2\":\"Suite 600\",\"city\":\"San Francisco\",\"state\":\"CA\",\"zip_code\":\"12345-1234\",\"country\":\"US\",\"is_primary\":true}],\"ein\":\"12-1234567\",\"legal_business_name\":\"John Doe Business Corporation\",\"dba_business_name\":\"John's\",\"business_type\":\"limited_liability_company\",\"date_established\":\"2020-01-01T00:00:00.000Z\",\"phone\":\"+14157485052\",\"email\":\"[email protected]\",\"website\":\"www.business.com\"}", 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.\",\"street2\":\"Suite 600\",\"city\":\"San Francisco\",\"state\":\"CA\",\"zip_code\":\"12345-1234\",\"country\":\"US\",\"is_primary\":true}],\"ein\":\"12-1234567\",\"legal_business_name\":\"John Doe Business Corporation\",\"dba_business_name\":\"John's\",\"business_type\":\"limited_liability_company\",\"date_established\":\"2020-01-01T00:00:00.000Z\",\"phone\":\"+14157485052\",\"email\":\"[email protected]\",\"website\":\"www.business.com\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0.1/businesses")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "<YOUR_IDENTITY>")
  .addHeader("Authorization", "YOUR-AUTHENTICATION")
  .build();

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

The JSON response contains all the information related to the newly created business. It also returns the new business_id which is a unique Bond identifier for the business. The business_id is used in subsequent API calls to retrieve and update the business resource, initiate KYB, and issue cards.

An example of a 201 response to a successful business creation request is shown below.

{
    "date_created": "2022-12-20T13:51:14.711080+00:00",
    "addresses": [
        {
            "date_created": "2022-12-20T13:51:14.716179+00:00",
            "address_id": "6229590e-544a-4a76-842c-e3cf3d35b750",
            "address_type": "MAILING",
            "street": "345 California Ave.",
            "street2": "Suite 600",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "12345-1234",
            "country": "US",
            "is_primary": true
        }
    ],
    "beneficial_owners": [
        {
            "date_created": "2022-12-20T13:51:14.713557+00:00",
            "addresses": [
                {
                    "date_created": "2022-12-20T13:51:14.717783+00:00",
                    "address_id": "af9de206-8643-4d77-9fbb-7bdd2fe5f80f",
                    "address_type": "MAILING",
                    "street": "345 California Ave.",
                    "street2": "Suit 600",
                    "city": "San Francisco",
                    "state": "CA",
                    "zip_code": "12345-1234",
                    "country": "US",
                    "is_primary": true
                }
            ],
            "beneficial_owner_id": "2630058d-b9e4-4d73-a335-aba4d111b466",
            "first_name": "James",
            "middle_name": null,
            "last_name": "Bond",
            "dob": "1970-12-12",
            "ssn": null,
            "phone": null,
            "email": null
        },
        {
            "date_created": "2022-12-20T13:51:14.714869+00:00",
            "addresses": [
                {
                    "date_created": "2022-12-20T13:51:14.719143+00:00",
                    "address_id": "df4d21b1-0e55-4b05-899d-f3c68d3e328e",
                    "address_type": "MAILING",
                    "street": "345 California Ave.",
                    "street2": "Suit 600",
                    "city": "San Francisco",
                    "state": "CA",
                    "zip_code": "12345-1234",
                    "country": "US",
                    "is_primary": true
                }
            ],
            "beneficial_owner_id": "b4183240-ecb0-4568-9531-5078a35c752c",
            "first_name": "Le",
            "middle_name": null,
            "last_name": "Chiffre",
            "dob": "1980-04-04",
            "ssn": null,
            "phone": null,
            "email": null
        }
    ],
    "business_id": "bf8fad28-5a93-4340-b67b-d80df9e7234e",
    "ein": "12-1234567",
    "legal_business_name": "John Doe Business Corporation",
    "dba_business_name": "John Doe & Co.",
    "business_type": "limited_liability_company",
    "date_established": null,
    "phone": "+14157485052",
    "email": "[email protected]",
    "website": "www.business.com"
}

For a complete specification and interactive examples, see Create a business in the Bond API Reference.

When missing a field

If you try to create a business with a missing field, you receive a JSON response similar to the example shown below.

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