DOCS
Developer resources
Community

Collaborate on your project with other Marqeta developers

Sales

Speak with an expert to learn more about Marqeta

/
Guides
Core API

Launch and manage your company's payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta's reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

15 minute read
March 29, 2022

User Transitions

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

Create user transition
Copy section link

Action: POST
Endpoint: /usertransitions

Sign in to use API widgets
POST

This endpoint enables you to change a user’s status, depending on your role and the previous status change. By changing a user’s status, you can control the user’s capabilities and the setting of the user.active field. (You cannot control user.active directly.)

user.status Field Description User Limitations

UNVERIFIED

Initial status of a new user belonging to an account holder group where KYC is always required.
Allowable Transitions:
ACTIVE, CLOSED

Cannot load funds or activate cards.
user.active Field:
false

LIMITED

Initial status of a new user belonging to an account holder group where KYC is conditionally required.
Allowable Transitions:
ACTIVE, SUSPENDED, CLOSED

Restricted by rules in accountholdergroups.pre_kyc_controls.
user.active Field:
true

ACTIVE

Status of a user who has passed KYC, or initial status of a new user belonging to an account holder group where KYC is never required.
Allowable Transitions:
SUSPENDED, CLOSED, UNVERIFIED

None.
user.active Field:
true

SUSPENDED

The user is temporarily inactive.

Transitioning a suspended user to the ACTIVE status is restricted based on your role and the details of the previous status change.
Allowable Transitions:
ACTIVE, LIMITED, UNVERIFIED, CLOSED

Cannot load funds or activate cards.
user.active Field:
false

CLOSED

The user is permanently inactive.

In general, the CLOSED status should be terminal. For exceptional cases, you can transition a user to other statuses, depending on your role and the details of the previous status change. Contact your Marqeta representative for more information.
Allowable Transitions:
ACTIVE, LIMITED, UNVERIFIED, SUSPENDED

Cannot load funds or activate cards.
user.active Field:
false
Note
The Marqeta platform transitions a user’s status in response to certain events. For example, a user in the UNVERIFIED status is transitioned to ACTIVE when the user passes KYC verification.

Request body
Copy section link

Fields Description

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

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

token

string
Optional

The unique identifier of the user 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

user_token

string
Required

The unique identifier of the user whose status is transitioned.

Allowable Values:

Existing user token.

Send a GET request to the /users endpoint to obtain a user token.

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Response body
Copy section link

Fields Description

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.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, 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 new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

token

string
Returned

The unique identifier of the user transition.

Allowable Values:

Existing user transition token

user_token

string
Conditionally returned

The unique identifier of the user whose status is transitioned.

Allowable Values:

Existing user token.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List transitions for user
Copy section link

Action: GET
Endpoint: /usertransitions/user/{user_token}

Sign in to use API widgets
GET

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

URL path parameters
Copy section link

Fields Description

user_token

string
Required

The unique identifier of the user resource.

Allowable Values:

Existing user token

URL query parameters
Copy section link

Fields Description

count

integer
Optional

The number of user 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
Copy section link

Fields Description

count

integer
Conditionally returned

The number of user resources retrieved.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of user transition objects.

Allowable Values:

Valid data array

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.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, 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 new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

data[].token

string
Returned

The unique identifier of the user transition.

Allowable Values:

Existing user transition token

data[].user_token

string
Conditionally returned

The unique identifier of the user whose status is transitioned.

Allowable Values:

Existing user 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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Retrieve user transition
Copy section link

Action: GET
Endpoint: /usertransitions/{token}

Sign in to use API widgets
GET

Use this endpoint to retrieve a user transition.

URL path parameters
Copy section link

Fields Description

token

string
Required

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

Allowable Values:

Existing user transition token

URL query parameters
Copy section link

Fields Description

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

Response body
Copy section link

Fields Description

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.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, 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 new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

token

string
Returned

The unique identifier of the user transition.

Allowable Values:

Existing user transition token

user_token

string
Conditionally returned

The unique identifier of the user whose status is transitioned.

Allowable Values:

Existing user token.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Related materials

Join our developer newsletter

© 2023 Marqeta, Inc.

• Terms • API Terms • Privacy • Cookies
Back to Marqeta.com