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:
Endpoint:
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
For information about configuring the required fields for KYC verification, see Perform KYC.
Body field details
Copy section link
Fields | Description |
---|---|
token
string
|
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
|
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
|
Fictitious business name ("Doing Business As" or DBA).
NoteThis 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
|
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
|
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
|
10-digit telephone number of business. Allowable Values: Format: 510-555-1212 or 5105551212 |
website
string
|
URL of the business' website. Allowable Values: 255 char max |
date_established
string
|
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
|
General description of the business. Allowable Values: 255 char max |
history
string
|
History of the business. Allowable Values: 255 char max |
account_holder_group_token
string
|
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
|
The IP address of the business. Allowable Values: 39 char max |
notes
string
|
Any additional information pertaining to the business. Allowable Values: 255 char max |
business_type
string
|
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
|
The locations of the business' offices outside the US. Allowable Values: 255 char max |
primary_contact
object
|
Describes the business' primary contact. Allowable Values: Existing primary_contact object
|
duns_number
string
|
Data Universal Numbering System (DUNS) number of the business. Allowable Values: 255 char max |
incorporation
object
|
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
|
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
|
Associates customer-injected metadata with the business. Allowable Values: Existing metadata object.
|
password
string
|
Password for the business account. Allowable Values:
|
identifications
array
|
One or more objects containing identifying information about the business. Allowable Values: Existing identifications array.
|
beneficial_owner1
object
|
Contains information about the beneficial owner of the business, if applicable.
NoteThis object is required for KYC verification if the business has a beneficial owner. Do not include information about the proprietor or business officer in abeneficial_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
|
Contains information about the second beneficial owner of the business, if applicable.
NoteThis 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 abeneficial_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
|
Contains information about the third beneficial owner of the business, if applicable.
NoteThis 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 abeneficial_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
|
Contains information about the fourth beneficial owner of the business, if applicable.
NoteThis 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 abeneficial_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
|
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
|
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
|
The title of the attester for KYC verification. Allowable Values: The title of the attester. For example, Chief Executive Officer. |
attestation_date
string
|
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
|
Indicates that the proprietor or officer of the business is also a beneficial owner.
NoteThis 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
|
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
|
Additional address information. Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max |
city
string
|
Business office’s city. This field is required for KYC verification. Allowable Values: 40 char max |
state
string
|
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
|
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
|
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
|
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
|
Name of primary contact. Allowable Values: 255 char max |
title
string
|
Title of primary contact. Allowable Values: 255 char max |
department
string
|
Department of primary contact. Allowable Values: 255 char max |
phone
string
|
Telephone number of primary contact. Allowable Values: Format: 510-555-1212 or 5105551212 Do not insert a 1 before the area code. |
extension
string
|
Telephone extension of primary contact. Allowable Values: 255 char max |
fax
string
|
Fax number of primary contact. Allowable Values: Format: 510-555-1212 or 5105551212 Do not insert a 1 before the area code. |
mobile
string
|
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
|
Email address of primary contact. Allowable Values: 255 char max |
The incorporation object
Copy section link
Fields | Description |
---|---|
is_public
boolean
|
A value of true indicates that the business is publicly held.
Allowable Values: true , false
Default value: false
|
incorporation_type
string
|
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
|
The business' stock symbol. Allowable Values: 255 char max |
state_of_incorporation
string
|
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
|
The name under which the business is registered. Allowable Values: 255 char max |
address_registered_under
object
|
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
|
Business' registered street address. Allowable Values: 255 char max |
address2
string
|
Additional address information. Allowable Values: 255 char max |
city
string
|
Business' registered city. Allowable Values: 40 char max |
state
string
|
Business' registered state. Allowable Values: 35 char max |
postal_code
string
|
Business' registered postal code. Allowable Values: 20 char max |
country
string
|
Business' registered country. Allowable Values: 40 char max |
The identifications array
Copy section link
You can add one or more objects to the
Only one of the following identification types can be associated with a business:
-
Business Tax ID
-
Business Number
-
Taxpayer Reference
Fields | Description |
---|---|
type
string
|
The form of identification.
NoteBUSINESS_TAX_ID required for KYC verification.
Allowable Values: BUSINESS_TAX_ID , BUSINESS_NUMBER , TAXPAYER_REFERENCE
|
value
string
|
The identification number associated with the form of identification. Allowable Values: 255 char max
NoteNine-digit EIN with no delimiters required for KYC verification. For example: 123456789 |
expiration_date
string
|
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
|
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
|
Middle name of business proprietor or officer. Allowable Values: 255 char max |
last_name
string
|
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
|
Alternate names of business proprietor or officer. Allowable Values: 255 char max |
title
string
|
Title of business proprietor or officer. Allowable Values: 255 char max |
home
object
|
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
|
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
|
Telephone number of business proprietor or officer. Allowable Values: Format: 510-555-1212 or 5105551212 |
email
string
|
Email address of business proprietor or officer. Allowable Values: 255 char max |
identifications
array
|
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
|
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
|
Additional address information. Allowable Values: 255 char max |
city
string
|
City of business proprietor or officer. This field is required for KYC verification. Allowable Values: 40 char max |
state
string
|
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
|
Business proprietor or officer’s postal code. This field is required for KYC verification. Allowable Values: 20 char max |
country
string
|
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
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
|
The form of identification.
NoteFull SSN is required for KYC verification.Allowable Values: SSN , TIN , SIN , NIN
|
value
string
|
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
|
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
|
Associates customer-injected metadata with the business. You can define the names and values of up to 20 fields. For example:
Copied Allowable Values:
|
The beneficial_owner object
Copy section link
The
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 theFields | Description |
---|---|
first_name
string
|
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
|
The middle name of the beneficial owner. Allowable Values: 255 char max |
last_name
string
|
The last name of the beneficial owner. Allowable Values: 2 char min, 48 char max for KYC verification; 255 char max otherwise. |
title
string
|
The title of the beneficial owner. Allowable Values: 255 char max |
home
object
|
The home address of the beneficial owner. Allowable Values: Existing beneficial_owner.home object.
|
ssn
string
|
The nine-digit Social Security Number of the beneficial owner. Allowable Values: Digits only, do not use separators. For example: 123456789 |
dob
string
|
The date of birth of the beneficial owner. Allowable Values: yyyy-MM-dd |
phone
string
|
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
|
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
|
Additional address information. Allowable Values: 255 char max |
city
string
|
The city of the beneficial owner’s home. Allowable Values: 40 char max |
state
string
|
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
|
The postal code of the beneficial owner’s home. Allowable Values: 20 char max |
country
string
|
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.
|
Retrieve business
Copy section link
Action:
Endpoint:
To retrieve a specific business, send a
This endpoint supports field filtering and sorting and pagination.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the business to retrieve. Allowable Values: Existing business token. Send a GET request to /businesses to retrieve business tokens.
|
Update business
Copy section link
Action:
Endpoint:
To update a business, send a
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
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
|
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
|
Fictitious business name ("Doing Business As" or DBA).
NoteRequired for KYC verification if the fictitious business name is different from the legal business name.Allowable Values: 255 char max |
office_location
object
|
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
|
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
|
10-digit telephone number of business. Allowable Values: Format: 510-555-1212 or 5105551212 |
website
string
|
URL of the business' website. Allowable Values: 255 char max |
date_established
string
|
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
|
General description of the business. Allowable Values: 255 char max |
history
string
|
History of the business. Allowable Values: 255 char max |
account_holder_group_token
string
|
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
|
The IP address of the business. Allowable Values: 39 char max |
notes
string
|
Any additional information pertaining to the business. Allowable Values: 255 char max |
business_type
string
|
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
|
The locations of the business' offices outside the US. Allowable Values: 255 char max |
primary_contact
object
|
Describes the business' primary contact. Allowable Values: Existing primary_contact object.
|
duns_number
string
|
Data Universal Numbering System (DUNS) number of the business. Allowable Values: 255 char max |
incorporation
object
|
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
|
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
|
Associates customer-injected metadata with the business. Allowable Values: Existing metadata object.
|
password
string
|
Password for the business' account. Allowable Values:
|
identifications
array
|
One or more objects containing identifying information about the business. Allowable Values: Existing identifications array.
|
beneficial_owner1
object
|
Contains information about the beneficial owner of the business, if applicable.
NoteThis object is required for KYC verification if the business has a beneficial owner. Do not include information about the proprietor or business officer in abeneficial_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
|
Contains information about the second beneficial owner of the business, if applicable.
NoteThis 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 abeneficial_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
|
Contains information about the third beneficial owner of the business, if applicable.
NoteThis 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 abeneficial_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
|
Contains information about the fourth beneficial owner of the business, if applicable.
NoteThis 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 abeneficial_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
|
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
|
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
|
The title of the attester for KYC verification. Allowable Values: The title of the attester. For example, Chief Executive Officer. |
attestation_date
string
|
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
|
Indicates that the proprietor or officer of the business is also a beneficial owner.
NoteThis 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 abeneficial_owner object.
Allowable Values: true , false
Default value: false
|
The office_location object
Copy section link
Fields | Description |
---|---|
address1
string
|
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
|
Additional address information. Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max |
city
string
|
Business office’s city. This field is required for KYC verification. Allowable Values: 40 char max |
state
string
|
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
|
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
|
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
|
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
|
Name of primary contact. Allowable Values: 255 char max |
title
string
|
Title of primary contact. Allowable Values: 255 char max |
department
string
|
Department of primary contact. Allowable Values: 255 char max |
phone
string
|
Telephone number of primary contact. Allowable Values: Format: 510-555-1212 or 5105551212 Do not insert a 1 before the area code. |
extension
string
|
Telephone extension of primary contact. Allowable Values: 255 char max |
fax
string
|
Fax number of primary contact. Allowable Values: Format: 510-555-1212 or 5105551212 Do not insert a 1 before the area code. |
mobile
string
|
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
|
Email address of primary contact. Allowable Values: 255 char max |
The incorporation object
Copy section link
Fields | Description |
---|---|
is_public
boolean
|
A value of true indicates that the business is publicly held.
Allowable Values: true , false
Default value: false
|
incorporation_type
string
|
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
|
The business' stock symbol. Allowable Values: 255 char max |
state_of_incorporation
string
|
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
|
The name under which the business is registered. Allowable Values: 255 char max |
address_registered_under
object
|
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
|
Business' registered street address. Allowable Values: 255 char max |
address2
string
|
Additional address information. Allowable Values: 255 char max |
city
string
|
Business' registered city. Allowable Values: 40 char max |
state
string
|
Business' registered state. Allowable Values: 35 char max |
postal_code
string
|
Business' registered postal code. Allowable Values: 20 char max |
country
string
|
Business' registered country. Allowable Values: 40 char max |
The identifications array
Copy section link
You can add one or more objects to the
Only one of the following identification types can be associated with a business:
-
Business Tax ID
-
Business Number
-
Taxpayer Reference
Fields | Description |
---|---|
type
string
|
The form of identification.
NoteBUSINESS_TAX_ID required for KYC verification.
Allowable Values: BUSINESS_TAX_ID , BUSINESS_NUMBER , TAXPAYER_REFERENCE
|
value
string
|
The identification number associated with the form of identification. Allowable Values: 255 char max
NoteDigits only, do not use separators. For example: 123456789 |
expiration_date
string
|
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
|
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
|
Middle name of business proprietor or officer. Allowable Values: 255 char max |
last_name
string
|
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
|
Alternate names of business proprietor or officer. Allowable Values: 255 char max |
title
string
|
Title of business proprietor or officer. Allowable Values: 255 char max |
home
object
|
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
|
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
|
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
|
Email address of business proprietor or officer. Allowable Values: 255 char max |
identifications
array
|
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
|
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
|
Additional address information. Allowable Values: 255 char max |
city
string
|
City of business proprietor or officer. This field is required for KYC verification. Allowable Values: 40 char max |
state
string
|
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
|
Business proprietor or officer’s postal code. This field is required for KYC verification. Allowable Values: 20 char max |
country
string
|
Country in which business proprietor or officer resides. This field is required for KYC verification. Allowable Values: 40 char max
NoteISO 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
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
|
The form of identification.
NoteFull SSN is required for KYC verification.Allowable Values: SSN , TIN , SIN , NIN
|
value
string
|
The identification number associated with the form of identification. Allowable Values: 255 char max
NoteDigits only, do not use separators. For example: 123456789 |
expiration_date
string
|
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:
|
The beneficial_owner object
Copy section link
The
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 theFields | Description |
---|---|
first_name
string
|
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
|
The middle name of the beneficial owner. Allowable Values: 255 char max |
last_name
string
|
The last name of the beneficial owner. Allowable Values: 2 char min, 48 char max for KYC verification; 255 char max otherwise. |
title
string
|
The title of the beneficial owner. Allowable Values: 255 char max |
home
object
|
The home address of the beneficial owner. Allowable Values: Existing beneficial_owner.home object.
|
ssn
string
|
The nine-digit Social Security Number of the beneficial owner. Allowable Values: Digits only, do not use separators. For example: 123456789 |
dob
string
|
The date of birth of the beneficial owner. Allowable Values: yyyy-MM-dd |
phone
string
|
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
|
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
|
Additional address information. Allowable Values: 255 char max |
city
string
|
The city of the beneficial owner’s home. Allowable Values: 40 char max |
state
string
|
The state or province of the beneficial owner’s home. Allowable Values: 35 char max |
postal_code
string
|
The postal code of the beneficial owner’s home. Allowable Values: 20 char max |
country
string
|
The country of the beneficial owner’s home. Allowable Values: ISO alpha-2 country code ( US , for example).
|
List businesses
Copy section link
Action:
Endpoint:
To return an array of all businesses, send a
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
|
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
|
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 |
Search businesses
Copy section link
Action:
Endpoint:
To search for one or more businesses, send a
Body field details
Copy section link
Fields | Description |
---|---|
dda
string
|
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.
|
List business children
Copy section link
Action:
Endpoint:
To return an array of all child users of a particular business, send a
This endpoint supports field filtering.
URL path parameters
Copy section link
Fields | Description |
---|---|
parent_token
string
|
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.
|
Retrieve business identification number
Copy section link
Action:
Endpoint:
To retrieve the government-issued identification number of a business' proprietor, send a
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
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
|
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
|
Create business transition
Copy section link
Action:
Endpoint:
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
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. NoteTransitioning a suspended business to theACTIVE 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. NoteCLOSED 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
Body field details
Copy section link
Fields | Description |
---|---|
token
string
|
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
|
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
|
Specifies the new status of the business. Allowable Values: UNVERIFIED , LIMITED , ACTIVE , SUSPENDED , CLOSED
|
reason_code
string
|
Identifies the standardized reason for the transition. Allowable Values: See The reason-code field section. |
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
channel
string
|
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. |
Retrieve business transition
Copy section link
Action:
Endpoint:
Use this endpoint to retrieve a business transition.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the business transition to retrieve. Allowable Values: Existing business transition token. |
List transitions for business
Copy section link
Action:
Endpoint:
Use this endpoint to list all transitions for a given business.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
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.
|