/
30 minute read
March 24, 2022

Account Holder Groups

Hidden

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:

A valid config object

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

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 CONDITIONAL and the account holder has not yet passed KYC.

Allowable Values:

A valid pre_kyc_controls object

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 false, 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

Send a GET request to /realtimefeegroups to retrieve real-time fee group tokens.

name

string
Optional

Descriptive name for the account holder group.

Allowable Values:

1–40 chars

token

string
Optional

The unique identifier of the account holder group.

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:

1–36 chars

Response body
Fields Description

config

object
Conditionally returned

Contains configuration fields for the account holder group. This object is returned when present in the resource.

Allowable Values:

A valid config object

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.

This field is returned when present in the resource.

Allowable Values:

true, 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.

This field is returned when present in the resource.

Allowable Values:

ALWAYS, CONDITIONAL, NEVER

config.pre_kyc_controls

object
Conditionally returned

Contains configuration fields for a number of controls. This object is returned when present in the resource.

NOTE: These controls are in effect only if kyc_required is CONDITIONAL and the account holder has not yet passed KYC.

Allowable Values:

A valid pre_kyc_controls object

config.pre_kyc_controls.balance_max

decimal
Conditionally returned

Specifies the maximum ledger balance allowed for members of the account holder group. This field is returned when present in the resource.

Allowable Values:

0.01 min

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. This field is returned when present in the resource.

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

config.pre_kyc_controls.enable_non_program_loads

boolean
Conditionally returned

If set to false, 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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

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

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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

Allowable Values:

36 char max

name

string
Conditionally returned

Descriptive name for the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group name

token

string
Conditionally returned

The unique identifier of the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group token

Sample request body
JSON
Copied

Is this helpful?

Yes
No
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

The number of resources to retrieve. Count can be between 1 - 10 items.

Allowable Values:

1-10

start_index

integer
Optional

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

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of objects in a returned resource. This object is returned when present in the resource.

Allowable Values:

A valid data array

data[].config

object
Conditionally returned

Contains configuration fields for the account holder group. This object is returned when present in the resource.

Allowable Values:

A valid config object

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.

This field is returned when present in the resource.

Allowable Values:

true, 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.

This field is returned when present in the resource.

Allowable Values:

ALWAYS, CONDITIONAL, NEVER

data[].config.pre_kyc_controls

object
Conditionally returned

Contains configuration fields for a number of controls. This object is returned when present in the resource.

NOTE: These controls are in effect only if kyc_required is CONDITIONAL and the account holder has not yet passed KYC.

Allowable Values:

A valid pre_kyc_controls object

data[].config.pre_kyc_controls.balance_max

decimal
Conditionally returned

Specifies the maximum ledger balance allowed for members of the account holder group. This field is returned when present in the resource.

Allowable Values:

0.01 min

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. This field is returned when present in the resource.

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

data[].config.pre_kyc_controls.enable_non_program_loads

boolean
Conditionally returned

If set to false, 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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

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

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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

Allowable Values:

36 char max

data[].name

string
Conditionally returned

Descriptive name for the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group name

data[].token

string
Conditionally returned

The unique identifier of the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group token

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array. This field is returned when present in the query.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. This field is returned when present in the resource.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the 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

The unique identifier of the account holder group.

Allowable Values:

Existing account holder group token.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

Response body
Fields Description

config

object
Conditionally returned

Contains configuration fields for the account holder group.

Allowable Values:

A valid config object

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.

This field is returned when present in the resource.

Allowable Values:

true, 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.

This field is returned when present in the resource.

Allowable Values:

ALWAYS, CONDITIONAL, NEVER

config.pre_kyc_controls

object
Conditionally returned

Contains configuration fields for a number of controls. This object is returned when present in the resource.

NOTE: These controls are in effect only if kyc_required is CONDITIONAL and the account holder has not yet passed KYC.

Allowable Values:

A valid pre_kyc_controls object

config.pre_kyc_controls.balance_max

decimal
Conditionally returned

Specifies the maximum ledger balance allowed for members of the account holder group. This field is returned when present in the resource.

Allowable Values:

0.01 min

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. This field is returned when present in the resource.

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

config.pre_kyc_controls.enable_non_program_loads

boolean
Conditionally returned

If set to false, 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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

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

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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

Allowable Values:

36 char max

name

string
Conditionally returned

Descriptive name for the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group name

token

string
Conditionally returned

The unique identifier of the account holder group. This field is returned when present in the resource.

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

The unique identifier of the account holder group.

Allowable Values:

Existing account holder group token.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

Request body
Fields Description

config

object
Optional

Contains configuration fields for the account holder group.

Allowable Values:

A valid config object

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

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 CONDITIONAL and the account holder has not yet passed KYC.

Allowable Values:

A valid pre_kyc_controls object

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 false, 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

Existing real_time_fee_group_token.

Send a GET request to /realtimefeegroups to retrieve real-time fee group tokens.

name

string
Optional

Descriptive name for the account holder group.

Allowable Values:

1–40 chars

Response body
Fields Description

config

object
Conditionally returned

Contains configuration fields for the account holder group. This object is returned when present in the resource.

Allowable Values:

A valid config object

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.

This field is returned when present in the resource.

Allowable Values:

true, 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.

This field is returned when present in the resource.

Allowable Values:

ALWAYS, CONDITIONAL, NEVER

config.pre_kyc_controls

object
Conditionally returned

Contains configuration fields for a number of controls. This object is returned when present in the resource.

NOTE: These controls are in effect only if kyc_required is CONDITIONAL and the account holder has not yet passed KYC.

Allowable Values:

A valid pre_kyc_controls object

config.pre_kyc_controls.balance_max

decimal
Conditionally returned

Specifies the maximum ledger balance allowed for members of the account holder group. This field is returned when present in the resource.

Allowable Values:

0.01 min

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. This field is returned when present in the resource.

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

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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

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

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.

This field is returned when present in the resource.

Allowable Values:

true, 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. This field is returned when present in the resource.

Allowable Values:

36 char max

name

string
Conditionally returned

Descriptive name for the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group name

token

string
Conditionally returned

The unique identifier of the account holder group. This field is returned when present in the resource.

Allowable Values:

Existing account holder group token

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter