Create User

Action: POST
Endpoint:
/users

To create a user, send a POST request to the /users endpoint and include the user details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

To create a child user, submit a POST request to the /users endpoint. In the request body, set the parent_token field to the value of the parent's token field. The parent must be an existing user or business. If either the parent or the parent's parent is a business, a business_token field is added to the user. This field's value is set to the token of either the parent or grandparent (whichever is the business).

The uses_parent_account field determines whether the child shares balances with the parent (true) or whether the child balances are independent of the parent (false). Note that if you do not specify a value for uses_parent_account, it will be set to false by default (meaning the user does not share the parent's balance) and returned in the response body. This field cannot be updated, so you must decide upon creation whether the child user will share the parent balance.

If you plan to perform a verification check (Know Your Customer - KYC) on users, the users resource must have the following fields configured:

  • first_name
  • last_name
  • address1 (cannot be a PO Box)
  • city
  • state
  • zip
  • country
  • birth_date
  • ssn (full or last four)

Body Field Details

Name Type Required? Description Allowable Values
token string No The unique identifier of the user. If you do not include a token, the system will generate 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. 36 char max
honorific string No The user's title/prefix: Ms., Mr., Miss, Mrs. 10 char max
gender string No The gender of the user. M | F
email string No A valid email address for the user.

This value must be unique among users.
255 char max
address1 string No The address of the user.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.
255 char max
address2 string No Additional address information for the user.

Cannot perform KYC if set to a PO Box.
255 char max
city string No The city that corresponds to the address.

Required for verification (KYC) checks.
40 char max
state string No The state that corresponds to the address.

Required for verification (KYC) checks.
2 char max
zip string No Zip code.

Required for verification (KYC) checks.
10 char max
country string No Country in which user resides.

Required for verification (KYC) checks.
40 char max
metadata object No Associates customer-injected metadata with the user.
nationality string No Nationality of the user. 255 char max
notes string No Any additional information pertaining to the user. 255 char max
phone string No 10-digit phone number of the user. 123-456-7890 or 1234567890

Do not insert a 1 before the area code.
ssn string No User's social security number.

Required for verification (KYC) checks.
Full or last 4 digits
(numerals only)
middle_name string No User's middle name. 40 char max
first_name string No User's first name.

Required for verification (KYC) checks.
40 char max
birth_date string No The date of birth of the user.

Required for verification (KYC) checks.
yyyy-MM-dd
last_name string No User's last name.

Required for verification (KYC) checks.
40 char max
uses_parent_account boolean No Indicates whether the child shares balances with the parent (true), or whether the child balances are independent of the parent (false).

If set to true, must also include a parent_token in the request. This value cannot be updated.
true | false;

Default: false
parent_token string No The unique identifier of a user/business already in the system.

Required if uses_parent_account = true. This user/business will be configured as the parent of the current user.
Existing user or business token.

Issue a GET to /users to retrieve user tokens or /businesses to retrieve business tokens.
passport_number string No The user's passport number. 255 char max
passport_expiration_date string No The user's passport expiration date. yyyy-MM-dd
id_card_number string No The ID number of the user's government issued ID card. 255 char max
id_card_expiration_date string No The expiration date of the user's ID card. yyyy-MM-dd
password string No Password for user account.
  • 8-20 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
corporate_card_holder boolean No Set to true if user holds a corporate card. true | false;

Default: false
company string No Company name. 255 char max
ip_address string No The IP address of the user. 45 char max
active boolean No Indicates whether the user is active. true | false
account_holder_group_token string No Associates the specified account holder group with the user. Existing account holder group token.

Issue a GET to /accountholdergroups to retrieve account holder group tokens.

metadata

Name Type Required? Description Allowable Values
customer_defined_name_01
customer_defined_name_02

...

customer_defined_name_20

(255 char max per name)
string No Associates customer-injected metadata with the user. The Marqeta customer defines the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
  }
Up to 20 name-value pairs.

255 char max per name; 255 char max per value.

Sample Request Body

{
"first_name": "Blue",
"last_name": "Bird",
"token": "bluebird_token",
"email": "bluebird@gmail.com",
"password": "My_passw0rd",
"ssn": "4444",
"birth_date": "1991-01-01",
"address1": "1234 Blake Street",
"city": "Berkeley",
"state": "CA",
"country": "USA",
"zip": "94702",
"phone": "5101111111",
"gender": "M",
"uses_parent_account": false,
"corporate_card_holder": false,
"active": true,
"metadata": {
"key1":"value1",
"key2":"value2"
}
}

Sample Response Body

{
"token": "bluebird_token",
"first_name": "Blue",
"last_name": "Bird",
"active": true,
"email": "bluebird@gmail.com",
"address1": "1234 Blake Street",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country": "USA",
"phone": "5101111111",
"metadata": {
"key1":"value1",
"key2":"value2"
},
"uses_parent_account": false,
"ssn": "___________",
"gender": "M",
"password": "___________",
"birth_date": "1991-01-31",
"corporate_card_holder": false,
"deposit_account": {
"account_number": "12343054860200",
"routing_number": "293748000",
"allow_immediate_credit": false
}
}


Retrieve User

Action: GET
Endpoint: /users/{token}

To retrieve a specific user, issue a GET request to the /users/{token} endpoint. Include the user token path parameter to specify the user to return.

The business_token field is conditionally returned in the response (it cannot be set by way of the API). You can use this field in conjunction with the parent_token field to determine whether the user has a parent or grandparent that is a business:

parent_token business_token Description
Not populated Not populated User does not have a parent.
Populated Not populated User's parent is a user.
Populated; matches business_token Populated; matches parent_token User's parent is a business.
Populated; does not match business_token Populated; does not match parent_token User's parent is a user and the parent's parent is a business.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes The token identifying the user you wish to retrieve. Existing user token.

Issue a GET to /users to retrieve existing user tokens.

Sample Response Body

{
"token": "bluebird_token",
"honorific": "Sir",
"first_name": "Blue",
"last_name": "Bird",
"active": true,
"email": "bluebird@gmail.com",
"address1": "1234 Blake Street",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country": "USA",
"phone": "5101111111",
"metadata": {
"key1":"value1",
"key2":"value2"
},
"uses_parent_account": false,
"ssn": "___________",
"gender": "M",
"password": "___________",
"birth_date": "1991-01-31",
"corporate_card_holder": false
}


Update User

Action: PUT
Endpoint: /users/{token}

To update a user, issue a PUT request to /users/{token}. Use the token path parameter to specify the user to update. Include the user 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

Name Type Required? Description Allowable Values
token string Yes The token identifying the user to update. Existing user token. Issue GET to /users to retrieve an existing user token.

Body Field Details

Name Type Required? Description Allowable Values
active boolean No Indicates whether the user is active. true | false
honorific string No The user's title/prefix: Ms., Mr., Miss, Mrs. 10 char max
gender string No The gender of the user. M | F
email string No A valid email address for the user.

This value must be unique among users.
255 char max
address1 string No The address of the user.

Required for verification (KYC) checks. Cannot perform KYC if set to a PO Box.
255 char max
address2 string No Additional address information for the user.

Cannot perform KYC if set to a PO Box.
255 char max
city string No The city that corresponds to the address.

Required for verification (KYC) checks.
40 char max
state string No The state that corresponds to the address.

Required for verification (KYC) checks.
2 char max
zip string No Zip code.

Required for verification (KYC) checks.
10 char max
country string No Country in which user resides.

Required for verification (KYC) checks.
40 char max
metadata object No Associates customer-injected metadata with the user.
nationality string No Nationality of the user. 255 char max
notes string No Any additional information pertaining to the user. 255 char max
phone string No 10-digit phone number of the user. 123-456-7890 or 1234567890

Do not insert a "1" before the area code.
ssn string No User's social security number.

Required for verification (KYC) checks.
Full or last 4 digits; numerals only
middle_name string No User's middle name. 40 char max
first_name string No User's first name.

Required for verification (KYC) checks.
40 char max
last_name string No User's last name.

Required for verification (KYC) checks.
40 char max
birth_date string No The date of birth of the user.

Required for verification (KYC) checks.
yyyy-MM-dd
parent_token string No The unique identifier of a user already in the system.

Required if uses_parent_account = true. This user will be configured as the parent of the current user.
Existing user token
passport_number string No The user's passport number. 255 char max
passport_expiration_date string No The user's passport expiration date. yyyy-MM-dd
id_card_number string No The ID number of the user's government issued ID card. 255 char max
id_card_expiration_date string No The expiration date of the user's ID card. yyyy-MM-dd
ip_address string No The IP address of the user. 45 char max
corporate_card_holder boolean No Set to true if corporate card. true | false; Default: false
company string No Company name. 255 char max
account_holder_group_token string No Associates the specified account holder group with the user. Existing account holder group token.

Issue a GET to /accountholdergroups to retrieve account holder group tokens.

metadata

Name Type Required? Description Allowable Values
customer_defined_name_01
customer_defined_name_02

...

customer_defined_name_20

(255 char max per name)
string No Associates customer-injected metadata with the user. The Marqeta customer defines the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
  }


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:

"metadata": {
  "my_name_1": "my_updated_value"
  }


Add a new field:

"metadata": {
  "my_new_field": "my_value"
  }


Delete an existing field:
"metadata": {
  "my_name_1": null
  }

Up to 20 name-value pairs.

255 char max per name; 255 char max per value

Sample Request Body

{
"metadata": {
"key2": null
}
}


Sample Response Body

{
"token": "bluebird_token",
"honorific": "Sir",
"first_name": "Blue",
"last_name": "Bird",
"active": true,
"email": "bluebird@gmail.com",
"address1": "1234 Blake Street",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country": "USA",
"phone": "5101111111",
"metadata": {
"key1":"value1"
},
"uses_parent_account": false,
"ssn": "___________",
"gender": "M",
"password": "___________",
"birth_date": "1991-01-31",
"corporate_card_holder": false
}


List Users

Action: GET
Endpoint: /users

To return an array of all users, issue a GET request to the /users endpoint.

To narrow your result set to users that match a particular name, telephone number, or email address, include the appropriate parameters from the following Query Parameters table. This endpoint also supports the query parameters described on the Field Filtering and Pagination & Sorting pages.

The business_token field is conditionally returned in the response (it cannot be set by way of the API). You can use this field in conjunction with the parent_token field to determine whether the user has a parent or grandparent that is a business:

parent_token business_token Description
Not populated Not populated User does not have a parent.
Populated Not populated User's parent is a user.
Populated; matches business_token Populated; matches parent_token User's parent is a business.
Populated; does not match business_token Populated; does not match parent_token User's parent is a user and the parent's parent is a business.

Query Parameters

Name Type Required? Description Allowable Values
first_name string No Performs a non-case-sensitive match on the users' first_name field. Matching is partial on the beginning of the name. For example, a match on "Alex" will return both "Alex" and "Alexander". 40 char max
last_name string No Performs a non-case-sensitive match on the users' last_name field. Matching is partial on the beginning of the name. For example, a match on "Smith" will return both "Smith" and "Smithline". 40 char max
phone string No Performs a match on the users' phone field. A valid and complete user telephone number
email string No Performs a non-case-sensitive, exact match on the users' email field. A valid and complete user email address
ssn string No Performs a match on the users' ssn (Social Security Number) field. Either a complete SSN or the last four digits.

Numerals only; do not use hyphens.
dda string No Retrieves users with the specified direct deposit account (DDA) number. Existing DDA number

Issue a GET to /directdeposits/accounts/{user_token} to retrieve the DDA number for a specific user.

Issue a GET to /users to retrieve user tokens.

Sample Response Body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": true,
"data": [
{
"token": "betsybird_token",
"first_name": "Betsy",
"last_name": "Bird",
"active": true,
"email": "betsybird@gmail.com",
"address1": "1234 Blake Street",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country": "USA",
"phone": "5101111112",
"uses_parent_account": false,
"ssn": "___________",
"gender": "F",
"password": "___________",
"birth_date": "1991-01-30",
"corporate_card_holder": false
},
{
"token": "bluebird_token",
"honorific": "Sir",
"first_name": "Blue",
"last_name": "Bird",
"active": true,
"email": "bluebird@gmail.com",
"address1": "1234 Blake Street",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country": "USA",
"phone": "5101111111",
"uses_parent_account": false,
"ssn": "___________",
"gender": "M",
"password": "___________",
"birth_date": "1991-01-31",
"corporate_card_holder": false
}
]
}


List User Children

Action: GET
Endpoint: /users/{parent_token}/children

To retrieve users who are children of another user or of a business (the parent), issue a GET request to the /users/{parent_token}/children endpoint. Include the parent's user/business token as a URL path parameter.

The business_token field is conditionally returned in the response (it cannot be set by way of the API). You can use this field in conjunction with the parent_token field to determine whether the user has a parent or grandparent that is a business:

parent_token business_token Description
Not populated Not populated User does not have a parent.
Populated Not populated User's parent is a user.
Populated; matches business_token Populated; matches parent_token User's parent is a business.
Populated; does not match business_token Populated; does not match parent_token User's parent is a user and the parent's parent is a business.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
parent_token string Yes The token of the parent user/business. Existing user/business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.

Sample Response Body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "user_child",
"first_name": "Cindy",
"last_name": "Taylor",
"active": true,
"email": "CindyT@gmail.com",
"address1": "1000 Money Lane",
"city": "Yountville",
"state": "CA",
"zip": "97543",
"parent_token": "my_user",
"uses_parent_account": true,
"birth_date": "1990-09-19"
}
]
}


Verify User Email Address

Verifying a user's email address is a two-step process. First you request an email verification token, and then you use that token in a subsequent request to verify the email.

STEP 1

Action: POST
Endpoint: /users/auth/verifyemail

To request an email verification token, send a POST to the /users/auth/verifyemail endpoint. (No input parameters are required because this operation is performed in the context of an authenticated user.) This request generates and sends an email message containing the email_verification_token to the user's email address. (The email message must be customized with a link that passes the email_verification_token to a web page where a subsequent request verifies the email address.) You set up the subsequent request in Step 2.

A successful request returns an empty response body and a response code of "204 No Content".

STEP 2

Action: POST
Endpoint: /users/auth/verifyemail/{email_verification_token}

To verify the email address, send a POST request to the /users/auth/verifyemail/{email_verification_token} endpoint. Include the email_verification_token as a path parameter.

A successful email verification returns an empty response body and a response code of "204 No Content".

URL Path Parameters

Name Type Required? Description Allowable Values
email_verification_token string Yes Email verification token. Generated from POST /users/auth/verifyemail

Retrieve User SSN

Action: GET
Endpoint: /users/{token}/ssn

To retrieve the social security number (SSN) for a user, issue a GET request to the /users/{token}/ssn endpoint. Include the token path parameter to specify the user whose ssn you wish to return. You can indicate whether to return the full number or the last four digits only.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the user whose SSN you want to retrieve. Existing user token.

Issue a GET to /users to retrieve user tokens.

Query Parameters

Name Type Required? Description Allowable Values
full_ssn boolean Yes To return the full social security number, set to true.
To return only the last 4 digits, set to false.
true | false

Default: false

Sample Response Body

{
"ssn": "5555"
}


Change Password

Action: POST
Endpoint: /users/auth/changepassword

To change a user password, send a POST request to the /users/auth/changepassword endpoint and include the current_password and new_password in JSON format in the body of the request. This endpoint operates in the context of a currently logged-in user.

A successful change of password returns an empty response body and a response code of "204 No Content".

Body Field Details

Name Type Required? Description Allowable Values
new_password string Yes The new password. 40 char max
current_password string Yes The current password. 40 char max

Sample Request Body

{
"new_password": "my_new_password",
"current_password": "my_old_password"
}


Reset User Password

Resetting a user's password is a two-step process. First you request a password reset token, and then you use that token in a subsequent request to update the password.

Step 1

Action: POST
Endpoint: /users/auth/resetpassword

To request a reset password token, send a POST request to the /users/auth/resetpassword endpoint and include the user's email address in JSON format in the body of the request. This request generates and sends an email message containing the user_token and password_reset_token to the user's email address. (The email message must be customized with a link that passes the user_token and password_reset_token to a web page where a subsequent request updates the password.) You set up the subsequent request in Step 2.

A successful request returns an empty response body and a response code of "204 No Content".

Body Field Details

Name Type Required? Description Allowable Values
email string Yes Email address of the user. 255 char max

Sample Request Body

{
"email": "my_email@gmail.com"
}

Step 2

Action: POST
Endpoint: /users/auth/resetpassword/{password_reset_token}

To reset the password, send a POST request to the /users/auth/resetpassword/{password_reset_token} endpoint. Include the user_token and new_password in JSON format in the body of the request. Include the password_reset_token as a path parameter.

A successful reset of password returns an empty response body and a response code of "204 No Content".

URL Path Parameters

Name Type Required? Description Allowable Values
password_reset_token string Yes Password reset token. Generated from POST /users/auth/resetpassword

Body Field Details

Name Type Required? Description Allowable Values
user_token string Yes The token identifying the user whose password will be reset. 255 char max
new_password string Yes New password. 255 char max

Sample Request Body

{
"user_token": "my_user",
"new_password": "newPassword123@"
}


Log out User

Action: POST
Endpoint: /users/auth/logout

To log out a user, send a POST request to the /users/auth/logout endpoint.

A successful logout returns an empty response body and a response code of "204 No Content".


Log in User

Action: POST
Endpoint: /users/auth/login

To log in a user and return a user access token, send a POST request to the /users/auth/login endpoint and include the user details in JSON format in the body of the request.

Note: If you want to check a user's credentials without logging out the user, utilize the /users/auth/onetime endpoint.

Body Field Details

Name Type Required? Description Allowable Values
email string Yes The user's email address. 255 char max
password string Yes The user's Marqeta password. 255 char max
user_token string Yes Identifies the user to log in. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Request Body

{
"email": "bigbird@gmail.com",
"password": "My_passw0rd",
"user_token": "bigbird_token"
}

Sample Response Body

{
"access_token" : {
"token" : "e12b1f64-1444-4aa3-83d9-347800c68e94",
"expires" : "2016-04-01T21:02:04Z",
"one_time" : false
},
"user" : {
"token" : "bigbird_token",
"active" : true,
"email" : "bigbird@gmail.com",
"uses_parent_account" : false,
"password" : "___________",
"corporate_card_holder" : false,
"created_time" : "2016-04-01T17:52:39Z",
"last_modified_time" : "2016-04-01T17:52:39Z"
}
}


Return Single-Use Token

Action: POST
Endpoint: /users/auth/onetime

This endpoint returns a single-use access token. This type of token authorizes a single request to access API endpoints and data associated with a particular user. A single-use access token differs from a user access token (as returned by POST /users/auth/login) only in the number of times it can be used.

To return a single-use access token, send a POST request to the /users/auth/onetime endpoint. Provide one of these sets of input data:

Case #1 – Application token and user access token
Case #2 – Application token, master access token, and user token
Case #3 – Application token, user's Marqeta password, and user's email address

In each case, provide the application token as the HTTP Basic Authenication username in the request header's Authorization field. When applicable, provide the user access token or master access token as the HTTP Basic Authenication password. When applicable, provide the user token or user's Marqeta password and email address in JSON format in the request body.

Before instantiating an embedded Marqeta widget, call this endpoint to obtain the single-use access token you will require as input (cases #1 and 2).

This endpoint is also useful when you want to check a user's credentials before performing a sensitive operation without having to log out the user (case #3). Note that calling this endpoint and returning a single-use access token does not invalidate the user's current user access token.

Body Field Details

Name Type Required? Description Allowable Values
user_token string Required when Basic Authentication password is set to a master access token (case #2). Identifies the user whose data will be accessed. Existing user token.

Issue a GET to /users to retrieve user tokens.
email string Required when Basic Authentication password is not specified (case #3). User's email address. 255 char max
password string Required when basic Basic Authentication is not specified (case #3). User's Marqeta password. 255 char max

Sample Request Body

Case #1 – Authorization: Basic my_application_token:my_user_access_token

{
}

Case #2 – Authorization: Basic my_application_token:my_master_access_token

{
"user_token": "my_user_token"
}

Case #3 – Authorization: Basic my_application_token

{
"email": "bruninho@gmail.com",
"password": "Querty123$"
}

Sample Response Body

{
"token" : "697e0bde-ea52-44bd-8150-0e0f83e9625d",
"expires" : "2015-06-13T01:06:14Z",
"one_time" : true
}