DOCS

Marqeta.com
Support
/
Guides
Core API Reference
DiVA API Reference
Core API Explorer
45 minute read
February 11, 2021

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

Sign in to use API widgets
POST

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.

This field is required for KYC verification.

Allowable Values:

128 char max for KYC verification; 255 char max otherwise.

business_name_dba

string
Conditionally required

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

Note
This field is required for KYC verification if the fictitious business name is different from the legal business name.

Allowable Values:

128 char max for KYC verification; 255 char max otherwise.

office_location

object
Conditionally required

Address of business office.

This object is 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.

This field is 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.

This object is 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.

This object is 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
This object is 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
This object is 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
This object is 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
This object is 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.

This field is required for KYC verification.

Allowable Values:

true
,
false

attester_name

string
Conditionally required

The name of the attester for KYC verification.

This field is 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.

This field is 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
This field is 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.

This field is 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.

This field is required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

Business office’s state.

This field is required for KYC verification.

Allowable Values:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 35 char max otherwise.

zip

string
Deprecated

Five- or nine-digit US ZIP code.

This field is deprecated and will be removed from this endpoint in the future. Use the

postal_code
field.

Allowable Values:

N/A

country

string
Conditionally required

Business office’s country.

This field is required for KYC verification.

Allowable Values:

ISO alpha-2 country code required for KYC verification (

US
, for example). Otherwise, 40 char max.

postal_code

string
Conditionally required

Business office’s postal code.

This field is required for KYC verification.

Allowable Values:

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

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

This field is 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.

This field is required for KYC verification.

Allowable Values:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 255 char max otherwise.

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.

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
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
Nine-digit EIN with no delimiters required for KYC verification. 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:

2 char min, 36 char max for KYC verification; 255 char max otherwise.

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:

2 char min, 48 char max required for KYC verification; 255 char max otherwise.

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.

This object is required for KYC verification.

Allowable Values:

Existing

proprietor_or_officer.home
object.

dob

string
Conditionally required

Business proprietor or officer’s date of birth.

This field is 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.

This array is 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.

This field is required for KYC verification. 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
Conditionally required

City of business proprietor or officer.

This field is required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

State in which business proprietor or officer resides.

This field is required for KYC verification.

Allowable Values:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 35 char max otherwise.

postal_code

string
Conditionally required

Business proprietor or officer’s postal code.

This field is required for KYC verification.

Allowable Values:

20 char max

country

string
Conditionally required

Country in which business proprietor or officer resides.

Allowable Values:

ISO alpha-2 country code required for KYC verification (

US
, for example); 40 char max otherwise.
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.

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:

Copied

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:

2 char min, 36 char max for KYC verification; 255 char max otherwise.

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:

2 char min, 48 char max for KYC verification; 255 char max otherwise.

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:

Digits only, do not use separators. 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.

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:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 35 char max otherwise.

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:

ISO alpha-2 country code required for KYC verification (

US
, for example); 40 char max otherwise.
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve business
Copy section link

Action:

GET

Endpoint:
/businesses/{token}

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

Update business
Copy section link

Action:

PUT

Endpoint:
/businesses/{token}

Sign in to use API widgets
PUT

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.

This field is required for KYC verification.

Allowable Values:

128 char max for KYC verification; 255 char max otherwise.

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.

This field is 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.

This field is 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.

This object is 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.

This object is 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
This object is 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
This object is 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
This object is 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
This object is 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.

This field is required for KYC verification.

Allowable Values:

true
,
false

attester_name

string
Conditionally required

The name of the attester for KYC verification.

This field is 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.

This field is 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
This field is 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.

This field is required for KYC verification. 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
Conditionally required

Business office’s city.

This field is required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

Business office’s state.

This field is required for KYC verification.

Allowable Values:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 35 char max otherwise.

zip

string
Deprecated

Five- or nine-digit US ZIP code.

This field is deprecated and will be removed from this endpoint in the future. Use the

postal_code
field.

Allowable Values:

N/A

country

string
Conditionally required

Business office’s country.

This field is required for KYC verification.

Allowable Values:

ISO alpha-2 country code required for KYC verification (

US
, for example); 40 char max otherwise.

postal_code

string
Conditionally required

Business office’s postal code.

This field is required for KYC verification.

Allowable Values:

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

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

This field is 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.

This field is required for KYC verification.

Allowable Values:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 255 char max otherwise.

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.

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

2 char min, 36 char max for KYC verification; 255 char max otherwise.

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:

2 char min, 48 char max for KYC verification; 255 char max otherwise.

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.

This object is required for KYC verification.

Allowable Values:

Existing

proprietor_or_officer.home
object.

dob

string
Conditionally required

Business proprietor or officer’s date of birth.

This field is 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.

This array is 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.

This field is required for KYC verification. Cannot perform KYC verification if set to a PO Box.

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.

This field is required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

State in which business proprietor or officer resides.

This field is required for KYC verification.

Allowable Values:

Valid two-letter state, provincial, or territorial abbreviation required for KYC verification; 35 char max otherwise.

postal_code

string
Conditionally required

Business proprietor or officer’s postal code.

This field is required for KYC verification.

Allowable Values:

20 char max

country

string
Conditionally required

Country in which business proprietor or officer resides.

This field is 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:

Copied

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:

Copied

Add a new field:

Copied

Delete an existing field:

Copied

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:

2 char min, 36 char max for KYC verification; 255 char max otherwise.

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:

2 char min, 48 char max for KYC verification; 255 char max otherwise.

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:

Digits only, do not use separators. 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.

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:

ISO alpha-2 country code (

US
, for example).
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List businesses
Copy section link

Action:

GET

Endpoint:
/businesses

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

Search businesses
Copy section link

Action:

POST

Endpoint:
/businesses/lookup

Sign in to use API widgets
POST

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
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List business children
Copy section link

Action:

GET

Endpoint:
/businesses/{parent_token}/children

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

Retrieve business identification number
Copy section link

Action:

GET

Endpoint:
/businesses/{token}/ssn

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

Create business transition
Copy section link

Action:

POST

Endpoint:
/businesstransitions

Sign in to use API widgets
POST

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

This address cannot accept mail or the addressee is unknown.

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.

19

Changed to

ACTIVE
because account activity was properly validated.

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
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve business transition
Copy section link

Action:

GET

Endpoint:
/businesstransitions/{token}

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

List transitions for business
Copy section link

Action:

GET

Endpoint:
/businesstransitions/business/{token}

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No
Related materials

Feedback on this page?

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

© 2021 Marqeta, Inc.

• Terms
 • API Terms
 • Privacy
 • Cookies