Create account holder group - Marqeta Docs

POST/

Use this endpoint to create an account holder group.

Request body

Fields	Description
config object Optional	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Optional	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Optional	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Optional	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Optional	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Optional	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Optional	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Optional	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Optional	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Optional	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Optional	Descriptive name for the account holder group. Allowable Values: 1–40 chars
token string Optional	Unique identifier of the account holder group. Allowable Values: 1–36 chars

Sample request body

JSON

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

Response body

Fields	Description
config object Conditionally returned	Contains configuration fields for the account holder group. Allowable Values: `is_reloadable`, `kyc_required`, `pre_kyc_controls`, `real_time_fee_group_token`
config.is_reloadable boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after the initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.kyc_required string Conditionally returned	If set to `ALWAYS`, new account holders are created in an `UNVERIFIED` status and must pass identity verification (KYC) before they can be active; if set to `CONDITIONAL`, new account holders begin in a `LIMITED` status and have limited actions available before passing identity verification; if set to `NEVER`, new account holders are created in an active state. Allowable Values: `ALWAYS`, `CONDITIONAL`, `NEVER` Default value: `NEVER`
config.pre_kyc_controls object Conditionally returned	Contains configuration fields for a number of controls. NOTE: These controls are in effect only if `kyc_required` is `ALWAYS` or `CONDITIONAL` and the account holder has not yet passed KYC. Allowable Values: `balance_max`, `cash_access_enabled`, `enable_non_program_loads`, `international_enabled`, `is_reloadable_pre_kyc`
config.pre_kyc_controls.balance_max decimal Conditionally returned	Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0
config.pre_kyc_controls.cash_access_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s cards from being used at an ATM. NOTE: If a card product’s `config.poi.atm` field is set to `false`, associated cards are prohibited from being used at an ATM regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.enable_non_program_loads boolean Conditionally returned	If set to `true`, funds can only be loaded from a program funding source. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.international_enabled boolean Conditionally returned	If set to `false`, this control prohibits an account holder from conducting transactions with a non-domestic country code. NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: `true`, `false` Default value: `false`
config.pre_kyc_controls.is_reloadable_pre_kyc boolean Conditionally returned	If set to `false`, this control prohibits an account holder’s account from being reloaded with funds after an initial load. This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: `true`, `false` Default value: `false`
config.real_time_fee_group_token string Conditionally returned	Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max
name string Conditionally returned	Descriptive name for the account holder group. This field is returned if it exists in the resource. Allowable Values: Existing account holder group name
token string Conditionally returned	Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token

Sample response body

JSON

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