DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

25 minute read

December 1, 2019

Businesses

A business is a type of account holder that cannot directly own cards, but can have parent/child relationships with 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

Can’t load funds.

Conditionally

LIMITED

No

Restricted by rules in accountholdergroups.pre_kyc_controls.

Never

ACTIVE

Yes

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 optional

Legal name of business.

Required for verification (KYC) checks.

Allowable Values:

255 char max

business_name_dba

string optional

Fictitious business name.

Required for verification (KYC) checks.

Allowable Values:

255 char max

office_location

object optional

Address of business office.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.

Allowable Values:

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.

Required for verification (KYC) checks.

Allowable Values:

510-555-1212 or 5105551212

Do not insert a 1 before the area code.

website

string optional

URL of the business' website.

Allowable Values:

255 char max

date_established

string optional

Date the business was established.

Required for verification (KYC) checks.

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:

duns_number

string optional

Data Universal Numbering System (DUNS) number of business.

Allowable Values:

255 char max

incorporation

object optional

Contains information regarding the business' incorporation.

Required for verification (KYC) checks.

Allowable Values:

proprietor_or_officer

object optional

Contains information regarding the business' proprietor or officer.

Allowable Values:

metadata

object optional

Associates customer-injected metadata with the business.

Allowable Values:

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:

The office_location object
Copy section link

Fields Description

address1

string optional

Business office’s street address.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.

Allowable Values: 255 char max

address2

string optional

Additional address information.

Cannot perform KYC if set to a PO Box.

Allowable Values: 255 char max

city

string optional

Business office’s city.

Required for verification (KYC) checks.

Allowable Values: 40 char max

state

string optional

Business office’s state.

Required for verification (KYC) checks.

Allowable Values: 35 char max

postal_code

string optional

Business office’s postal code.

Required for verification (KYC) checks.

Allowable Values: 20 char max

country

string optional

Business office’s country.

Required for verification (KYC) checks.

Allowable Values: 40 char max

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: 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: 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: 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 optional

true indicates the business is publicly held.

Allowable Values: true, false

Default value: false

incorporation_type

string optional

The business' type of incorporation.

Required for verification (KYC) checks.

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 optional

The state in which the business is incorporated.

Required for verification (KYC) checks.

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 optional

The address under which the business is registered.

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

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
Required for KYC verification checks.

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 optional

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 optional

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 optional

Describes the business proprietor or officer’s home.

dob

string optional

Business proprietor or officer’s date of birth

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

object optional

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

The proprietor_or_officer.home object
Copy section link

Fields Description

address1

string optional

Street address of business proprietor or officer.

Allowable Values: 255 char max

address2

string optional

Additional address information.

Allowable Values: 255 char max

city

string optional

City of business proprietor or officer.

Allowable Values: 40 char max

state

string optional

State in which business proprietor or officer resides.

Allowable Values: 35 char max

postal_code

string optional

Business proprietor or officer’s postal code.

Allowable Values: 20 char max

country

string optional

Country in which business proprietor or officer resides

Allowable Values: 40 char max

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
SSN is required for KYC verification checks.

Allowable Values:

SSN, TIN, SIN, NIN

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 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"
}

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value

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": "USA"
    },
    "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": "USA"
  },
  "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": "USA"
    }
  }
 }

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": "USA"
  },
  "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": "USA"
    },
    "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": "USA"
    },
    "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",
    "allow_immediate_credit": false
  },
  "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": "USA"
  },
  "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": "USA"
    },
    "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": "USA"
    },
    "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",
    "allow_immediate_credit": false
  },
  "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 optional

Legal name of business.

Required for verification (KYC) checks.

Allowable Values:

255 char max

business_name_dba

string optional

Fictitious business name.

Required for verification (KYC) checks.

Allowable Values:

255 char max

office_location

object optional

Address of business office.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.

Allowable Values:

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.

Required for verification (KYC) checks.

Allowable Values:

510-555-1212 or 5105551212

Do not insert a 1 before the area code.

website

string optional

URL of the business' website.

Allowable Values:

255 char max

date_established

string optional

Date the business was established.

Required for verification (KYC) checks.

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:

duns_number

string optional

Data Universal Numbering System (DUNS) number of business.

Allowable Values:

255 char max

incorporation

object optional

Contains information regarding the business' incorporation.

Required for verification (KYC) checks.

Allowable Values:

proprietor_or_officer

object optional

Contains information regarding the business' proprietor or officer.

Allowable Values:

metadata

object optional

Associates customer-injected metadata with the business.

Allowable Values:

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:

The office_location object
Copy section link

Fields Description

address1

string optional

Business office’s street address.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.

Allowable Values: 255 char max

address2

string optional

Additional address information.

Cannot perform KYC if set to a PO Box.

Allowable Values: 255 char max

city

string optional

Business office’s city.

Required for verification (KYC) checks.

Allowable Values: 40 char max

state

string optional

Business office’s state.

Required for verification (KYC) checks.

Allowable Values: 35 char max

postal_code

string optional

Business office’s postal code.

Required for verification (KYC) checks.

Allowable Values: 20 char max

country

string optional

Business office’s country.

Required for verification (KYC) checks.

Allowable Values: 40 char max

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: 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: 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: 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 optional

true indicates the business is publicly held.

Allowable Values: true, false

Default value: false

incorporation_type

string optional

The business' type of incorporation.

Required for verification (KYC) checks.

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 optional

The state in which the business is incorporated.

Required for verification (KYC) checks.

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 optional

The address under which the business is registered.

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

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.

Required for KYC verification checks.

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 optional

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 optional

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 optional

Describes the business proprietor or officer’s home.

dob

string optional

Business proprietor or officer’s date of birth

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

object optional

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

The proprietor_or_officer.home object
Copy section link

Fields Description

address1

string optional

Street address of business proprietor or officer.

Allowable Values: 255 char max

address2

string optional

Additional address information.

Allowable Values: 255 char max

city

string optional

City of business proprietor or officer.

Allowable Values: 40 char max

state

string optional

State in which business proprietor or officer resides.

Allowable Values: 35 char max

postal_code

string optional

Business proprietor or officer’s postal code.

Allowable Values: 20 char max

country

string optional

Country in which business proprietor or officer resides

Allowable Values: 40 char max

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
SSN is required for KYC verification checks.

Allowable Values:

SSN, TIN, SIN, NIN

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 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.

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": "USA"
  },
  "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": "USA"
    },
    "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": "USA"
    },
    "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",
    "allow_immediate_credit": false
  },
  "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": "USA"
        },
        "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": "USA"
      },
      "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": "USA"
        }
      },
      "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": "USA",
      "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 The business.active field Business limitations Allowable transitions

Unverified

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

false

Cannot load funds.

ACTIVE, SUSPENDED, CLOSED

Limited

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

true

Restricted by rules in accountholdergroups.pre_kyc_controls.

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.

true

None.

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.

false

Cannot load funds or activate cards.

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.

false

Cannot load funds.

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 or stolen.

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.

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.