DOCS

New!

/

10 minute read

August 2, 2019

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 according to whether or not an account holder has passed verification (KYC).

You associate an account holder with an account holder group by way of 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

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to create an account holder group.

Body field details

Fields Description

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: 36 char max

name

string, optional

Descriptive name for the account holder group.

Allowable Values: 40 char max

config

object, optional

Contains configuration fields for the account holder group.

The config object

Fields Description

kyc_required

string, optional

Set to ALWAYS, new account holders are created in an UNVERIFIED status and must pass identity verification (KYC) before they can be active; set to CONDITIONAL, new account holders begin in a LIMITED status and have limited actions available before passing identity verification; set to NEVER, new account holders are created in an active state.

Allowable Values: ALWAYS, CONDITIONAL, NEVER

Default value: NEVER

pre_kyc_controls

object, optional

Contains configuration fields for a number of controls. These controls are in effect only if kyc_required is CONDITIONAL and the account holder has not yet passed KYC.

is_reloadable

boolean, optional

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, MSA orders, offer orders, peer transfers, direct deposits, but does not apply to operator adjustments.

Allowable Values: true, false

Default value: true

real_time_fee_group_token

string, optional

Associates the specified real-time fee group with the members of the account holder group.

Allowable Values: Existing real_time_fee_group_token.

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

The config.pre_kyc_controls object

Fields Description

cash_access_enabled

boolean, optional

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

international_enabled

boolean, optional

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

balance_max

integer, optional

Specifies the maximum ledger balance allowed for members of the account holder group.

Allowable Values: Any positive integer.

Default value: 1000

is_reloadable_pre_kyc

boolean, optional

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, MSA orders, offer orders, peer transfers, direct deposits, but does not apply to operator adjustments.

Allowable Values: true, false

Default value: false

enable_non_program_loads

boolean, optional

Set to true, funds can only be loaded from a program funding source.

This restriction applies to GPA orders, MSA orders, offer orders, peer transfers, direct deposits, but does not apply to operator adjustments.

Allowable Values: true, false

Default value: false

Sample request body

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

Is this helpful?

Sample response body

{
  "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
    }
  }
}

Is this helpful?

Retrieve account holder group

Action: GET
Endpoint: /accountholdergroups/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a specific account holder group.

URL path parameters

Fields Description

token

string, required

Identifies the account holder group you want to retrieve.

Allowable Values: Existing account holder group token.

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

Sample response body

{
  "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
    }
  }
}

Is this helpful?

Update account holder group

Action: PUT
Endpoint: /accountholdergroups/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

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, sned 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. Only values of parameters in the request are modified; all others are left unchanged.

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

Identifies the account holder group you want to retrieve.

Allowable Values: Existing account holder group token.

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

Body field details

Fields Description

name

string, optional

Descriptive name for the account holder group.

Allowable Values: 40 char max

config

object, optional

Contains configuration fields for the account holder group.

The config object

Fields Description

kyc_required

string, optional

Set to ALWAYS, new account holders are created in an UNVERIFIED status and must pass identity verification (KYC) before they can be active; set to CONDITIONAL, new account holders begin in a LIMITED status and have limited actions available before passing identity verification; set to NEVER, new account holders are created in an active state.

Allowable Values: ALWAYS, CONDITIONAL, NEVER

Default value: NEVER

pre_kyc_controls

object, optional

Contains configuration fields for a number of controls. These controls are in effect only if kyc_required is CONDITIONAL and the account holder has not yet passed KYC.

is_reloadable

boolean, optional

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, MSA orders, offer orders, peer transfers, direct deposits, but does not apply to operator adjustments.

Allowable Values: true, false

Default value: true

real_time_fee_group_token

string, optional

Associates the specified real-time fee group with the members of the account holder group.

Allowable Values: Existing real_time_fee_group_token.

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

The config.pre_kyc_controls object

Fields Description

cash_access_enabled

boolean, optional

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

international_enabled

boolean, optional

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

balance_max

integer, optional

Specifies the maximum ledger balance allowed for members of the account holder group.

Allowable Values: Any positive integer.

is_reloadable_pre_kyc

boolean, optional

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, MSA orders, offer orders, peer transfers, direct deposits, but does not apply to operator adjustments.

Allowable Values: true, false

Default value: false

enable_non_program_loads

boolean, optional

Set to true, funds can only be loaded from a program funding source.

This restriction applies to GPA orders, MSA orders, offer orders, peer transfers, direct deposits, but does not apply to operator adjustments.

Allowable Values: true, false

Default value: false

Sample request body

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

Is this helpful?

Sample response body

{
  "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
    }
  }
}

Is this helpful?

List account holder groups

Action: GET
Endpoint: /accountholdergroups

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to return an array of all account holder groups.

Sample response body

{
  "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
        }
      }
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.