Create business

Action: POST
Endpoint: /businesses

To create a business, send a POST request to the /businesses endpoint and include the business details in JSON format in the body of the request. A new business's initial status 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's status, use the /businesstransitions endpoint. For more information on status changes, see "Create business transition" on this page.

To perform KYC verification checks on businesses, the business object must have the following fields configured:

  • business_name_legal
  • business_name_dba
  • office_location (object; cannot perform KYC if set to a PO Box)
  • identifications (array; must include identification of type BUSINESS_TAX_ID, BUSINESS_NUMBER, or TAXPAYER_REFERENCE)
  • incorporation.incorporation_type
  • incorporation.state_of_incorporation
  • phone (the top-level phone field)
  • date_established

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

Body field details

Name Type Required? Description Allowable Values
token string No 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.
36 char max
business_name_legal string No Legal name of business.

Required for verification (KYC) checks.
255 char max
business_name_dba string No Fictitious business name.

Required for verification (KYC) checks.
255 char max
office_location object No Address of business office.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.
in_current_location_since string No The date on which the business office opened in its current location. 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 No 10-digit telephone number of business.

Required for verification (KYC) checks.
123-456-7890 or 1234567890

Do not insert a 1 before the area code.
website string No URL of the business's website. 255 char max
date_established string No Date the business was established.

Required for verification (KYC) checks.
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 No General description of the business. 255 char max
history string No History of the business. 255 char max
account_holder_group_token string No Associates the specified account holder group with the business. Existing account holder group token.

Issue a GET to /accountholdergroups to retrieve account holder group tokens.
ip_address string No The IP address of the business. 39 char max
notes string No Any additional information pertaining to the business. 255 char max
business_type string No Indicates the type of business, for example B2B (business-to-business) or B2C (business-to-consumer). 255 char max
international_office_locations string No The locations of the business's offices outside the US. 255 char max
primary_contact object No Describes the business's primary contact.
duns_number string No Data Universal Numbering System (DUNS) number of business. 255 char max
incorporation object No Contains information regarding the business's incorporation.

Required for verification (KYC) checks.
proprietor_or_officer object No Contains information regarding the business's proprietor or officer.
metadata object No Associates customer-injected metadata with the business.
password string No Password for the business's account.
  • 8-20 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
identifications array No One or more objects containing identifying information about the business.

The office_location object

Name Type Required? Description Allowable Values
address1 string No Business office's street address.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.
35 char max
address2 string No Additional address information.

Cannot perform KYC if set to a PO Box.
35 char max
city string No Business office's city.

Required for verification (KYC) checks.
35 char max
state string No Business office's state.

Required for verification (KYC) checks.
35 char max
postal_code string No Business office's postal code.

Required for verification (KYC) checks.
20 char max
country string No Business office's country.

Required for verification (KYC) checks.
40 char max

The primary_contact object

Name Type Required? Description Allowable Values
full_name string No Name of primary contact. 255 char max
title string No Title of primary contact. 255 char max
department string No Department of primary contact. 255 char max
phone string No Telephone number of primary contact. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
extension string No Telephone extention of primary contact. 255 char max
fax string No Fax number of primary contact. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
mobile string No Mobile telephone number of primary contact. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
email string No Email address of primary contact. 255 char max

The incorporation object

Name Type Required? Description Allowable Values
is_public boolean No "True" indicates the business is publicly held. true | false

Default: false
incorporation_type string No The business's type of incorporation.

Required for verification (KYC) checks.
LLC | CORPORATION | SOLE_PROPRIETORSHIP | PARTNERSHIP | COOPERATIVE | OTHER
stock_symbol string No The business's stock symbol. 255 char max
state_of_incorporation string No The state in which the business is incorporated.

Required for verification (KYC) checks.
255 char max
name_registered_under string No The name under which the business is registered. 255 char max
address_registered_under object No The address under which the business is registered.

The incorporation.address_registered_under object

Name Type Required? Description Allowable Values
address1 string No Business's registered street address. 35 char max
address2 string No Additional address information. 35 char max
city string No Business's registered city. 35 char max
state string No Business's registered state. 35 char max
postal_code string No Business's registered postal code. 20 char max
country string No Business's registered country. 40 char max

The identifications array

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
Name Type Required? Description Allowable Values
type string Yes The form of identification.

Note: Required for KYC verification checks.
BUSINESS_TAX_ID | BUSINESS_NUMBER | TAXPAYER_REFERENCE
value string Yes The identification number associated with the form of identification. 255 char max
expiration_date string No The expiration date for the form of identification, if applicable. yyyy-MM-dd

The proprietor_or_officer object

Name Type Required? Description Allowable Values
first_name string No First name of business proprietor or officer. 255 char max
middle_name string No Middle name of business proprietor or officer. 255 char max
last_name string No Last name of business proprietor or officer. 255 char max
alternative_names string No Alternate names of business proprietor or officer. 255 char max
title string No Title of business proprietor or officer. 255 char max
home object No Describes the business proprietor or officer's home.
dob string No Business proprietor or officer's date of birth 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 No Telephone number of business proprietor or officer. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
email string No Email address of business proprietor or officer. 255 char max
identifications object No One or more objects containing identifying information about the business proprietor or officer.

The proprietor_or_officer.home object

Name Type Required? Description Allowable Values
address1 string No Street address of business proprietor or officer. 35 char max
address2 string No Additional address information. 35 char max
city string No City of business proprietor or officer. 35 char max
state string No State in which business proprietor or officer resides. 35 char max
postal_code string No Business proprietor or officer's postal code. 20 char max
country string No Country in which business proprietor or officer resides 40 char max

The proprietor_or_officer.identifications array

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
Name Type Required? Description Allowable Values
type string Yes The form of identification.

Note: SSN is required for KYC verification checks.
SSN | TIN | SIN | NIN
value string Yes The identification number associated with the form of identification. 255 char max
expiration_date string No The expiration date for the form of identification, if applicable. yyyy-MM-dd

The metadata object

Name Type Required? Description Allowable Values
customer_defined_name_01
customer_defined_name_02
...
customer_defined_name_20
(255 char max per name)
string No 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"
  }
  • Up to 20 name-value pairs
  • 255 char max per name
  • 255 char max per value

Sample request body

{
"token": "my_business_02",
"metadata": {
"my_name_1": "my_value_1",
"my_name_2": "my_value_2"
},
"notes": "My notes",
"password": "My_passw0rd",
"phone": "1234567890",
"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": "1234567890",
"extension": "11",
"fax": "1234567890",
"email": "dr_me@my_business.com",
"full_name": "First Middle Last",
"mobile": "1234567890"
},
"proprietor_or_officer": {
"title": "Dr",
"dob": "1954-03-07",
"phone": "1234567890",
"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"
}
}
}

Sample response body

{
"token": "my_business_02",
"active": true,
"notes": "My notes",
"ip_address": "67.120.28.118",
"password": "___________",
"phone": "1234567890",
"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": "1234567890",
"extension": "11",
"fax": "1234567890",
"mobile": "1234567890",
"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": "1234567890",
"email": "dr_me@my_business.com"
},
"created_time": "2017-01-13T23:29:10Z",
"last_modified_time": "2017-01-13T23:29:10Z",
"deposit_account": {
"token": "420df02a-6aef-42bf-be7b-0d080ebf7573",
"account_number": "12342126720827265",
"routing_number": "293748000",
"allow_immediate_credit": false
},
"status": "ACTIVE"
}


Retrieve business

Action: GET
Endpoint: /businesses/{token}

To retrieve a specific business, issue 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, pagination, and sorting.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the business to retrieve. Existing business token.

Issue a GET to /businesses to retrieve business tokens.

Sample response body

{
"token": "my_business_02",
"active": true,
"notes": "My notes",
"ip_address": "67.120.28.118",
"password": "___________",
"phone": "1234567890",
"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": "1234567890",
"extension": "11",
"fax": "1234567890",
"mobile": "1234567890",
"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": "1234567890",
"email": "dr_me@my_business.com"
},
"created_time": "2017-01-13T23:29:10Z",
"last_modified_time": "2017-01-13T23:29:10Z",
"deposit_account": {
"token": "420df02a-6aef-42bf-be7b-0d080ebf7573",
"account_number": "12342126720827265",
"routing_number": "293748000",
"allow_immediate_credit": false
},
"status": "ACTIVE"
}


Update business

Action: PUT
Endpoint: /businesses/{token}

To update a business, issue 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

Name Type Required? Description Allowable Values
token string Yes Identifies the business to update. Existing business token.

Issue a GET to /businesses to retrieve business tokens.

Body field details

Name Type Required? Description Allowable Values
business_name_legal string No Legal name of business.

Required for verification (KYC) checks.
255 char max
business_name_dba string No Fictitious business name.

Required for verification (KYC) checks.
255 char max
office_location object No Address of business office.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.
in_current_location_since string No The date on which the business office opened in its current location. 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 No 10-digit telephone number of business.

Required for verification (KYC) checks.
123-456-7890 or 1234567890

Do not insert a 1 before the area code.
website string No URL of the business's website. 255 char max
date_established string No Date the business was established.

Required for verification (KYC) checks.
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 No General description of the business. 255 char max
history string No History of the business. 255 char max
account_holder_group_token string No Associates the specified account holder group with the business. Existing account holder group token.

Issue a GET to /accountholdergroups to retrieve account holder group tokens.
ip_address string No The IP address of the business. 39 char max
notes string No Any additional information pertaining to the business. 255 char max
business_type string No Indicates the type of business, for example B2B (business-to-business) or B2C (business-to-consumer). 255 char max
international_office_locations string No The locations of the business's offices outside the US. 255 char max
primary_contact object No Describes the business's primary contact.
duns_number string No Data Universal Numbering System (DUNS) number of business. 255 char max
incorporation object No Contains information regarding the business's incorporation.

Required for verification (KYC) checks.
proprietor_or_officer object No Contains information regarding the business's proprietor or officer.
metadata object No Associates customer-injected metadata with the business.
password string No Password for the business's account.
  • 8-20 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
identifications array No One or more objects containing identifying information about the business.

The office_location object

Name Type Required? Description Allowable Values
address1 string No Business office's street address.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.
35 char max
address2 string No Additional address information.

Cannot perform KYC if set to a PO Box.
35 char max
city string No Business office's city.

Required for verification (KYC) checks.
35 char max
state string No Business office's state.

Required for verification (KYC) checks.
35 char max
postal_code string No Business office's postal code.

Required for verification (KYC) checks.
20 char max
country string No Business office's country.

Required for verification (KYC) checks.
40 char max

The primary_contact object

Name Type Required? Description Allowable Values
full_name string No Name of primary contact. 255 char max
title string No Title of primary contact. 255 char max
department string No Department of primary contact. 255 char max
phone string No Telephone number of primary contact. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
extension string No Telephone extention of primary contact. 255 char max
fax string No Fax number of primary contact. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
mobile string No Mobile telephone number of primary contact. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
email string No Email address of primary contact. 255 char max

The incorporation object

Name Type Required? Description Allowable Values
is_public boolean No "True" indicates the business is publicly held. true | false

Default: false
incorporation_type string No The business's type of incorporation.

Required for verification (KYC) checks.
LLC | CORPORATION | SOLE_PROPRIETORSHIP | PARTNERSHIP | COOPERATIVE | OTHER
stock_symbol string No The business's stock symbol. 255 char max
state_of_incorporation string No The state in which the business is incorporated.

Required for verification (KYC) checks.
255 char max
name_registered_under string No The name under which the business is registered. 255 char max
address_registered_under object No The address under which the business is registered.

The incorporation.address_registered_under object

Name Type Required? Description Allowable Values
address1 string No Business's registered street address. 35 char max
address2 string No Additional address information. 35 char max
city string No Business's registered city. 35 char max
state string No Business's registered state. 35 char max
postal_code string No Business's registered postal code. 20 char max
country string No Business's registered country. 40 char max

The identifications array

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
Name Type Required? Description Allowable Values
type string Yes The form of identification.

Note: Required for KYC verification checks.
BUSINESS_TAX_ID | BUSINESS_NUMBER | TAXPAYER_REFERENCE
value string Yes The identification number associated with the form of identification. 255 char max
expiration_date string No The expiration date for the form of identification, if applicable. yyyy-MM-dd

The proprietor_or_officer object

Name Type Required? Description Allowable Values
first_name string No First name of business proprietor or officer. 255 char max
middle_name string No Middle name of business proprietor or officer. 255 char max
last_name string No Last name of business proprietor or officer. 255 char max
alternative_names string No Alternate names of business proprietor or officer. 255 char max
title string No Title of business proprietor or officer. 255 char max
home object No Describes the business proprietor or officer's home.
dob string No Business proprietor or officer's date of birth 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 No Telephone number of business proprietor or officer. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
email string No Email address of business proprietor or officer. 255 char max
identifications object No One or more objects containing identifying information about the business proprietor or officer.

The proprietor_or_officer.home object

Name Type Required? Description Allowable Values
address1 string No Street address of business proprietor or officer. 35 char max
address2 string No Additional address information. 35 char max
city string No City of business proprietor or officer. 35 char max
state string No State in which business proprietor or officer resides. 35 char max
postal_code string No Business proprietor or officer's postal code. 20 char max
country string No Country in which business proprietor or officer resides 40 char max

The proprietor_or_officer.identifications array

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
Name Type Required? Description Allowable Values
type string Yes The form of identification.

Note: SSN is required for KYC verification checks.
SSN | TIN | SIN | NIN
value string Yes The identification number associated with the form of identification. 255 char max
expiration_date string No The expiration date for the form of identification, if applicable. yyyy-MM-dd

The metadata object

Name Type Required? Description Allowable Values
customer_defined_name_01
customer_defined_name_02
...
customer_defined_name_20
(255 char max per name)
string No 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
  }

Up to 20 name-value pairs.

255 char max per name.

255 char max per value.

Sample request body

{
"phone": "9876543210"
}

Sample response body

{
"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": "1234567890",
"extension": "11",
"fax": "1234567890",
"mobile": "1234567890",
"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": "1234567890",
"email": "dr_me@my_business.com"
},
"created_time": "2017-01-13T23:29:10Z",
"last_modified_time": "2017-01-13T23:29:10Z",
"deposit_account": {
"token": "420df02a-6aef-42bf-be7b-0d080ebf7573",
"account_number": "12342126720827265",
"routing_number": "293748000",
"allow_immediate_credit": false
},
"status": "ACTIVE"
}


List businesses

Action: GET
Endpoint: /businesses

To return an array of all businesses, issue 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, pagination, and sorting.

Query parameters

Name Type Required? Description Allowable Values
business_name_legal string No Performs a non-case-sensitive match on the business's 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". 40 char max
business_name_dba string No Performs a non-case-sensitive match on the business's 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". 40 char max
dda string No Retrieves businesses with the specified deposit account number. Existing deposit account number

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

Issue a GET to /businesses to retrieve business tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "my_business_01",
"active": true,
"notes": "My notes",
"password": "___________",
"phone": "1234567890",
"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": "1234567890",
"extension": "11",
"fax": "1234567890",
"email": "dr_me@my_business.com",
"full_name": "First Middle Last",
"mobile": "1234567890"
},
"proprietor_or_officer": {
"title": "Dr",
"dob": "1954-03-07",
"phone": "1234567890",
"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": "2016-10-18T21:17:03Z",
"last_modified_time": "2016-10-19T22:48:02Z"
"status": "ACTIVE"
}
]
}


List business children

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

To return an array of all child users of a particular business, issue 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

Name Type Required? Description Allowable Values
parent_token string Yes Indentifies the business whose child-users you want to list. Existing business token.

Issue a GET to /businesses to retrieve business tokens.

Sample response body

{
"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",
"corporate_card_holder": false,
"parent_token": "my_business_01",
"uses_parent_account": true,
"created_time": "2016-10-20T17:50:36Z",
"last_modified_time": "2016-10-20T17:50:36Z",
"business_token": "my_business_01"
"status": "ACTIVE"
},
]
}


Retrieve business identification number

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

To retrieve the government-issued identification number of a business's proprietor, issue 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

Name Type Required? Description Allowable Values
token string Yes Identifies the business whose identification number you want to retrieve. Existing business token.

Issue a GET to /businesses to retrieve business tokens.

Query parameters

Name Type Required? Description Allowable Values
full_ssn boolean Yes 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.
true | false

Default: false

Sample response body

{
"ssn": "5555"
}


Create business transition

Action: POST
Endpoint: /businesstransition

This endpoint enables you to change a business's status, depending your role and the previous status change. By changing a business's status, you can control the business's capabilities and the setting of the business.active field. (You cannot control business.active 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 Can't 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 Can't load funds or activate cards. false
Closed The business is permanently inactive.

Note: In general, the Closed status should be terminal. For exceptional cases, you can transition a business to other statuses, depending on your role and the details of the previous status change. Contact your Marqeta Customer Success representative for more information.
false Can't load funds. ACTIVE | LIMITED | UNVERIFIED | SUSPENDED

In general, the Closed status should be terminal. For exceptional cases, you can transition a business to other statuses, depending on your role and the details of the previous status change. Contact your Marqeta Customer Success representative for more information.

Note: The Marqeta platform transitions a business's 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

Name Type Required? Description Allowable Values
token string No 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.
36 char max
business_token string Yes Identifies the business whose status is transitioned. Existing business token.

Issue a GET request to the /businesses endpoint to retrieve business tokens.
status string Yes Specifies the new status of the business. UNVERIFIED | LIMITED | ACTIVE | SUSPENDED | CLOSED
reason_code string Yes Identifies the standardized reason for the transition. See "The reason_code field" section.
reason string No Additional information about the status change. 255 char max
channel string Yes The mechanism by which the transaction was initiated. API | IVR | FRAUD | ADMIN | SYSTEM

The reason_code field

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.

Sample request body

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

Sample response body

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


Retrieve business transition

Action: GET
Endpoint: /businesstransitions/{token}

Use this endpoint to retrieve a business transition.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the business transition to retrieve. Existing business transition token.

Sample response body

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


List transitions for business

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

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

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the business associated with the transitions to retrieve. Existing business token.

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

Sample response body

{
"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": "2016-11-23T23:28:39Z"
}
]
}