/
15 minute read
March 30, 2022

Business Transitions

Use the /businesstransitions endpoints to transition business resources between states, and to retrieve and list state changes for a business resource.

Create business transition

Action: POST
Endpoint: /businesstransitions

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.
Request body
Fields Description

business_token

string
Required

Identifies the business whose status you want to transition.

Allowable Values:

Existing business token

channel

string
Required

The mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

reason

string
Optional

Additional information about the status change.

Allowable Values:

255 char max

reason_code

string
Required

Identifies the standardized reason for the transition:

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

status

string
Required

Specifies the new status of the business.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

business_token

string
Conditionally returned

Identifies the business whose status you want to transition.

Allowable Values:

Existing business token

channel

string
Returned

The mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last updated, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

reason

string
Conditionally returned

Additional information about the status change.

Allowable Values:

255 char max

reason_code

string
Returned

Identifies the standardized reason for the transition:

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

status

string
Returned

Specifies the status of the business.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

token

string
Returned

The unique identifier of the business transition.

Allowable Values:

Existing business transition token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List business transitions

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

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

URL path parameters
Fields Description

business_token

string
Required

The unique identifier of the business associated with the transitions to retrieve.

Allowable Values:

Existing business token

URL query parameters
Fields Description

count

integer
Optional

The number of business transitions to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources retrieved.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of business transition objects.

Allowable Values:

Valid data array

data[].business_token

string
Conditionally returned

Identifies the business whose status you want to transition.

Allowable Values:

Existing business token

data[].channel

string
Returned

The mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

data[].created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

The date and time when the resource was last updated, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].reason

string
Conditionally returned

Additional information about the status change.

Allowable Values:

255 char max

data[].reason_code

string
Returned

Identifies the standardized reason for the transition:

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

data[].status

string
Returned

Specifies the status of the business.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

data[].token

string
Returned

The unique identifier of the business transition.

Allowable Values:

Existing business transition token

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, `false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve business transition

Action: GET
Endpoint: /businesstransitions/{token}

Use this endpoint to retrieve a business transition.

URL path parameters
Fields Description

token

string
Required

The unique identifier of the business transition you want to retrieve.

Allowable Values:

Existing business transition token

URL query parameters
Fields Description

fields

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

Comma-delimited list of fields, or blank

Response body
Fields Description

business_token

string
Conditionally returned

Identifies the business whose status you want to transition.

Allowable Values:

Existing business token

channel

string
Returned

The mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last updated, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

reason

string
Conditionally returned

Additional information about the status change.

Allowable Values:

255 char max

reason_code

string
Returned

Identifies the standardized reason for the transition:

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

status

string
Returned

Specifies the status of the business.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

token

string
Returned

The unique identifier of the business transition.

Allowable Values:

Existing business transition token

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter