DOCS
Support

Marqeta Home

/
Guides
Core API Reference
DiVA API Reference
Core API Explorer

40 minute read

November 10, 2020

Businesses

A business is a type of account holder that cannot directly hold cards, but can have parent/child relationships with card-holding users. A business can monitor and control card use by a specified group of users. Every business has a general purpose account (GPA).

For information on how to create a user that has a child-to-parent hierarchical relationship to the business, see Create User.

Note
A user can simultaneously be a child of a business and a parent of other users if the user is not configured to use the parent’s account balances and the user’s children are configured to use the parent’s account balances.

Create business
Copy section link

Action: POST
Endpoint: /businesses

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a business. The initial status of a newly created business depends on the Know Your Customer (KYC) requirements of the program or associated account holder group.

KYC Required Initial Business State Business Active on Creation Business Limitations

Always

UNVERIFIED

No

Cannot load funds.

Conditionally

LIMITED

No

Restricted by rules in accountholdergroups.pre_kyc_controls.

Never

ACTIVE

Required

None.

To change or track the history of a business' status, use the /businesstransitions endpoint. For more information on status changes, see Create Business Transition.

For information about configuring the required fields for KYC verification, see Perform KYC.

Body field details
Copy section link

Fields Description

token

string
Optional

The unique identifier of the business.

If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

business_name_legal

string
Conditionally required

Legal name of business.

Note
Required for KYC verification.

Allowable Values:

255 char max

business_name_dba

string
Conditionally required

Fictitious business name ("Doing Business As" or DBA).

Note
Required for KYC verification if the fictitious business name is different from the legal business name.

Allowable Values:

255 char max

office_location

object
Conditionally required

Address of business office.

Note
Required for KYC verification. Cannot perform KYC if set to a PO Box.

Allowable Values:

Existing office_location object.

in_current_location_since

string
Optional

The date on which the business office opened in its current location.

Allowable Values:

yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

phone

string
Optional

10-digit telephone number of business.

Allowable Values:

Format: 510-555-1212 or 5105551212

website

string
Optional

URL of the business' website.

Allowable Values:

255 char max

date_established

string
Conditionally required

Date the business was established.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

general_business_description

string
Optional

General description of the business.

Allowable Values:

255 char max

history

string
Optional

History of the business.

Allowable Values:

255 char max

account_holder_group_token

string
Optional

Associates the specified account holder group with the business.

Allowable Values:

Existing account holder group token.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

ip_address

string
Optional

The IP address of the business.

Allowable Values:

39 char max

notes

string
Optional

Any additional information pertaining to the business.

Allowable Values:

255 char max

business_type

string
Optional

Indicates the type of business, for example B2B (business-to-business) or B2C (business-to-consumer).

Allowable Values:

255 char max

international_office_locations

string
Optional

The locations of the business' offices outside the US.

Allowable Values:

255 char max

primary_contact

object
Optional

Describes the business' primary contact.

Allowable Values:

Existing primary_contact object

duns_number

string
Optional

Data Universal Numbering System (DUNS) number of the business.

Allowable Values:

255 char max

incorporation

object
Conditionally required

Contains information about the organizational structure of the business.

Note
Required for KYC verification.

Allowable Values:

Existing incorporation object.

proprietor_or_officer

object
Conditionally required

Contains information about the proprietor or officer of the business.

Note
Required for KYC verification.

Allowable Values:

Existing proprietor_or_officer object.

metadata

object
Optional

Associates customer-injected metadata with the business.

Allowable Values:

Existing metadata object.

password

string
Optional

Password for the business account.

Allowable Values:

  • 8-20 characters

  • Must contain at least one numeral

  • Must contain at least one lowercase letter

  • Must contain at least one uppercase letter

  • Must contain at least one of these symbols: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

identifications

array
Optional

One or more objects containing identifying information about the business.

Allowable Values:

Existing identifications array.

beneficial_owner1

object
Conditionally required

Contains information about the beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

beneficial_owner2

object
Conditionally required

Contains information about the second beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a second beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

beneficial_owner3

object
Conditionally required

Contains information about the third beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a third beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

beneficial_owner4

object
Conditionally required

Contains information about the fourth beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a fourth beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

attestation_consent

boolean
Conditionally required

Indicates that the attester agrees that the information provided is correct and truthful.

Note
Required for KYC verification.

Allowable Values:

true, false

attester_name

string
Conditionally required

The name of the attester for KYC verification.

Note
Required for KYC verification.

Allowable Values:

The name of the attester. For example, Jane Smith.

attester_title

string
Optional

The title of the attester for KYC verification.

Allowable Values:

The title of the attester. For example, Chief Executive Officer.

attestation_date

string
Conditionally required

The timestamp of the attestation.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ

proprietor_is_beneficial_owner

boolean
Conditionally required

Indicates that the proprietor or officer of the business is also a beneficial owner.

Note
Required for KYC verification if the business proprietor or officer is also a beneficial owner.

Allowable Values:

true, false

Default value:
false

The office_location object
Copy section link

Fields Description

address1

string
Conditionally required

Business office’s street address.

Note
Required for KYC verification. Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Conditionally required

Additional address information.

Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

city

string
Conditionally required

Business office’s city.

Note
Required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

Business office’s state.

Note
Required for KYC verification.

Allowable Values:

35 char max

postal_code

string
Conditionally required

Business office’s postal code.

Note
Required for KYC verification.

Allowable Values:

20 char max

country

string
Conditionally required

Business office’s country.

Note
Required for KYC verification.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification. US, for example.

The primary_contact object
Copy section link

Fields Description

full_name

string
Optional

Name of primary contact.

Allowable Values:

255 char max

title

string
Optional

Title of primary contact.

Allowable Values:

255 char max

department

string
Optional

Department of primary contact.

Allowable Values:

255 char max

phone

string
Optional

Telephone number of primary contact.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

extension

string
Optional

Telephone extension of primary contact.

Allowable Values:

255 char max

fax

string
Optional

Fax number of primary contact.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

mobile

string
Optional

Mobile telephone number of primary contact.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

email

string
Optional

Email address of primary contact.

Allowable Values:

255 char max

The incorporation object
Copy section link

Fields Description

is_public

boolean
Required

A value of true indicates that the business is publicly held.

Allowable Values:

true, false

Default value:
false

incorporation_type

string
Conditionally required

The organizational structure of the business (corporation or sole proprietorship, for example).

Note
Required for KYC verification.

Allowable Values:

LLC, CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, COOPERATIVE, OTHER

stock_symbol

string
Optional

The business' stock symbol.

Allowable Values:

255 char max

state_of_incorporation

string
Conditionally required

The state in which the business is incorporated.

Note
Required for KYC verification.

Allowable Values:

255 char max

name_registered_under

string
Optional

The name under which the business is registered.

Allowable Values:

255 char max

address_registered_under

object
Conditionally required

The address under which the business is registered.

Note
Required for KYC verification.

Allowable Values:

A valid incorporation.address_registered_under object.

The incorporation.address_registered_under object
Copy section link

Fields Description

address1

string
Optional

Business' registered street address.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Optional

Business' registered city.

Allowable Values:

40 char max

state

string
Optional

Business' registered state.

Allowable Values:

35 char max

postal_code

string
Optional

Business' registered postal code.

Allowable Values:

20 char max

country

string
Optional

Business' registered country.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification.

The identifications array
Copy section link

You can add one or more objects to the identifications array. Each identification in the array must be of a different type.

Only one of the following identification types can be associated with a business:

  • Business Tax ID

  • Business Number

  • Taxpayer Reference

Fields Description

type

string
Required

The form of identification.

Note
BUSINESS_TAX_ID required for KYC verification.

Allowable Values:

BUSINESS_TAX_ID, BUSINESS_NUMBER, TAXPAYER_REFERENCE

value

string
Required

The identification number associated with the form of identification.

Allowable Values:

255 char max

expiration_date

string
Optional

The expiration date for the form of identification, if applicable.

Allowable Values:

yyyy-MM-dd

The proprietor_or_officer object
Copy section link

Fields Description

first_name

string
Required

First name of business proprietor or officer.

Allowable Values:

255 char max, no digits or single letters.

middle_name

string
Optional

Middle name of business proprietor or officer.

Allowable Values:

255 char max

last_name

string
Required

Last name of business proprietor or officer.

Allowable Values:

255 char max, no digits or single letters.

alternative_names

string
Optional

Alternate names of business proprietor or officer.

Allowable Values:

255 char max

title

string
Optional

Title of business proprietor or officer.

Allowable Values:

255 char max

home

object
Conditionally required

The business proprietor or officer’s home address.

Note
Required for KYC verification.

Allowable Values:

Existing proprietor_or_officer.home object.

dob

string
Conditionally required

Business proprietor or officer’s date of birth.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

phone

string
Optional

Telephone number of business proprietor or officer.

Allowable Values:

Format: 510-555-1212 or 5105551212

email

string
Optional

Email address of business proprietor or officer.

Allowable Values:

255 char max

identifications

array
Conditionally required

One or more objects containing identifying information about the business proprietor or officer.

Note
Required for KYC verification.

Allowable Values:

Existing proprietor_or_officer.identifications array.

The proprietor_or_officer.home object
Copy section link

Fields Description

address1

string
Conditionally required

Street address of business proprietor or officer.

Note
Required for KYC verification.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Conditionally required

City of business proprietor or officer.

Note
Required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

State in which business proprietor or officer resides.

Note
Required for KYC verification.

Allowable Values:

35 char max

postal_code

string
Conditionally required

Business proprietor or officer’s postal code.

Note
Required for KYC verification.

Allowable Values:

20 char max

country

string
Conditionally required

Country in which business proprietor or officer resides.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification. US, for example.

The proprietor_or_officer.identifications array
Copy section link

You can add one or more objects to the identifications array. Each identification in the array must be of a different type.

Only one of the following identification types can be associated with a proprietor or officer:

  • SSN – Social Security Number

  • SIN – Social Insurance Number

  • TIN – Taxpayer Identification Number

  • NIN – National Insurance Number

Fields Description

type

string
Required

The form of identification.

Note
Full SSN is required for KYC verification.

Allowable Values:

SSN, TIN, SIN, NIN

value

string
Required

The identification number associated with the form of identification.

Allowable Values:

255 char max

Note
Digits only, do not use separators. For example: 123456789

expiration_date

string
Optional

The expiration date for the form of identification, if applicable.

Allowable Values:

yyyy-MM-dd

The metadata object
Copy section link

Fields Description

customer_defined_name_01 customer_defined_name_02 …​ customer_defined_name_20

string
Optional

Associates customer-injected metadata with the business.

You can define the names and values of up to 20 fields. For example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
}

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value

The beneficial_owner object
Copy section link

The beneficial_owner object is only required if you want to run KYC validation on a company that has one or more beneficial owners.

Note
If the proprietor or officer of the business is also a beneficial owner, you only need to submit their information as the proprietor, setting the value for the proprietor_is_beneficial_owner field of the body field details of the business to true. Submitting an individual as both proprietor and beneficial owner will cause an extra KYC evaluation to be performed unnecessarily on that individual.
Fields Description

first_name

string
Required

The first name of the beneficial owner.

Allowable Values:

255 char max, no digits or single letters.

middle_name

string
Optional

The middle name of the beneficial owner.

Allowable Values:

255 char max

last_name

string
Required

The last name of the beneficial owner.

Allowable Values:

255 char max, no digits or single letters.

title

string
Optional

The title of the beneficial owner.

Allowable Values:

255 char max

home

object
Required

The home address of the beneficial owner.

Allowable Values:

Existing beneficial_owner.home object.

ssn

string
Required

The nine-digit Social Security Number of the beneficial owner.

Allowable Values:

255 char max

Note
Digits only, do not use separators. For example: 123456789

For example: 123456789

dob

string
Required

The date of birth of the beneficial owner.

Allowable Values:

yyyy-MM-dd

phone

string
Optional

The 10-digit phone number of the beneficial owner.

Allowable Values:

Format: 510-555-1212 or 5105551212

The beneficial_owner.home object
Copy section link

Fields Description

address1

string
Required

The street address of the beneficial owner’s home.

Note
Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Required

The city of the beneficial owner’s home.

Allowable Values:

40 char max

state

string
Required

The state or province of the beneficial owner’s home.

Allowable Values:

35 char max

postal_code

string
Required

The postal code of the beneficial owner’s home.

Allowable Values:

20 char max

country

string
required

The country of the beneficial owner’s home.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification.

Sample request body
Copy section link

{
  "token": "my_business_02",
  "metadata": {
  	"my_name_1": "my_value_1",
  	"my_name_2": "my_value_2"
  },
  "notes": "My notes",
  "password": "My_passw0rd",
  "phone": "5105551212",
  "website": "https://my_business_02.com",
  "history": "My_business_history",
  "incorporation": {
    "is_public": true,
    "stock_symbol": "MB",
    "state_of_incorporation": "CA",
    "name_registered_under": "First Middle Last",
    "address_registered_under": {
      "address1": "123 B Street",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "incorporation_type": "LLC"
  },
  "ip_address": "67.120.28.118",
  "business_name_legal": "My_legal_business_name",
  "business_name_dba": "My_fictitious_business_name",
  "office_location": {
    "address1": "123 A street",
    "address2": "Suite 123",
    "city": "My_city",
    "state": "CA",
    "postal_code": "94711",
    "country": "US"
  },
  "in_current_location_since": "2010-04-15",
  "date_established": "2010-04-15",
  "general_business_description": "My_business_description",
  "business_type": "My_business_type",
  "international_office_locations": "Athens, Greece; Buenos Aires, Argentina",
  "identifications": [
    {
      "type": "BUSINESS_TAX_ID",
      "value": "123456789"
    }
  ],
  "duns_number": "123456789",
  "primary_contact": {
    "title": "Dr",
    "department": "My_department",
    "phone": "5105551212",
    "extension": "11",
    "fax": "5105551222",
    "email": "dr_me@my_business.com",
    "full_name": "First Middle Last",
    "mobile": "5105551213"
  },
  "proprietor_or_officer": {
    "title": "Dr",
    "dob": "1954-03-07",
    "phone": "5105551214",
    "email": "dr_me@my_business.com",
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "home": {
      "address1": "123 B Street",
      "address2": "Apt A",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    }
  },
  "beneficial_owner1" : {
    "title": "Dr",
    "dob": "1954-03-07",
    "ssn" : "123456789",
    "phone": "5105551214",
    "email": "dr1@my_business.com",
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "home": {
      "address1": "123 B Street",
      "address2": "Apt A",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    }
  },
  "beneficial_owner2" : {
    "title": "Dr",
    "dob": "1957-01-07",
    "ssn" : "123456789",
    "phone": "5105551333",
    "email": "dr2@my_business.com",
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "home": {
      "address1": "123 C Street",
      "address2": "Apt D",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    }
  },
  "beneficial_owner3" : {
    "title": "Dr",
    "dob": "1957-01-07",
    "ssn" : "123456789",
    "phone": "5105551333",
    "email": "dr3@my_business.com",
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "home": {
      "address1": "123 C Street",
      "address2": "Apt D",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    }
  },
  "beneficial_owner4" : {
    "title": "Dr",
    "dob": "1957-01-07",
    "ssn" : "123456789",
    "phone": "5105551333",
    "email": "dr4@my_business.com",
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "home": {
      "address1": "123 C Street",
      "address2": "Apt D",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    }
  },
  "attester_name"  : "Jane Smith",
  "attester_title" : "Chief Executive Officer",
  "attestation_date" : "2020-03-03 12:03:14"
 }

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_business_02",
  "active": true,
  "notes": "My notes",
  "ip_address": "67.120.28.118",
  "password": "___________",
  "phone": "5105551212",
  "metadata": {
    "my_name_1": "my_value_1",
    "my_name_2": "my_value_2"
  },
  "business_name_legal": "My_legal_business_name",
  "business_name_dba": "My_fictitious_business_name",
  "office_location": {
    "address1": "123 A Street",
    "address2": "Suite 123",
    "city": "My_city",
    "state": "CA",
    "postal_code": "94711",
    "country": "US"
  },
  "in_current_location_since": "2010-04-15",
  "website": "https://my_business_02.com",
  "date_established": "2010-04-15",
  "general_business_description": "My_business_description",
  "history": "My_business_history",
  "business_type": "My_business_type",
  "international_office_locations": "Athens, Greece; Buenos Aires, Argentina",
  "identifications": [
    {
      "type": "BUSINESS_TAX_ID",
      "value": "123456789"
    }
  ],
  "duns_number": "123456789",
  "primary_contact": {
    "full_name": "First Middle Last",
    "title": "Dr",
    "department": "My_department",
    "phone": "5105551212",
    "extension": "11",
    "fax": "5105551222",
    "mobile": "5105551213",
    "email": "dr_me@my_business.com"
  },
  "incorporation": {
    "is_public": true,
    "stock_symbol": "MB",
    "state_of_incorporation": "CA",
    "name_registered_under": "First Middle Last",
    "address_registered_under": {
      "address1": "123 B Street",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "incorporation_type": "LLC"
  },
  "proprietor_or_officer": {
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "title": "Dr.",
    "home": {
      "address1": "123 B Street",
      "address2": "Apt A",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "dob": "1954-03-07",
    "phone": "5105551214",
    "email": "dr_me@my_business.com"
  },
  "created_time": "2019-01-13T23:29:10Z",
  "last_modified_time": "2019-01-13T23:29:10Z",
  "deposit_account": {
    "token": "420df02a-6aef-42bf-be7b-0d080ebf7573",
    "account_number": "12342126720827265",
    "routing_number": "293748000"
  },
  "status": "ACTIVE"
}

Is this helpful?

Retrieve business
Copy section link

Action: GET
Endpoint: /businesses/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

To retrieve a specific business, send a GET request to the /businesses/{token} endpoint. Include the business token path parameter to specify the business to return.

This endpoint supports field filtering and sorting and pagination.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the business to retrieve.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve business tokens.

Sample response body
Copy section link

{
  "token": "my_business_02",
  "active": true,
  "notes": "My notes",
  "ip_address": "67.120.28.118",
  "password": "___________",
  "phone": "5105551212",
  "metadata": {
    "my_name_1": "my_value_1",
    "my_name_2": "my_value_2"
  },
  "business_name_legal": "My_legal_business_name",
  "business_name_dba": "My_fictitious_business_name",
  "office_location": {
    "address1": "123 A street",
    "address2": "Suite 123",
    "city": "My_city",
    "state": "CA",
    "postal_code": "94711",
    "country": "US"
  },
  "in_current_location_since": "2010-04-15",
  "website": "https://my_business_02.com",
  "date_established": "2010-04-15",
  "general_business_description": "My_business_description",
  "history": "My_business_history",
  "business_type": "My_business_type",
  "international_office_locations": "Athens, Greece; Buenos Aires, Argentina",
  "identifications": [
    {
      "type": "BUSINESS_TAX_ID",
      "value": "123456789"
    }
  ],
  "duns_number": "123456789",
  "primary_contact": {
    "full_name": "First Middle Last",
    "title": "Dr",
    "department": "My_department",
    "phone": "5105551212",
    "extension": "11",
    "fax": "5105551222",
    "mobile": "5105551213",
    "email": "dr_me@my_business.com"
  },
  "incorporation": {
    "is_public": true,
    "stock_symbol": "MB",
    "state_of_incorporation": "CA",
    "name_registered_under": "First Middle Last",
    "address_registered_under": {
      "address1": "123 B Street",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "incorporation_type": "LLC"
  },
  "proprietor_or_officer": {
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "title": "Dr",
    "home": {
      "address1": "123 B Street",
      "address2": "Apt A",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "dob": "1954-03-07",
    "phone": "5105551214",
    "email": "dr_me@my_business.com"
  },
  "created_time": "2019-01-13T23:29:10Z",
  "last_modified_time": "2019-01-13T23:29:10Z",
  "deposit_account": {
    "token": "420df02a-6aef-42bf-be7b-0d080ebf7573",
    "account_number": "12342126720827265",
    "routing_number": "293748000"
  },
  "status": "ACTIVE"
}

Is this helpful?

Update business
Copy section link

Action: PUT
Endpoint: /businesses/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

To update a business, send a PUT request to /businesses/{token}. Use the token path parameter to specify the business to update. Include the business details to update in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the business to update.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve business tokens.

Body field details
Copy section link

Fields Description

business_name_legal

string
Conditionally required

Legal name of business.

Note
Required for KYC verification.

Allowable Values:

255 char max

business_name_dba

string
Conditionally required

Fictitious business name ("Doing Business As" or DBA).

Note
Required for KYC verification if the fictitious business name is different from the legal business name.

Allowable Values:

255 char max

office_location

object
Conditionally required

Address of business office.

Note
Required for KYC verification. Cannot perform KYC if set to a PO Box.

Allowable Values:

Existing office_location object.

in_current_location_since

string
Optional

The date on which the business office opened in its current location.

Allowable Values:

yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

phone

string
Optional

10-digit telephone number of business.

Allowable Values:

Format: 510-555-1212 or 5105551212

website

string
Optional

URL of the business' website.

Allowable Values:

255 char max

date_established

string
Conditionally required

Date the business was established.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

general_business_description

string
Optional

General description of the business.

Allowable Values:

255 char max

history

string
Optional

History of the business.

Allowable Values:

255 char max

account_holder_group_token

string
Optional

Associates the specified account holder group with the business.

Allowable Values:

Existing account holder group token.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

ip_address

string
Optional

The IP address of the business.

Allowable Values:

39 char max

notes

string
Optional

Any additional information pertaining to the business.

Allowable Values:

255 char max

business_type

string
Optional

Indicates the type of business, for example business-to-business (B2B) or business-to-consumer (B2C).

Allowable Values:

255 char max

international_office_locations

string
Optional

The locations of the business' offices outside the US.

Allowable Values:

255 char max

primary_contact

object
Optional

Describes the business' primary contact.

Allowable Values:

Existing primary_contact object.

duns_number

string
Optional

Data Universal Numbering System (DUNS) number of the business.

Allowable Values:

255 char max

incorporation

object
Conditionally required

Contains information about the organizational structure of the business.

Note
Required for KYC verification.

Allowable Values:

Existing incorporation object.

proprietor_or_officer

object
Conditionally required

Contains information about the proprietor or officer of the business.

Note
Required for KYC verification.

Allowable Values:

Existing proprietor_or_officer object.

metadata

object
Optional

Associates customer-injected metadata with the business.

Allowable Values:

Existing metadata object.

password

string
Optional

Password for the business' account.

Allowable Values:

  • 8-20 characters

  • Must contain at least one numeral

  • Must contain at least one lowercase letter

  • Must contain at least one uppercase letter

  • Must contain at least one of these symbols: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

identifications

array
Optional

One or more objects containing identifying information about the business.

Allowable Values:

Existing identifications array.

beneficial_owner1

object
Conditionally required

Contains information about the beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

beneficial_owner2

object
Conditionally required

Contains information about the second beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a second beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

beneficial_owner3

object
Conditionally required

Contains information about the third beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a third beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

beneficial_owner4

object
Conditionally required

Contains information about the fourth beneficial owner of the business, if applicable.

Note
Required for KYC verification if the business has a fourth beneficial owner. Do not include information about the proprietor or business officer in a beneficial_owner object. If the proprietor or officer of the business is also a beneficial owner, you must indicate that in the proprietor_is_beneficial_owner field in the body field details of the business.

Allowable Values:

Existing beneficial_owner object.

attestation_consent

boolean
Conditionally required

Indicates that the attester agrees that the information provided is correct and truthful.

Note
Required for KYC verification.

Allowable Values:

true, false

attester_name

string
Conditionally required

The name of the attester for KYC verification.

Note
Required for KYC verification.

Allowable Values:

The name of the attester. For example, Jane Smith.

attester_title

string
Optional

The title of the attester for KYC verification.

Allowable Values:

The title of the attester. For example, Chief Executive Officer.

attestation_date

string
Conditionally required

The timestamp of the attestation.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ

proprietor_is_beneficial_owner

boolean
Conditionally required

Indicates that the proprietor or officer of the business is also a beneficial owner.

Note
Required for KYC verification if the business proprietor or officer is also a beneficial owner. If the proprietor or business officer is a beneficial owner, use this field to indicate their beneficial ownership. Do not include information about the proprietor or business officer in a beneficial_owner object.

Allowable Values:

true, false

Default value:
false

The office_location object
Copy section link

Fields Description

address1

string
Conditionally required

Business office’s street address.

Note
Required for KYC verification. Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Note
Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

city

string
Conditionally required

Business office’s city.

Note
Required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

Business office’s state.

Note
Required for KYC verification.

Allowable Values:

35 char max

postal_code

string
Conditionally required

Business office’s postal code.

Note
Required for KYC verification.

Allowable Values:

20 char max

country

string
Conditionally required

Business office’s country.

Note
Required for KYC verification.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification. US, for example.

The primary_contact object
Copy section link

Fields Description

full_name

string
Optional

Name of primary contact.

Allowable Values:

255 char max

title

string
Optional

Title of primary contact.

Allowable Values:

255 char max

department

string
Optional

Department of primary contact.

Allowable Values:

255 char max

phone

string
Optional

Telephone number of primary contact.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

extension

string
Optional

Telephone extension of primary contact.

Allowable Values:

255 char max

fax

string
Optional

Fax number of primary contact.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

mobile

string
Optional

Mobile telephone number of primary contact.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

email

string
Optional

Email address of primary contact.

Allowable Values:

255 char max

The incorporation object
Copy section link

Fields Description

is_public

boolean
Required

A value of true indicates that the business is publicly held.

Allowable Values:

true, false

Default value:
false

incorporation_type

string
Conditionally required

The organizational structure of the business (corporation or sole proprietorship, for example).

Note
Required for KYC verification.

Allowable Values:

LLC, CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, COOPERATIVE, OTHER

stock_symbol

string
Optional

The business' stock symbol.

Allowable Values:

255 char max

state_of_incorporation

string
Required

The state in which the business is incorporated.

Note
Required for KYC verification.

Allowable Values:

255 char max

name_registered_under

string
Optional

The name under which the business is registered.

Allowable Values:

255 char max

address_registered_under

object
Conditionally required

The address under which the business is registered.

Note
Required for KYC verification.

Allowable Values:

A valid incorporation.address_registered_under object.

The incorporation.address_registered_under object
Copy section link

Fields Description

address1

string
Optional

Business' registered street address.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Optional

Business' registered city.

Allowable Values:

40 char max

state

string
Optional

Business' registered state.

Allowable Values:

35 char max

postal_code

string
Optional

Business' registered postal code.

Allowable Values:

20 char max

country

string
Optional

Business' registered country.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification. US, for example.

The identifications array
Copy section link

You can add one or more objects to the identifications array. Each identification in the array must be of a different type.

Only one of the following identification types can be associated with a business:

  • Business Tax ID

  • Business Number

  • Taxpayer Reference

Fields Description

type

string
Required

The form of identification.

Note
BUSINESS_TAX_ID required for KYC verification.

Allowable Values:

BUSINESS_TAX_ID, BUSINESS_NUMBER, TAXPAYER_REFERENCE

value

string
Required

The identification number associated with the form of identification.

Allowable Values:

255 char max

Note
Digits only, do not use separators. For example: 123456789

expiration_date

string
Optional

The expiration date for the form of identification, if applicable.

Allowable Values:

yyyy-MM-dd

The proprietor_or_officer object
Copy section link

Fields Description

first_name

string
Required

First name of business proprietor or officer.

Allowable Values:

255 char max

middle_name

string
Optional

Middle name of business proprietor or officer.

Allowable Values:

255 char max

last_name

string
Required

Last name of business proprietor or officer.

Allowable Values:

255 char max

alternative_names

string
Optional

Alternate names of business proprietor or officer.

Allowable Values:

255 char max

title

string
Optional

Title of business proprietor or officer.

Allowable Values:

255 char max

home

object
Conditionally required

Describes the business proprietor or officer’s home.

Note
Required for KYC verification.

Allowable Values:

Existing proprietor_or_officer.home object.

dob

string
Conditionally required

Business proprietor or officer’s date of birth.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

phone

string
Optional

Telephone number of business proprietor or officer.

Allowable Values:

Format: 510-555-1212 or 5105551212

Do not insert a 1 before the area code.

email

string
Optional

Email address of business proprietor or officer.

Allowable Values:

255 char max

identifications

array
Conditionally required

One or more objects containing identifying information about the business proprietor or officer.

Note
Required for KYC verification.

Allowable Values:

Existing proprietor_or_officer.identifications array.

The proprietor_or_officer.home object
Copy section link

Fields Description

address1

string
Conditionally required

Street address of the business proprietor or officer.

Note
Required for KYC verification.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Conditionally required

City of business proprietor or officer.

Note
Required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

State in which business proprietor or officer resides.

Note
Required for KYC verification.

Allowable Values:

35 char max

postal_code

string
Conditionally required

Business proprietor or officer’s postal code.

Note
Required for KYC verification.

Allowable Values:

20 char max

country

string
Conditionally required

Country in which business proprietor or officer resides.

Note
Required for KYC verification.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification. US, for example.

The proprietor_or_officer.identifications array
Copy section link

You can add one or more objects to the identifications array. Each identification in the array must be of a different type.

Only one of the following identification types can be associated with a proprietor or officer:

  • SSN – Social Security Number

  • SIN – Social Insurance Number

  • TIN – Taxpayer Identification Number

  • NIN – National Insurance Number

Fields Description

type

string
Required

The form of identification.

Note
Full SSN is required for KYC verification.

Allowable Values:

SSN, TIN, SIN, NIN

value

string
Required

The identification number associated with the form of identification.

Allowable Values:

255 char max

Note
Digits only, do not use separators. For example: 123456789

expiration_date

string
Optional

The expiration date for the form of identification, if applicable.

Allowable Values:

yyyy-MM-dd

The metadata object
Copy section link

Fields Description

customer_defined_name_01 customer_defined_name_02 …​ customer_defined_name_20

Associates customer-injected metadata with the business.

You can define the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
}

The following samples show how to update, add, and delete fields. Existing fields are unaffected unless they are included in the request.

Update a field’s value:

"metadata": {
  "my_name_1": "my_updated_value"
}

Add a new field:

"metadata": {
  "my_new_field": "my_value"
}

Delete an existing field:

"metadata": {
  "my_name_1": null
}

Allowable Values:

  • Up to 20 name-value pairs.

  • 255 char max per name.

  • 255 char max per value.

The beneficial_owner object
Copy section link

The beneficial_owner object is only required if you want to run KYC validation on a company that has one or more beneficial owners.

Note
If the proprietor or officer of the business is also a beneficial owner, you only need to submit their information as the proprietor, setting the value for the proprietor_is_beneficial_owner field to true. Submitting an individual as both proprietor and beneficial owner will cause an extra KYC evaluation to be performed unnecessarily on that individual.
Fields Description

first_name

string
Required

The first name of the beneficial owner.

Allowable Values:

255 char max, no digits or single letters.

middle_name

string
Optional

The middle name of the beneficial owner.

Allowable Values:

255 char max

last_name

string
Required

The last name of the beneficial owner.

Allowable Values:

255 char max, no digits or single letters.

title

string
Optional

The title of the beneficial owner.

Allowable Values:

255 char max

home

object
Required

The home address of the beneficial owner.

Allowable Values:

Existing beneficial_owner.home object.

ssn

string
Required

The nine-digit Social Security Number of the beneficial owner.

Allowable Values:

255 char max

Note
Digits only, do not use separators. For example: 123456789

For example: 123456789

dob

string
Required

The date of birth of the beneficial owner.

Allowable Values:

yyyy-MM-dd

phone

string
Optional

The 10-digit phone number of the beneficial owner.

Allowable Values:

Format: 510-555-1212 or 5105551212

The beneficial_owner.home object
Copy section link

Fields Description

address1

string
Required

The street address of the beneficial owner’s home.

Note
Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Required

The city of the beneficial owner’s home.

Allowable Values:

40 char max

state

string
Required

The state or province of the beneficial owner’s home.

Allowable Values:

35 char max

postal_code

string
Required

The postal code of the beneficial owner’s home.

Allowable Values:

20 char max

country

string
Required

The country of the beneficial owner’s home.

Allowable Values:

40 char max

Note
ISO alpha-2 country code required for KYC verification.

Sample request body
Copy section link

{
  "phone": "9876543210"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_business_02",
  "active": true,
  "notes": "My notes",
  "ip_address": "67.120.28.118",
  "password": "___________",
  "phone": "9876543210",
  "metadata": {
    "my_name_1": "my_value_1",
    "my_name_2": "my_value_2"
  },
  "business_name_legal": "My_legal_business_name",
  "business_name_dba": "My_fictitious_business_name",
  "office_location": {
    "address1": "123 A Street",
    "address2": "Suite 123",
    "city": "My_city",
    "state": "CA",
    "postal_code": "94711",
    "country": "US"
  },
  "in_current_location_since": "2010-04-15",
  "website": "https://my_business_02.com",
  "date_established": "2010-04-15",
  "general_business_description": "My_business_description",
  "history": "My_business_history",
  "business_type": "My_business_type",
  "international_office_locations": "Athens, Greece; Buenos Aires, Argentina",
  "identifications": [
    {
      "type": "BUSINESS_TAX_ID",
      "value": "123456789"
    }
  ],
  "duns_number": "123456789",
  "primary_contact": {
    "full_name": "First Middle Last",
    "title": "Dr",
    "department": "My_department",
    "phone": "5105551214",
    "extension": "11",
    "fax": "5105551222",
    "mobile": "5105551213",
    "email": "dr_me@my_business.com"
  },
  "incorporation": {
    "is_public": true,
    "stock_symbol": "MB",
    "state_of_incorporation": "CA",
    "name_registered_under": "First Middle Last",
    "address_registered_under": {
      "address1": "123 B Street",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "incorporation_type": "LLC"
  },
  "proprietor_or_officer": {
    "first_name": "First",
    "middle_name": "Middle",
    "last_name": "Last",
    "alternative_names": "My alternative name",
    "title": "Dr",
    "home": {
      "address1": "123 B Street",
      "address2": "Apt A",
      "city": "My_city",
      "state": "CA",
      "postal_code": "94711",
      "country": "US"
    },
    "dob": "1954-03-07",
    "phone": "5105551214",
    "email": "dr_me@my_business.com"
  },
  "created_time": "2019-01-13T23:29:10Z",
  "last_modified_time": "2019-01-13T23:29:10Z",
  "deposit_account": {
    "token": "420df02a-6aef-42bf-be7b-0d080ebf7573",
    "account_number": "12342126720827265",
    "routing_number": "293748000"
  },
  "status": "ACTIVE"
}

Is this helpful?

List businesses
Copy section link

Action: GET
Endpoint: /businesses

Develop Now!

Sign in and use your sandbox to access the API Explorer

To return an array of all businesses, send a GET request to the /businesses endpoint.

To narrow your result set to businesses that match a particular legal or fictitious name, include the appropriate parameters from the following query parameters table. This endpoint also supports field filtering and sorting and pagination.

Query parameters
Copy section link

Fields Description

business_name_legal

string
Optional

Performs a non-case-sensitive match on the business' business_name_legal field. Matching is partial on the beginning of the name. For example, a match on "Tool" returns both "Tools R Us" and "Tools & More".

Allowable Values:

40 char max

business_name_dba

string
Optional

Performs a non-case-sensitive match on the business' business_name_dba field. Matching is partial on the beginning of the name. For example, a match on "Tool" returns both "Tools R Us" and "Tools & More".

Allowable Values:

40 char max

Sample response body
Copy section link

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "token": "my_business_01",
      "active": true,
      "notes": "My notes",
      "password": "___________",
      "phone": "5105551215",
      "website": "https://my_business.com",
      "history": "My_business_history",
      "incorporation": {
        "is_public": true,
        "stock_symbol": "MB",
        "state_of_incorporation": "CA",
        "name_registered_under": "First Middle Last",
        "address_registered_under": {
          "address1": "123 B Street",
          "city": "My_city",
          "state": "CA",
          "postal_code": "94711",
          "country": "US"
        },
        "incorporation_type": "LLC"
      },
      "ip_address": "67.120.28.118",
      "business_name_legal": "My_legal_business_name",
      "business_name_dba": "My_fictitious_business_name",
      "office_location": {
        "address1": "123 A Street",
        "address2": "Suite 123",
        "city": "My_city",
        "state": "CA",
        "postal_code": "94711",
        "country": "US"
      },
      "in_current_location_since": "2010-04-15",
      "date_established": "2010-04-15",
      "general_business_description": "My_business_description",
      "business_type": "My_business_type",
      "international_office_locations": "Athens, Greece; Buenos Aires, Argentina",
      "identifications": [
        {
          "type": "BUSINESS_TAX_ID",
          "value": "123456789"
        }
      ],
      "duns_number": "123456789",
      "primary_contact": {
        "title": "Dr",
        "department": "My_department",
        "phone": "5105551215",
        "extension": "11",
        "fax": "5105551216",
        "email": "dr_me@my_business.com",
        "full_name": "First Middle Last",
        "mobile": "5105551217"
      },
      "proprietor_or_officer": {
        "title": "Dr",
        "dob": "1954-03-07",
        "phone": "5105551214",
        "email": "dr_me@my_business.com",
        "first_name": "First",
        "middle_name": "Middle",
        "last_name": "Last",
        "alternative_names": "My alternative name",
        "home": {
          "address1": "123 B Street",
          "address2": "Apt A",
          "city": "My_city",
          "state": "CA",
          "postal_code": "94711",
          "country": "US"
        }
      },
      "created_time": "2019-10-18T21:17:03Z",
      "last_modified_time": "2019-10-19T22:48:02Z"
      "status": "ACTIVE"
    }
  ]
}

Is this helpful?

Search businesses
Copy section link

Action: POST
Endpoint: /businesses/lookup

Develop Now!

Sign in and use your sandbox to access the API Explorer

To search for one or more businesses, send a POST request to the /businesses/lookup endpoint. Include in the message body any parameters by which you want to query. This endpoint supports field filtering and pagination.

Body field details
Copy section link

Fields Description

dda

string
Required

The deposit account number of the business.

Allowable Values:

17 char max

Send a GET request to /directdeposits/accounts/{business_token} to retrieve the deposit account number for a specific business.

Send a GET request to /businesses to retrieve business tokens.

Sample request body
Copy section link

{
  "dda" : "00002129923205648"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "297aa1a7-f3c9-46eb-9e0a-54f8bce0c189",
  "active": true,
  "phone": "5105551218",
  "metadata": {},
  "account_holder_group_token": "DEFAULT_AHG",
  "created_time": "2019-06-20T00:17:48Z",
  "last_modified_time": "2019-06-20T00:17:48Z",
  "business_name_legal": "Chicken Tooth Music LLC",
  "business_name_dba": "Chicken Tooth Music",
  "office_location": {
    "address1": "111 Main St",
    "address2": "Suite B",
    "city": "Berkeley",
    "state": "CA",
    "postal_code": "94702",
    "country": "USA"
  },
  "date_established": "2010-01-01",
  "business_type": "other",
  "duns_number": "22344566",
  "primary_contact": {
    "full_name": "William Barry",
    "title": "Mr.",
    "department": "AP",
    "phone": "5105551218",
    "extension": "234",
    "fax": "5105551219",
    "mobile": "5105551220",
    "email": "wbarry@ctm.com"
  },
  "incorporation": {
    "state_of_incorporation": "CA",
    "incorporation_type": "CORPORATION"
  },
  "identifications": [
    {
      "type": "BUSINESS_TAX_ID",
      "value": "27-4387216"
    }
  ]
}

Is this helpful?

List business children
Copy section link

Action: GET
Endpoint: /businesses/{parent_token}/children

Develop Now!

Sign in and use your sandbox to access the API Explorer

To return an array of all child users of a particular business, send a GET request to the /businesses/{parent_token}/children endpoint. Include the parent_token as a URL path parameter.

This endpoint supports field filtering.

URL path parameters
Copy section link

Fields Description

parent_token

string
Required

Identifies the business whose child-users you want to list.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve business tokens.

Sample response body
Copy section link

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_child_user_01",
      "active": true,
      "password": "___________",
      "phone": "510-111-1111",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "gender": "F",
      "email": "my_child_user_01@gmail.com",
      "address1": "1234 Lake Street",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94702",
      "country": "US",
      "identifications": [
        {
          "type": "SSN",
          "value": "_________"
        }
      ],
      "first_name": "First",
      "last_name": "Last",
      "birth_date": "1990-01-01",
      "parent_token": "my_business_01",
      "uses_parent_account": true,
      "created_time": "2019-10-20T17:50:36Z",
      "last_modified_time": "2019-10-20T17:50:36Z",
      "business_token": "my_business_01"
      "status": "ACTIVE"
    },
  ]
}

Is this helpful?

Retrieve business identification number
Copy section link

Action: GET
Endpoint: /businesses/{token}/ssn

Develop Now!

Sign in and use your sandbox to access the API Explorer

To retrieve the government-issued identification number of a business' proprietor, send a GET request to the /businesses/{token}/ssn endpoint. Include the token path parameter to specify the business whose identification number (SSN, TIN, NIN, SIN) you want to return. You can indicate whether to return the full number or the last four digits only.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the business whose identification number you want to retrieve.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve business tokens.

Query parameters
Copy section link

Fields Description

full_ssn

boolean
Required

To return the full identification number, set to true. To return only the last 4 digits, set to false.

If the proprietor_or_officer.identifications array contains only the last four digits of the identification number, the /businesses/{token}/ssn endpoint will return only the last four digits regardless of the full_ssn parameter.

Allowable Values:

true, false

Default value:
false

Sample response body
Copy section link

{
  "ssn": "5555"
}

Is this helpful?

Create business transition
Copy section link

Action: POST
Endpoint: /businesstransitions

Develop Now!

Sign in and use your sandbox to access the API Explorer

This endpoint enables you to change a business' status, depending on your role and the previous status change. By changing a business' status, you can control the business' capabilities and the setting of the business.active field. The business.active field is true if your business is in the LIMITED or ACTIVE state, and false if your business is in the UNVERIFIED state. You cannot control the value of the business.active field directly.

The business.status field Description Business limitations

Unverified

Initial status of a newly created business belonging to an accountholdergroup where KYC is always required.

Cannot load funds.

The business.active field:
false

Allowable transitions:
ACTIVE, SUSPENDED, CLOSED

Limited

Initial status of a newly created business belonging to an accountholdergroup where KYC is conditionally required.

Restricted by rules in accountholdergroups.pre_kyc_controls.

The business.active field:
true

Allowable transitions:
ACTIVE, SUSPENDED, CLOSED

Active

Status of a business that has passed KYC; initial status of a newly created business belonging to an accountholdergroup where KYC is never required.

None.

The business.active field:
true

Allowable transitions:
SUSPENDED, CLOSED

Suspended

The business is temporarily inactive.

Note
Transitioning a suspended business to the ACTIVE status is restricted, based on your role and the details of the previous status change.

Cannot load funds or activate cards.

The business.active field:
false

Allowable transitions:
ACTIVE, LIMITED, UNVERIFIED, CLOSED

Closed

The business is permanently inactive.

Note
CLOSED is a terminal status. In exceptional cases, you can transition a business from CLOSED to another status, depending on your role and the details of the previous status change. Contact your Marqeta representative for more information.

Cannot load funds.

The business.active field:
false

Allowable transitions:
ACTIVE, LIMITED, UNVERIFIED, SUSPENDED
Note
The Marqeta platform transitions a business" status in response to certain events. For example, a business with an UNVERIFIED status transitions to ACTIVE when the business passes KYC.

Body field details
Copy section link

Fields Description

token

string
Optional

The unique identifier of the business transition.

If you do not include a token, the system generates one automatically. This token is referenced in other API calls, so we recommend that you define a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

business_token

string
Required

Identifies the business whose status is transitioned.

Allowable Values:

Existing business token.

Send a GET request to the /businesses endpoint to retrieve business tokens.

status

string
Required

Specifies the new status of the business.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

reason_code

string
Required

Identifies the standardized reason for the transition.

Allowable Values:

See The reason-code field section.

reason

string
Optional

Additional information about the status change.

Allowable Values:

255 char max

channel

string
Required

The mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

The reason_code field
Copy section link

Value Description

00

Object activated for the first time.

01

Requested by you.

02

Inactivity over time.

03

Provided address either does not accept mail or the addressee is not known at the address.

04

Negative account balance.

05

Account under review.

06

Suspicious activity was identified.

07

Activity outside the program parameters was identified.

08

Confirmed fraud was identified.

09

Matched with an Office of Foreign Assets Control list.

10

Card was reported lost.

11

Card information was cloned.

12

Account or card information was compromised.

13

Temporary status change while on hold/leave.

14

Initiated by Marqeta.

15

Initiated by issuer.

16

Card expired.

17

Failed KYC.

18

Changed to ACTIVE because information was properly validated and confirmed.

19

Changed to ACTIVE because account activity was properly validated and confirmed.

20

Change occurred prior to the normalization of reason codes.

21

Initiated by a third party, often a digital wallet provider.

22

PIN retry limit reached.

23

Card was reported stolen.

Sample request body
Copy section link

{
  "token": "activate_05",
  "business_token": "my_business_01",
  "status": "ACTIVE",
  "reason_code": "00",
  "reason": "Activating business",
  "channel": "API"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "activate_05",
  "business_token": "my_business_01",
  "status": "ACTIVE",
  "reason_code": "00",
  "reason": "Activating business",
  "channel": "API",
  "created_time": "2019-11-23T23:28:39Z"
}

Is this helpful?

Retrieve business transition
Copy section link

Action: GET
Endpoint: /businesstransitions/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a business transition.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the business transition to retrieve.

Allowable Values:

Existing business transition token.

Sample response body
Copy section link

{
  "token": "activate_05",
  "business_token": "my_business_01",
  "status": "ACTIVE",
  "reason_code": "00",
  "reason": "Activating business",
  "channel": "API",
  "created_time": "2019-11-23T23:28:39Z"
}

Is this helpful?

List transitions for business
Copy section link

Action: GET
Endpoint: /businesstransitions/business/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list all transitions for a given business.

URL path parameters
Copy section link

Fields Description

token

string
Required

Identifies the business associated with the transitions to retrieve.

Allowable Values:

Existing business token.

Send a GET request to the /businesses endpoint to retrieve business tokens.

Sample response body
Copy section link

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "activate_05",
      "business_token": "my_business_01",
      "status": "ACTIVE",
      "reason_code": "00",
      "reason": "Activating business",
      "channel": "API",
      "created_time": "2019-11-23T23:28:39Z"
    }
  ]
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.