Skip to main content
Note
This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.
The Marqeta platform’s deposit account feature enables you to manage the creation, maintenance, and lifecycle of a deposit account. You can also look up a user by their associated plain text deposit account number or list all the deposit accounts associated with a specified user.

​
Create deposit account

Action: POST
Endpoint: /depositaccounts Creates a new deposit account for a user or business. Before you can create a new deposit account, the associated user must successfully pass KYC. (You can also set the manual_override field of POST /kyc to true in the event that you performed the verification through another mechanism, such as with an alternative KYC provider or directly with the account holder). For more information, see About KYC Verification. An active, issued card—at either the parent or the child level—is required before creating an account with the type field set to DEPOSIT_ACCOUNT. In contrast, you can create an account without an issued card when the type field is set to CHECKING; however, you must issue and activate a card before the checking account can be used to transact.
Note
Each cardholder is limited to five deposit accounts, including any accounts in the ACTIVE or SUSPENDED state. Contact your Marqeta representative if you need to raise this value.

​
Request body

FieldsDescription
token

string

Optional		Unique identifier of the deposit account.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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
user_token OR business_token

string

Required		User or business for which to create the deposit account. Pass either a user_token or business_token. Performs a non-case-sensitive match.

Allowable Values:

Existing user or business token.

NOTE: If you pass a business token here, you can only create a DEPOSIT_ACCOUNT, and not a CHECKING account. See the type field below for details.
type

string

Optional		Type of deposit account being created.

Allowable Values:

- DEPOSIT_ACCOUNT: An ACH account that supports automatic direct deposit transactions. Reserved for prepaid card programs.
- CHECKING: A consumer Demand Deposit Account (DDA) offering features typically associated with checking accounts.

Default value:
DEPOSIT_ACCOUNT

NOTE: This field is not returned in the response.
customer_due_diligence

array of objects

Conditionally required		Array containing Customer Due Diligence (CDD) data associated with the account holder specified by user_token. Required when the type field is set to CHECKING. For details, see About Customer Due Diligence.

Allowable Values:

Array of objects with valid CDD question/answer pairs, as described in CDD Data Object.

​
Response body

FieldsDescription
account_number

string

Returned		Account number assigned to the deposit account.

Allowable Values:

13-17 char max, depending on the program.
routing_number

string

Returned		Routing number assigned to the deposit account.

Allowable Values:

9 char max
token

string

Returned		Unique identifier of the deposit account.

Allowable Values:

36 char max
user_token OR business_token

string

Returned		User or business to whom the deposit account belongs.

Allowable Values:

36 char max
state

string

Returned		Status of the deposit account.

Allowable Values:

ACTIVE
type

string

Returned		Type of deposit account created.

Allowable Values:

DEPOSIT_ACCOUNT, CHECKING
created_time

string

Returned		Date and time when the deposit account was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
last_modified_time

string

Returned		Date and time when the deposit account was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample request body

JSON
{
  "user_token": "bd6772dc-3ab9-4014-8ef1-fa0843bf5d0d",
  "type": "CHECKING",
  "customer_due_diligence": [
    {
      "question": "dda_002_cdd_01_expmondep",
      "answer": "2"
    },
    {
      "question": "dda_002_cdd_02_naics",
      "answer": "6241"
    }
  ]
}

​
Sample response body

JSON
{
  "account_number": "2401870493365",
  "routing_number": "041285663",
  "token": "b28fc1c9-d0b7-452c-9e88-4d17099114c3",
  "user_token": "bd6772dc-3ab9-4014-8ef1-fa0843bf5d0d",
  "state": "ACTIVE",
  "type": "CHECKING",
  "created_time": "2020-12-08T00:12:59Z",
  "last_modified_time": "2020-12-08T00:12:59Z"
}

​
Retrieve deposit account

Action: GET
Endpoint: /depositaccounts/{token} Retrieves a specified deposit account. Include the token path parameter to indicate the deposit account to retrieve.

​
URL path parameters

FieldsDescription
token

string

Required		Token of the deposit account.

Allowable Values:

Existing deposit account token.

​
Response body

FieldsDescription
account_number

string

Returned		Account number assigned to the deposit account.

Allowable Values:

13-17 char max, depending on the program.
routing_number

string

Returned		Routing number assigned to the deposit account.

Allowable Values:

9 char max
token

string

Returned		Unique identifier of the deposit account.

Allowable Values:

36 char max
user_token OR business_token

string

Returned		User or business associated with the deposit account.

Allowable Values:

36 char max
state

string

Returned		Status of the deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED
type

string

Returned		Type of deposit account.

Allowable Values:

- DEPOSIT_ACCOUNT: An ACH account that supports automatic direct deposit transactions. Reserved for prepaid card programs.
- CHECKING: A consumer Demand Deposit Account (DDA) offering features typically associated with checking accounts.
created_time

string

Returned		Date and time when the deposit account was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
last_modified_time

string

Returned		Date and time when the deposit account was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample response body

JSON
{
  "account_number": "2401534763971",
  "routing_number": "041815663",
  "token": "a11eecf9-0bde-4e9c-ac13-723f12a09cb3",
  "user_token": "bd5472cc-3cd9-4004-8ef1-fa0743bf5d0d",
  "state": "ACTIVE",
  "type": "DEPOSIT_ACCOUNT",
  "created_time": "2020-11-17T23:46:19Z",
  "last_modified_time": "2020-11-17T23:46:19Z"
}

​
List deposit accounts

Action: GET
Endpoint: /depositaccounts/user/{token} Retrieves a list of all the deposit accounts associated with the specified account holder. This endpoint supports pagination and field filtering.

​
URL path parameters

FieldsDescription
token

string

Required		Token identifying the user or business whose deposit accounts you want to retrieve.

Allowable Values:

36 char max

​
Response body

FieldsDescription
account_number

string

Returned		Account number assigned to the deposit account.

Allowable Values:

13-17 char max, depending on the program.
routing_number

string

Returned		Routing number assigned to the deposit account.

Allowable Values:

9 char max
token

string

Returned		Unique identifier of the deposit account.

Allowable Values:

36 char max
user_token OR business_token

string

Returned		Unique identifier of the user or business associated with the deposit account.

Allowable Values:

36 char max
state

string

Returned		Status of the deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED
type

string

Returned		Type of deposit account.

Allowable Values:

DEPOSIT_ACCOUNT, CHECKING
created_time

string

Returned		Date and time when the deposit account was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
last_modified_time

string

Returned		Date and time when the deposit account was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample response body

JSON
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "account_number": "2403570493575",
      "routing_number": "041215623",
      "token": "c39fc2d0-d0b7-452c-9e88-4d17099114c3",
      "user_token": "bd6773cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "state": "ACTIVE",
      "type": "DEPOSIT_ACCOUNT",
      "created_time": "2020-10-08T00:12:59Z",
      "last_modified_time": "2020-11-08T00:12:59Z"
    },
    {
      "account_number": "2401568763971",
      "routing_number": "041215663",
      "token": "a11eecf9-0bde-4e9c-ac13-723f12a09cb3",
      "user_token": "bd6773cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "state": "ACTIVE",
      "type": "DEPOSIT_ACCOUNT",
      "created_time": "2020-09-17T23:46:19Z",
      "last_modified_time": "2020-09-17T23:46:19Z"
    }
  ]
}

​
Look up user by deposit account number

Action: POST
Endpoint: /depositaccounts/account/user Looks up a user by their associated plain text deposit account number.

​
Request body

FieldsDescription
account_number

string

Required		Deposit account number of the user you are looking up.

Allowable Values:

Existing 13-17 digit deposit account number.

​
Sample response body

JSON
{
  "token": "03cf3266-1e6c-43aa-833e-447d34e5ce26",
  "active": true,
  "gender": "M",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john32@gmail.com",
  "address1": "6201 Doyle Street",
  "city": "Emeryville",
  "state": "CA",
  "postal_code": "94607",
  "country": "USA",
  "phone": "5105551212",
  "uses_parent_account": false,
  "password": "___________",
  "created_time": "2020-03-16T20:26:28Z",
  "last_modified_time": "2020-03-16T20:26:29Z",
  "metadata": {},
  "account_holder_group_token": "DEFAULT_AHG",
  "status": "ACTIVE",
  "identifications": [
    {
      "type": "DRIVERS_LICENSE",
      "value": "12345"
    }
  ],
  "birth_date": "1986-04-01"
}

​
Create deposit account transition

Action: POST
Endpoint: /depositaccounts/transitions Creates a transition record to activate, suspend, or deactivate a deposit account.
Warning
Accounts in the TERMINATED state cannot be transitioned to another state. TERMINATED is a final state.

​
Request body

FieldsDescription
token

string

Optional		Unique identifier of the account transitions record.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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
account_token

string

Required		Unique identifier of the deposit account.

Allowable Values:

36 char max
state

string

Required		Status of the account transitions record.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED
channel

string

Required		Channel associated with the account transitions record.

Most account transitions use the API channel, and the SYSTEM channel is typically reserved for use by the Marqeta platform. For a detailed description of each of these values, see the channel field on the Card Transitions page.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM
reason

string

Required		Explanation of why the account transitions record was created.

Allowable Values:

255 char max

​
Response body

FieldsDescription
token

string

Returned		Unique identifier of the account transitions record.

Allowable Values:

36 char max
user_token OR business_token

string

Returned		Unique identifier of the user or business associated with the account transitions record.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the deposit account.

Allowable Values:

36 char max
state

string

Returned		Status of the deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED
channel

string

Returned		Channel associated with the account transitions record.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM
reason

string

Returned		Explanation of why the account transitions record was created.

Allowable Values:

255 char max
created_time

string

Returned		Date and time when the deposit transition was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample request body

JSON
{
  "channel": "API",
  "account_token": "bf344baf-054b-420a-852f-cbedb3413b37",
  "reason": "Suspicious activity detected",
  "state": "SUSPENDED"
}

​
Sample response body

JSON
{
  "token": "a4e1237b-c335-4e39-acb7-bf942b2751fe",
  "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
  "account_token": "bf344baf-054b-420a-852f-cbedb3413b37",
  "state": "SUSPENDED",
  "channel": "API",
  "created_time": "2020-11-15T20:27:50Z"
}

​
Retrieve deposit account transition

Action: GET
Endpoint: /depositaccounts/transitions/{token} Retrieves the specified deposit account transition.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the account transitions record.

Allowable Values:

36 char max

​
Response body

FieldsDescription
token

string

Returned		Unique identifier of the account transitions record.

Allowable Values:

36 char max
user_token OR business_token

string

Returned		Unique identifier of the user or business associated with the account transitions record.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the deposit account.

Allowable Values:

36 char max
state

string

Returned		Status of the account transitions record.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED
channel

string

Returned		Channel associated with the account transitions record.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM
reason

string

Returned		Explanation of why the account transitions record was created.

Allowable Values:

255 char max
created_time

string

Returned		Date and time when the account transitions record was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample response body

JSON
{
  "token": "181033a3-3bd7-47b2-9f07-20fbfa053987",
  "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
  "account_token": "bf377baf-054b-420a-852f-cbedb3413b37",
  "state": "SUSPENDED",
  "channel": "API",
  "reason": "Transitioned DDA",
  "created_time": "2020-10-18T19:48:35Z"
}

​
Retrieve all deposit account transitions

Action: GET
Endpoint: /depositaccounts/{user_token}/transitions Retrieves a list of all transitions of all accounts that are associated with the specified account holder. This endpoint supports pagination and field filtering.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user whose account transitions you want to retrieve.

Allowable Values:

36 char max

​
Response body

FieldsDescription
token

string

Returned		Unique identifier of the account transitions record.

Allowable Values:

36 char max
user_token

string

Returned		Unique identifier of the user whose account transitions you want to retrieve.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the deposit account.

Allowable Values:

36 char max
state

string

Returned		Status to which the deposit account was transitioned.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED
channel

string

Returned		Channel associated with the account transitions record.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM
reason

string

Returned		Explanation of why the account transitions record was created.

Allowable Values:

255 char max
created_time

string

Returned		Date and time when the account transitions record was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample response body

JSON
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "2de542ce-b168-4640-a17d-4701439b875d",
      "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "account_token": "bf377baf-054b-420a-852f-cbedb3413b37",
      "state": "ACTIVE",
      "channel": "IVR",
      "created_time": "2020-10-15T20:32:45Z"
    },
    {
      "token": "8435b916-6fc9-4d60-b234-ae68e7addc4b",
      "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "account_token": "b28fc1c9-d0b7-452c-9e88-4d17099114c3",
      "state": "UNACTIVATED",
      "channel": "SYSTEM",
      "reason": "CREATED DDA",
      "created_time": "2020-10-08T00:12:59Z"
    }
  ]
}

​
Retrieve customer due diligence information

Action: GET
Endpoint: /depositaccounts/{token}/cdd Retrieves a list of the customer due diligence (CDD) questions and answers associated with the specified account holder and DDA. For more information on CDD, see About Customer Due Diligence.

​
URL path parameters

FieldsDescription
token

string

Required		Token identifying the DDA whose CDD questions and answers you want to retrieve.

Allowable Values:

36 char max

​
Response body

FieldsDescription
customer_due_diligence_list

array of objects

Returned		An array containing a customer_due_diligence object for each due diligence question/answer pair related to the specified account token.

Each customer_due_diligence object contains the fields described in the customer_due_diligence data object.

Allowable Values:

An array of valid customer_due_diligence data objects.

​
The customer_due_diligence data object

FieldsDescription
question

string

Returned		Unique identifier of the CDD question whose answer is stored in the customer_due_diligence object. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value, for example dda_002_cdd_01_expmondep.
answer

string

Returned		Unique identifier of the answer supplied by the account holder in response to the CDD question specified by question.

Allowable Values:

A valid answer ID from the Expected monthly deposits table or the Employment classification table.
type

string

Returned		Type of account whose CDD data is contained in this object.

Allowable Values:

CHECKING
bank

string

Returned		Name of the financial institution requesting these CDD questions and answers. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value
token

string

Returned		Unique identifier of this CDD response.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the associated deposit account.

Allowable Values:

36 char max

​
Sample response body

JSON
{
  "customer_due_diligence_list": [
    {
      "question": "dda_002_cdd_01_expmondep",
      "answer": "2",
      "type": "CHECKING",
      "bank": "BankName",
      "token": "e691a7ae-f9ae-4184-a2e9-cf6bbc963e4a",
      "account_token": "1bb17a10-8d12-442b-95c0-1babd9a78f92"
    },
    {
      "question": "dda_002_cdd_02_naics",
      "answer": "6241",
      "type": "CHECKING",
      "bank": "BankName",
      "token": "e509fb2f-f55f-48de-a226-5456c6c78dd4",
      "account_token": "1bb17a10-8d12-442b-95c0-1babd9a78f92"
    }
  ]
}

​
Update customer due diligence information

Action: PUT
Endpoint: /depositaccounts/{token}/cdd/{cddtoken} Updates the answer to a customer due diligence (CDD) question associated with the specified account holder and DDA.
Note
Each CDD question must be updated separately; you cannot update multiple questions in a single request.

​
URL path parameters

FieldsDescription
token

string

Required		Account token identifying the DDA whose CDD question you want to update.

Allowable Values:

Existing account token.
cddtoken

string

Required		Token identifying the CDD question whose answer you want to update.

Allowable Values:

Existing CDD token.

​
Request body

FieldsDescription
answer

string

Required		The updated answer value to the CDD question specified by cddtoken.

Allowable Values:

A valid answer ID from the Expected monthly deposits table or the Employment classification table.

​
Response body

FieldsDescription
question

string

Returned		Unique identifier of the CDD question whose updated answer is specified by answer. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value, for example dda_002_cdd_01_expmondep.
answer

string

Returned		Unique identifier of the updated answer supplied by the account holder in response to the CDD question specified by question.

Allowable Values:

A valid answer ID from the Expected monthly deposits table or the Employment classification table.
type

string

Returned		Type of account whose CDD data is being updated.

Allowable Values:

CHECKING
bank

string

Returned		Name of the financial institution requesting these CDD questions and answers. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value
token

string

Returned		Unique identifier of this CDD response.

Allowable Values:

36 char max
account_token

string

Returned		Unique identifier of the associated deposit account.

Allowable Values:

36 char max

​
Sample request body

JSON
{
  "answer": "4"
}

​
Sample response body

JSON
{
  "question": "dda_002_cdd_01_expmondep",
  "answer": "4",
  "type": "CHECKING",
  "bank": "pathward",
  "token": "e691a7ae-f9ae-4184-a2e9-cf6bbc963e4a",
  "account_token": "1bb17a10-8d12-442b-95c0-1babd9a78f92"
}

Related topics

Direct DepositSimulations 2.0 — Direct DepositsIntra-Account TransfersAbout Customer Due Diligence