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
Copy section link
Action: POST
Endpoint: /accountholdergroups
Use this endpoint to create an account holder group.
Request body
Copy section link
| Fields | Description |
|---|---|
config
object
|
Contains configuration fields for the account holder group. Allowable Values:
|
config.is_reloadable
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.kyc_required
string
|
If set to Allowable Values:
Default value: |
config.pre_kyc_controls
object
|
Contains configuration fields for a number of controls. NOTE: These controls are in effect only if Allowable Values:
|
config.pre_kyc_controls.balance_max
decimal
|
Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: |
config.pre_kyc_controls.cash_access_enabled
boolean
|
If set to NOTE: If a card product’s Allowable Values:
Default value: |
config.pre_kyc_controls.enable_non_program_loads
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.pre_kyc_controls.international_enabled
boolean
|
If set to 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:
Default value: |
config.pre_kyc_controls.is_reloadable_pre_kyc
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.real_time_fee_group_token
string
|
Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
name
string
|
Descriptive name for the account holder group. Allowable Values: 1–40 chars |
token
string
|
Unique identifier of the account holder group. Allowable Values: 1–36 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
config
object
|
Contains configuration fields for the account holder group. Allowable Values:
|
config.is_reloadable
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.kyc_required
string
|
If set to Allowable Values:
Default value: |
config.pre_kyc_controls
object
|
Contains configuration fields for a number of controls. NOTE: These controls are in effect only if Allowable Values:
|
config.pre_kyc_controls.balance_max
decimal
|
Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: |
config.pre_kyc_controls.cash_access_enabled
boolean
|
If set to NOTE: If a card product’s Allowable Values:
Default value: |
config.pre_kyc_controls.enable_non_program_loads
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.pre_kyc_controls.international_enabled
boolean
|
If set to 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:
Default value: |
config.pre_kyc_controls.is_reloadable_pre_kyc
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.real_time_fee_group_token
string
|
Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
name
string
|
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
|
Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token |
List account holder groups
Copy section link
Action: GET
Endpoint: /accountholdergroups
Use this endpoint to return an array of all account holder groups.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources to retrieve. Allowable Values: 1-10 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
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
|
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
|
Contains configuration fields for the account holder group. Allowable Values:
|
data[].config.is_reloadable
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
data[].config.kyc_required
string
|
If set to Allowable Values:
Default value: |
data[].config.pre_kyc_controls
object
|
Contains configuration fields for a number of controls. NOTE: These controls are in effect only if Allowable Values:
|
data[].config.pre_kyc_controls.balance_max
decimal
|
Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: |
data[].config.pre_kyc_controls.cash_access_enabled
boolean
|
If set to NOTE: If a card product’s Allowable Values:
Default value: |
data[].config.pre_kyc_controls.enable_non_program_loads
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
data[].config.pre_kyc_controls.international_enabled
boolean
|
If set to 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:
Default value: |
data[].config.pre_kyc_controls.is_reloadable_pre_kyc
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
data[].config.real_time_fee_group_token
string
|
Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
data[].name
string
|
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
|
Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token |
end_index
integer
|
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
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
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 |
Retrieve account holder group
Copy section link
Action: GET
Endpoint: /accountholdergroups/{token}
Use this endpoint to retrieve a specific account holder group.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the account holder group. Allowable Values: Existing account holder group token |
Response body
Copy section link
| Fields | Description |
|---|---|
config
object
|
Contains configuration fields for the account holder group. Allowable Values:
|
config.is_reloadable
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.kyc_required
string
|
If set to Allowable Values:
Default value: |
config.pre_kyc_controls
object
|
Contains configuration fields for a number of controls. NOTE: These controls are in effect only if Allowable Values:
|
config.pre_kyc_controls.balance_max
decimal
|
Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: |
config.pre_kyc_controls.cash_access_enabled
boolean
|
If set to NOTE: If a card product’s Allowable Values:
Default value: |
config.pre_kyc_controls.enable_non_program_loads
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.pre_kyc_controls.international_enabled
boolean
|
If set to 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:
Default value: |
config.pre_kyc_controls.is_reloadable_pre_kyc
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.real_time_fee_group_token
string
|
Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
name
string
|
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
|
Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token |
Update account holder group
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the account holder group. Allowable Values: Existing account holder group token |
Request body
Copy section link
| Fields | Description |
|---|---|
config
object
|
Contains configuration fields for the account holder group. Allowable Values:
|
config.is_reloadable
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.kyc_required
string
|
If set to Allowable Values:
Default value: |
config.pre_kyc_controls
object
|
Contains configuration fields for a number of controls. NOTE: These controls are in effect only if Allowable Values:
|
config.pre_kyc_controls.balance_max
decimal
|
Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: |
config.pre_kyc_controls.cash_access_enabled
boolean
|
If set to NOTE: If a card product’s Allowable Values:
Default value: |
config.pre_kyc_controls.enable_non_program_loads
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.pre_kyc_controls.international_enabled
boolean
|
If set to 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:
Default value: |
config.pre_kyc_controls.is_reloadable_pre_kyc
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.real_time_fee_group_token
string
|
Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
name
string
|
Descriptive name for the account holder group. Allowable Values: 1–40 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
config
object
|
Contains configuration fields for the account holder group. Allowable Values:
|
config.is_reloadable
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.kyc_required
string
|
If set to Allowable Values:
Default value: |
config.pre_kyc_controls
object
|
Contains configuration fields for a number of controls. NOTE: These controls are in effect only if Allowable Values:
|
config.pre_kyc_controls.balance_max
decimal
|
Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: |
config.pre_kyc_controls.cash_access_enabled
boolean
|
If set to NOTE: If a card product’s Allowable Values:
Default value: |
config.pre_kyc_controls.enable_non_program_loads
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.pre_kyc_controls.international_enabled
boolean
|
If set to 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:
Default value: |
config.pre_kyc_controls.is_reloadable_pre_kyc
boolean
|
If set to This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values:
Default value: |
config.real_time_fee_group_token
string
|
Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
name
string
|
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
|
Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token |