/
15 minute read
March 30, 2022

Business Transitions

Use the /businesstransitions endpoints to transition business resources between states, as well as 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

Unique identifier of the business whose status you want to transition.

Allowable Values:

Existing business resource token

channel

string
Required

Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

idempotentHash

string
Optional

Unique hashed value that identifies subsequent submissions of the business transition request.

Allowable Values:

255 char max

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

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

Unique identifier of the business whose status you want to transition.

Allowable Values:

Existing business resource token

channel

string
Returned

Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

datetime
Conditionally returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

Date and time when the resource was last updated, in UTC.

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

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}

List all transitions for a given business.

URL path parameters

Fields Description

business_token

string
Required

Unique identifier of the business resource associated with the transitions to retrieve.

Allowable Values:

Existing business resource token

URL query parameters

Fields Description

count

integer
Optional

Number of business transitions to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

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:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-id

Response body

Fields Description

count

integer
Conditionally returned

The number of resources retrieved.

This field is returned if there are resources in your returned array.

Allowable Values:

1-10

data

array of objects
Conditionally returned

Array of business transition objects.

Objects are returned as appropriate to your query.

Allowable Values:

A valid array of one or more business transition objects

data[].business_token

string
Conditionally returned

Unique identifier of the business whose status you want to transition.

Allowable Values:

Existing business resource token

data[].channel

string
Returned

Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

data[].created_time

datetime
Conditionally returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

Date and time when the resource was last updated, in UTC.

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

Unique identifier of the business transition.

Allowable Values:

Existing business transition token

end_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your 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:

createdTime, lastModifiedTime, or any field in the resource model

Response body

Fields Description

business_token

string
Conditionally returned

Unique identifier of the business whose status you want to transition.

Allowable Values:

Existing business resource token

channel

string
Returned

Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

datetime
Conditionally returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

Date and time when the resource was last updated, in UTC.

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

Unique identifier of the business transition.

Allowable Values:

Existing business transition token

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter