Account Holder Groups

The account holder group is a Marqeta platform resource that allows you to configure multiple account holders (user and/or business resources) as a group. It allows certain settings to be selectively applied, depending on whether or not an account holder has passed verification (KYC). You associate an account holder with an account holder group using the optional account_holder_group_token field in the user or business resource. Any account holder that you do not explicitly associate with a group is automatically associated with the program’s default account holder group. The default group’s name is “Default account holder group”, its token is DEFAULT_AHG, and its configuration uses the default configuration values.

Create account holder group

Action: POST
Endpoint: /accountholdergroups Use this endpoint to create an account holder group.

Request body

Fields	Description
config object Optional	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Optional	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Optional	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Optional	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Optional	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Optional	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Optional	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Optional	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Optional	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Optional	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Optional	Descriptive name for the account holder group. Allowable Values: 1–40 chars
token string Optional	Unique identifier of the account holder group. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "token": "account_holder_group_01",
  "name": "Account Holder Group 01"
}

Response body

Fields	Description
config object Conditionally returned	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Conditionally returned	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Conditionally returned	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Conditionally returned	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Conditionally returned	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Conditionally returned	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Conditionally returned	Descriptive name for the account holder group. This field is returned if it exists in the resource. Allowable Values: Existing account holder group name
token string Conditionally returned	Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token

Sample response body

JSON

{
  "token": "account_holder_group_01",
  "name": "Account Holder Group 01",
  "config": {
    "kyc_required": "ALWAYS",
    "is_reloadable": true,
    "pre_kyc_controls": {
      "cash_access_enabled": false,
      "international_enabled": false,
      "balance_max": 1000,
      "enable_non_program_loads": false,
      "is_reloadable_pre_kyc": false
    }
  }
}

List account holder groups

Action: GET
Endpoint: /accountholdergroups Use this endpoint to return an array of all account holder groups.

URL query parameters

Fields	Description
count integer Optional	Number of resources to retrieve. Allowable Values: 1-10
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer
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

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of account holder group objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more account holder group objects
data[].config object Conditionally returned	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
data[].config.is_reloadable boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
data[].config.kyc_required string Conditionally returned	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
data[].config.pre_kyc_controls object Conditionally returned	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
data[].config.pre_kyc_controls.balance_max decimal Conditionally returned	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
data[].config.pre_kyc_controls.cash_access_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
data[].config.pre_kyc_controls.enable_non_program_loads boolean Conditionally returned	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
data[].config.pre_kyc_controls.international_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
data[].config.pre_kyc_controls.is_reloadable_pre_kyc boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
data[].config.real_time_fee_group_token string Conditionally returned	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
data[].name string Conditionally returned	Descriptive name for the account holder group. This field is returned if it exists in the resource. Allowable Values: Existing account holder group name
data[].token string Conditionally returned	Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group 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

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "account_holder_group_01",
      "name": "Account Holder Group 01",
      "config": {
        "kyc_required": "ALWAYS",
        "is_reloadable": true,
        "pre_kyc_controls": {
          "cash_access_enabled": false,
          "international_enabled": false,
          "balance_max": 500,
          "enable_non_program_loads": false,
          "is_reloadable_pre_kyc": false
        }
      }
    }
  ]
}

Retrieve account holder group

Action: GET
Endpoint: /accountholdergroups/{token} Use this endpoint to retrieve a specific account holder group.

URL path parameters

Fields	Description
token string Required	Unique identifier of the account holder group. Allowable Values: Existing account holder group token

Response body

Fields	Description
config object Conditionally returned	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Conditionally returned	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Conditionally returned	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Conditionally returned	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Conditionally returned	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Conditionally returned	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Conditionally returned	Descriptive name for the account holder group. This field is returned if it exists in the resource. Allowable Values: Existing account holder group name
token string Conditionally returned	Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token

Sample response body

JSON

{
  "token": "account_holder_group_01",
  "name": "Account Holder Group 01",
  "config": {
    "kyc_required": "ALWAYS",
    "is_reloadable": true,
    "pre_kyc_controls": {
      "cash_access_enabled": false,
      "international_enabled": false,
      "balance_max": 1000,
      "enable_non_program_loads": false,
      "is_reloadable_pre_kyc": false
    }
  }
}

Update account holder group

Action: PUT
Endpoint: /accountholdergroups/{token} Use this endpoint to update a specific account holder group. Only values of parameters in the request are modified; all others are left unchanged. To update a specific account holder group, send a PUT request to the /accountholdergroups/{token} endpoint. Use the token path parameter to specify the account holder group to update. Include the account holder group details to update in JSON format in the body of the request.

Note
While you can update account holder groups that you create, the default group is restricted and requires special permissions to update.

URL path parameters

Fields	Description
token string Required	Unique identifier of the account holder group. Allowable Values: Existing account holder group token

Request body

Fields	Description
config object Optional	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Optional	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Optional	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Optional	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Optional	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Optional	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Optional	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Optional	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Optional	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Optional	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Optional	Descriptive name for the account holder group. Allowable Values: 1–40 chars

Sample request body

JSON

{
  "config": {
    "pre_kyc_controls": {
      "balance_max": 500
    }
  }
}

Response body

Fields	Description
config object Conditionally returned	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Conditionally returned	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Conditionally returned	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Conditionally returned	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Conditionally returned	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Conditionally returned	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Conditionally returned	Descriptive name for the account holder group. This field is returned if it exists in the resource. Allowable Values: Existing account holder group name
token string Conditionally returned	Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

Account Holder Groups

Create account holder group

Request body

Sample request body

Response body

Sample response body

List account holder groups

URL query parameters

Response body

Sample response body

Retrieve account holder group

URL path parameters

Response body

Sample response body

Update account holder group

URL path parameters

Request body

Sample request body

Response body

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​Create account holder group

​Request body

​Sample request body

​Response body

​Sample response body

​List account holder groups

​URL query parameters

​Response body

​Sample response body

​Retrieve account holder group

​URL path parameters

​Response body

​Sample response body

​Update account holder group

​URL path parameters

​Request body

​Sample request body

​Response body

Create account holder group

Request body

Sample request body

Response body

Sample response body

List account holder groups

URL query parameters

Response body

Sample response body

Retrieve account holder group

URL path parameters

Response body

Sample response body

Update account holder group

URL path parameters

Request body

Sample request body

Response body