> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Holder Groups

> Use account holder groups to configure settings for multiple account holders simultaneously.

export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
      text: "mint-text-green-700 dark:mint-text-green-400",
      border: "mint-border-green-300 dark:mint-border-green-700"
    },
    POST: {
      bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
      text: "mint-text-blue-700 dark:mint-text-blue-400"
    },
    PUT: {
      bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
      text: "mint-text-yellow-700 dark:mint-text-yellow-400"
    },
    PATCH: {
      bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
      text: "mint-text-orange-700 dark:mint-text-orange-400"
    },
    DELETE: {
      bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
      text: "mint-text-red-700 dark:mint-text-red-400"
    },
    API: {
      bg: "mint-bg-black",
      text: "mint-text-white"
    }
  };
  const MethodBadge = ({method}) => {
    const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
    return <span className={`
          method-pill rounded-lg font-semibold px-1.5 py-0.5 text-xs leading-5 ${style.bg} ${style.text}`}>
        {method?.toUpperCase()}
      </span>;
  };
  const content = <div className="group flex items-center gap-4 border border-gray-200 dark:border-gray-700 rounded-xl p-5 hover:border-gray-400 dark:hover:border-gray-500 hover:shadow-md transition-all cursor-pointer">
      {}
      <div className="shrink-0">
        <MethodBadge method={method} />
      </div>
      {}
      <div className="flex-1 min-w-0">
        <p className="font-semibold text-gray-900 dark:text-white text-sm leading-snug">{title}</p>
        {children && <p className="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">{children}</p>}
      </div>
    </div>;
  if (!href) return content;
  return <a href={href} className="block no-underline border-b-0 mb-2">
      {content}
    </a>;
};

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.

<h2 id="post_accountholdergroups">
  Create account holder group
</h2>

**Action:** `POST`\
**Endpoint:** `/accountholdergroups`

{/* <EndpointCard
title="Creates an account holder group object"
path="/accountholdergroups"
method="post"
/> */}

Use this endpoint to create an account holder group.

<h3 id="_request_body">
  Request body
</h3>

| Fields                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config<br /><br />object<br /><br />Optional                                                     | Contains configuration fields for the account holder group.<br /><br />**Allowable Values:**<br /><br />`is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`                                                                                                                                                                                                                                                                                                            |
| config.**is\_reloadable**<br /><br />boolean<br /><br />Optional                                 | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                             |
| config.**kyc\_required**<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`ALWAYS`, `CONDITIONAL`, `NEVER`<br /><br />**Default value:**<br />`NEVER` |
| config.**pre\_kyc\_controls**<br /><br />object<br /><br />Optional                              | Contains configuration fields for a number of controls.<br /><br />**NOTE:** These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC.<br /><br />**Allowable Values:**<br /><br />`balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`                                                                                                                         |
| config.pre\_kyc\_controls.**balance\_max**<br /><br />decimal<br /><br />Optional                | Specifies the maximum ledger balance allowed for members of the account holder group.<br /><br />**Allowable Values:**<br /><br />0.01 min<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                                                                     |
| config.pre\_kyc\_controls.**cash\_access\_enabled**<br /><br />boolean<br /><br />Optional       | If set to `false`, this control prohibits an account holder’s cards from being used at an ATM.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                            |
| config.pre\_kyc\_controls.**enable\_non\_program\_loads**<br /><br />boolean<br /><br />Optional | If set to `true`, funds can only be loaded from a program funding source.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                |
| config.pre\_kyc\_controls.**international\_enabled**<br /><br />boolean<br /><br />Optional      | If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                      |
| config.pre\_kyc\_controls.**is\_reloadable\_pre\_kyc**<br /><br />boolean<br /><br />Optional    | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                              |
| config.**real\_time\_fee\_group\_token**<br /><br />string<br /><br />Optional                   | Associates the specified real-time fee group with the members of the account holder group.<br /><br />**Allowable Values:**<br /><br />36 char max                                                                                                                                                                                                                                                                                                                                                  |
| name<br /><br />string<br /><br />Optional                                                       | Descriptive name for the account holder group.<br /><br />**Allowable Values:**<br /><br />1–40 chars                                                                                                                                                                                                                                                                                                                                                                                               |
| token<br /><br />string<br /><br />Optional                                                      | Unique identifier of the account holder group.<br /><br />**Allowable Values:**<br /><br />1–36 chars                                                                                                                                                                                                                                                                                                                                                                                               |

<h3 id="_sample_request_body">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "token": "account_holder_group_01",
  "name": "Account Holder Group 01"
}
```

<h3 id="_response_body">
  Response body
</h3>

| Fields                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config<br /><br />object<br /><br />Conditionally returned                                                     | Contains configuration fields for the account holder group.<br /><br />**Allowable Values:**<br /><br />`is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`                                                                                                                                                                                                                                                                                                            |
| config.**is\_reloadable**<br /><br />boolean<br /><br />Conditionally returned                                 | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                             |
| config.**kyc\_required**<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`ALWAYS`, `CONDITIONAL`, `NEVER`<br /><br />**Default value:**<br />`NEVER` |
| config.**pre\_kyc\_controls**<br /><br />object<br /><br />Conditionally returned                              | Contains configuration fields for a number of controls.<br /><br />**NOTE:** These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC.<br /><br />**Allowable Values:**<br /><br />`balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`                                                                                                                         |
| config.pre\_kyc\_controls.**balance\_max**<br /><br />decimal<br /><br />Conditionally returned                | Specifies the maximum ledger balance allowed for members of the account holder group.<br /><br />**Allowable Values:**<br /><br />0.01 min<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                                                                     |
| config.pre\_kyc\_controls.**cash\_access\_enabled**<br /><br />boolean<br /><br />Conditionally returned       | If set to `false`, this control prohibits an account holder’s cards from being used at an ATM.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                            |
| config.pre\_kyc\_controls.**enable\_non\_program\_loads**<br /><br />boolean<br /><br />Conditionally returned | If set to `true`, funds can only be loaded from a program funding source.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                |
| config.pre\_kyc\_controls.**international\_enabled**<br /><br />boolean<br /><br />Conditionally returned      | If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                      |
| config.pre\_kyc\_controls.**is\_reloadable\_pre\_kyc**<br /><br />boolean<br /><br />Conditionally returned    | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                              |
| config.**real\_time\_fee\_group\_token**<br /><br />string<br /><br />Conditionally returned                   | Associates the specified real-time fee group with the members of the account holder group.<br /><br />**Allowable Values:**<br /><br />36 char max                                                                                                                                                                                                                                                                                                                                                  |
| name<br /><br />string<br /><br />Conditionally returned                                                       | Descriptive name for the account holder group.<br /><br />This field is returned if it exists in the resource.<br /><br />**Allowable Values:**<br /><br />Existing account holder group name                                                                                                                                                                                                                                                                                                       |
| token<br /><br />string<br /><br />Conditionally returned                                                      | Unique identifier of the account holder group.<br /><br />This field is always returned.<br /><br />**Allowable Values:**<br /><br />Existing account holder group token                                                                                                                                                                                                                                                                                                                            |

<h3 id="_sample_response_body">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "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
    }
  }
}
```

<h2 id="get_accountholdergroups">
  List account holder groups
</h2>

**Action:** `GET`\
**Endpoint:** `/accountholdergroups`

{/* <EndpointCard
title="Lists account holder groups"
path="/accountholdergroups"
method="get"
/> */}

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

<h3 id="_url_query_parameters">
  URL query parameters
</h3>

| Fields                                              | Description                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count<br /><br />integer<br /><br />Optional        | Number of resources to retrieve.<br /><br />**Allowable Values:**<br /><br />1-10                                                                                                                                                                                                                                                                                  |
| start\_index<br /><br />integer<br /><br />Optional | Sort order index of the first resource in the returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                                                                                                                                                                              |
| sort\_by<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`createdTime`, `lastModifiedTime`, or any field in the resource model |

<h3 id="_response_body_2">
  Response body
</h3>

| Fields                                                                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count<br /><br />integer<br /><br />Conditionally returned                                                             | Number of resources to retrieve.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />1-10                                                                                                                                                                                                                                                                                                                                  |
| data<br /><br />array of objects<br /><br />Conditionally returned                                                     | Array of account holder group objects.<br /><br />Objects are returned as appropriate to your query.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more account holder group objects                                                                                                                                                                                                                                                                                            |
| data\[].**config**<br /><br />object<br /><br />Conditionally returned                                                 | Contains configuration fields for the account holder group.<br /><br />**Allowable Values:**<br /><br />`is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`                                                                                                                                                                                                                                                                                                            |
| data\[].config.**is\_reloadable**<br /><br />boolean<br /><br />Conditionally returned                                 | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                             |
| data\[].config.**kyc\_required**<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`ALWAYS`, `CONDITIONAL`, `NEVER`<br /><br />**Default value:**<br />`NEVER` |
| data\[].config.**pre\_kyc\_controls**<br /><br />object<br /><br />Conditionally returned                              | Contains configuration fields for a number of controls.<br /><br />**NOTE:** These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC.<br /><br />**Allowable Values:**<br /><br />`balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`                                                                                                                         |
| data\[].config.pre\_kyc\_controls.**balance\_max**<br /><br />decimal<br /><br />Conditionally returned                | Specifies the maximum ledger balance allowed for members of the account holder group.<br /><br />**Allowable Values:**<br /><br />0.01 min<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                                                                     |
| data\[].config.pre\_kyc\_controls.**cash\_access\_enabled**<br /><br />boolean<br /><br />Conditionally returned       | If set to `false`, this control prohibits an account holder’s cards from being used at an ATM.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                            |
| data\[].config.pre\_kyc\_controls.**enable\_non\_program\_loads**<br /><br />boolean<br /><br />Conditionally returned | If set to `true`, funds can only be loaded from a program funding source.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                |
| data\[].config.pre\_kyc\_controls.**international\_enabled**<br /><br />boolean<br /><br />Conditionally returned      | If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                      |
| data\[].config.pre\_kyc\_controls.**is\_reloadable\_pre\_kyc**<br /><br />boolean<br /><br />Conditionally returned    | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                              |
| data\[].config.**real\_time\_fee\_group\_token**<br /><br />string<br /><br />Conditionally returned                   | Associates the specified real-time fee group with the members of the account holder group.<br /><br />**Allowable Values:**<br /><br />36 char max                                                                                                                                                                                                                                                                                                                                                  |
| data\[].**name**<br /><br />string<br /><br />Conditionally returned                                                   | Descriptive name for the account holder group.<br /><br />This field is returned if it exists in the resource.<br /><br />**Allowable Values:**<br /><br />Existing account holder group name                                                                                                                                                                                                                                                                                                       |
| data\[].**token**<br /><br />string<br /><br />Conditionally returned                                                  | Unique identifier of the account holder group.<br /><br />This field is always returned.<br /><br />**Allowable Values:**<br /><br />Existing account holder group token                                                                                                                                                                                                                                                                                                                            |
| end\_index<br /><br />integer<br /><br />Conditionally returned                                                        | Sort order index of the last resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                                                                                                                                                                                                                               |
| is\_more<br /><br />boolean<br /><br />Conditionally returned                                                          | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />`true`, `false`                                                                                                                                                                                                                |
| start\_index<br /><br />integer<br /><br />Conditionally returned                                                      | Sort order index of the first resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                                                                                                                                                                                                                              |

<h3 id="_sample_response_body_2">
  Sample response body
</h3>

```json JSON expandable lines wrap theme={null}
{
  "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
        }
      }
    }
  ]
}
```

<h2 id="get_accountholdergroups_token">
  Retrieve account holder group
</h2>

**Action:** `GET`\
**Endpoint:** `/accountholdergroups/{token}`

{/* <EndpointCard
title="Returns a specific account holder group object"
path="/accountholdergroups/{token}"
method="get"
/> */}

Use this endpoint to retrieve a specific account holder group.

<h3 id="_url_path_parameters">
  URL path parameters
</h3>

| Fields                                      | Description                                                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| token<br /><br />string<br /><br />Required | Unique identifier of the account holder group.<br /><br />**Allowable Values:**<br /><br />Existing account holder group token |

<h3 id="_response_body_3">
  Response body
</h3>

| Fields                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config<br /><br />object<br /><br />Conditionally returned                                                     | Contains configuration fields for the account holder group.<br /><br />**Allowable Values:**<br /><br />`is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`                                                                                                                                                                                                                                                                                                            |
| config.**is\_reloadable**<br /><br />boolean<br /><br />Conditionally returned                                 | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                             |
| config.**kyc\_required**<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`ALWAYS`, `CONDITIONAL`, `NEVER`<br /><br />**Default value:**<br />`NEVER` |
| config.**pre\_kyc\_controls**<br /><br />object<br /><br />Conditionally returned                              | Contains configuration fields for a number of controls.<br /><br />**NOTE:** These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC.<br /><br />**Allowable Values:**<br /><br />`balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`                                                                                                                         |
| config.pre\_kyc\_controls.**balance\_max**<br /><br />decimal<br /><br />Conditionally returned                | Specifies the maximum ledger balance allowed for members of the account holder group.<br /><br />**Allowable Values:**<br /><br />0.01 min<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                                                                     |
| config.pre\_kyc\_controls.**cash\_access\_enabled**<br /><br />boolean<br /><br />Conditionally returned       | If set to `false`, this control prohibits an account holder’s cards from being used at an ATM.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                            |
| config.pre\_kyc\_controls.**enable\_non\_program\_loads**<br /><br />boolean<br /><br />Conditionally returned | If set to `true`, funds can only be loaded from a program funding source.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                |
| config.pre\_kyc\_controls.**international\_enabled**<br /><br />boolean<br /><br />Conditionally returned      | If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                      |
| config.pre\_kyc\_controls.**is\_reloadable\_pre\_kyc**<br /><br />boolean<br /><br />Conditionally returned    | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                              |
| config.**real\_time\_fee\_group\_token**<br /><br />string<br /><br />Conditionally returned                   | Associates the specified real-time fee group with the members of the account holder group.<br /><br />**Allowable Values:**<br /><br />36 char max                                                                                                                                                                                                                                                                                                                                                  |
| name<br /><br />string<br /><br />Conditionally returned                                                       | Descriptive name for the account holder group.<br /><br />This field is returned if it exists in the resource.<br /><br />**Allowable Values:**<br /><br />Existing account holder group name                                                                                                                                                                                                                                                                                                       |
| token<br /><br />string<br /><br />Conditionally returned                                                      | Unique identifier of the account holder group.<br /><br />This field is always returned.<br /><br />**Allowable Values:**<br /><br />Existing account holder group token                                                                                                                                                                                                                                                                                                                            |

<h3 id="_sample_response_body_3">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "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
    }
  }
}
```

<h2 id="put_accountholdergroups_token">
  Update account holder group
</h2>

**Action:** `PUT`\
**Endpoint:** `/accountholdergroups/{token}`

{/* <EndpointCard
title="Updates an account holder group object"
path="/accountholdergroups/{token}"
method="put"
/> */}

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](http://json.org) format in the body of the request.

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

<h3 id="_url_path_parameters_2">
  URL path parameters
</h3>

| Fields                                      | Description                                                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| token<br /><br />string<br /><br />Required | Unique identifier of the account holder group.<br /><br />**Allowable Values:**<br /><br />Existing account holder group token |

<h3 id="_request_body_2">
  Request body
</h3>

| Fields                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config<br /><br />object<br /><br />Optional                                                     | Contains configuration fields for the account holder group.<br /><br />**Allowable Values:**<br /><br />`is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`                                                                                                                                                                                                                                                                                                            |
| config.**is\_reloadable**<br /><br />boolean<br /><br />Optional                                 | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                             |
| config.**kyc\_required**<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`ALWAYS`, `CONDITIONAL`, `NEVER`<br /><br />**Default value:**<br />`NEVER` |
| config.**pre\_kyc\_controls**<br /><br />object<br /><br />Optional                              | Contains configuration fields for a number of controls.<br /><br />**NOTE:** These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC.<br /><br />**Allowable Values:**<br /><br />`balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`                                                                                                                         |
| config.pre\_kyc\_controls.**balance\_max**<br /><br />decimal<br /><br />Optional                | Specifies the maximum ledger balance allowed for members of the account holder group.<br /><br />**Allowable Values:**<br /><br />0.01 min<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                                                                     |
| config.pre\_kyc\_controls.**cash\_access\_enabled**<br /><br />boolean<br /><br />Optional       | If set to `false`, this control prohibits an account holder’s cards from being used at an ATM.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                            |
| config.pre\_kyc\_controls.**enable\_non\_program\_loads**<br /><br />boolean<br /><br />Optional | If set to `true`, funds can only be loaded from a program funding source.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                |
| config.pre\_kyc\_controls.**international\_enabled**<br /><br />boolean<br /><br />Optional      | If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                      |
| config.pre\_kyc\_controls.**is\_reloadable\_pre\_kyc**<br /><br />boolean<br /><br />Optional    | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                              |
| config.**real\_time\_fee\_group\_token**<br /><br />string<br /><br />Optional                   | Associates the specified real-time fee group with the members of the account holder group.<br /><br />**Allowable Values:**<br /><br />36 char max                                                                                                                                                                                                                                                                                                                                                  |
| name<br /><br />string<br /><br />Optional                                                       | Descriptive name for the account holder group.<br /><br />**Allowable Values:**<br /><br />1–40 chars                                                                                                                                                                                                                                                                                                                                                                                               |

<h3 id="_sample_request_body_2">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "config": {
    "pre_kyc_controls": {
      "balance_max": 500
    }
  }
}
```

<h3 id="_response_body_4">
  Response body
</h3>

| Fields                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config<br /><br />object<br /><br />Conditionally returned                                                     | Contains configuration fields for the account holder group.<br /><br />**Allowable Values:**<br /><br />`is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`                                                                                                                                                                                                                                                                                                            |
| config.**is\_reloadable**<br /><br />boolean<br /><br />Conditionally returned                                 | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                             |
| config.**kyc\_required**<br /><br />string<br /><br />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.<br /><br />**Allowable Values:**<br /><br />`ALWAYS`, `CONDITIONAL`, `NEVER`<br /><br />**Default value:**<br />`NEVER` |
| config.**pre\_kyc\_controls**<br /><br />object<br /><br />Conditionally returned                              | Contains configuration fields for a number of controls.<br /><br />**NOTE:** These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC.<br /><br />**Allowable Values:**<br /><br />`balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`                                                                                                                         |
| config.pre\_kyc\_controls.**balance\_max**<br /><br />decimal<br /><br />Conditionally returned                | Specifies the maximum ledger balance allowed for members of the account holder group.<br /><br />**Allowable Values:**<br /><br />0.01 min<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                                                                     |
| config.pre\_kyc\_controls.**cash\_access\_enabled**<br /><br />boolean<br /><br />Conditionally returned       | If set to `false`, this control prohibits an account holder’s cards from being used at an ATM.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                            |
| config.pre\_kyc\_controls.**enable\_non\_program\_loads**<br /><br />boolean<br /><br />Conditionally returned | If set to `true`, funds can only be loaded from a program funding source.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                |
| config.pre\_kyc\_controls.**international\_enabled**<br /><br />boolean<br /><br />Conditionally returned      | If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code.<br /><br />**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.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                      |
| config.pre\_kyc\_controls.**is\_reloadable\_pre\_kyc**<br /><br />boolean<br /><br />Conditionally returned    | If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load.<br /><br />This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                              |
| config.**real\_time\_fee\_group\_token**<br /><br />string<br /><br />Conditionally returned                   | Associates the specified real-time fee group with the members of the account holder group.<br /><br />**Allowable Values:**<br /><br />36 char max                                                                                                                                                                                                                                                                                                                                                  |
| name<br /><br />string<br /><br />Conditionally returned                                                       | Descriptive name for the account holder group.<br /><br />This field is returned if it exists in the resource.<br /><br />**Allowable Values:**<br /><br />Existing account holder group name                                                                                                                                                                                                                                                                                                       |
| token<br /><br />string<br /><br />Conditionally returned                                                      | Unique identifier of the account holder group.<br /><br />This field is always returned.<br /><br />**Allowable Values:**<br /><br />Existing account holder group token                                                                                                                                                                                                                                                                                                                            |