/
25 minute read
March 24, 2022

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:
1000

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
Copied

Is this helpful?

Yes
No

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:
1000

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
Copied

Is this helpful?

Yes
No

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:
1000

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
Copied

Is this helpful?

Yes
No

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:
1000

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
Copied

Is this helpful?

Yes
No

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:
1000

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
Copied

Is this helpful?

Yes
No

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:
1000

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

Join our developer newsletter