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:POSTEndpoint:
/accountholdergroups
Use this endpoint to create an account holder group.
Request body
| Fields | Description |
|---|---|
| config object Optional | Contains configuration fields for the account holder group. Allowable Values: is_reloadable, kyc_required, pre_kyc_controls, real_time_fee_group_token |
| config.is_reloadable boolean Optional | If set to false, this control prohibits an account holder’s account from being reloaded with funds after the initial load.This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: true, falseDefault 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, NEVERDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, NEVERDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, falseDefault 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
}
}
}
List account holder groups
Action:GETEndpoint:
/accountholdergroups
Use this endpoint to return an array of all account holder groups.
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of resources to retrieve. Allowable Values: 1-10 |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| sort_by string Optional | Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.Allowable Values: createdTime, lastModifiedTime, or any field in the resource model |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
| data array of objects Conditionally returned | Array of account holder group objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more account holder group objects |
| data[].config object Conditionally returned | Contains configuration fields for the account holder group. Allowable Values: is_reloadable, kyc_required, pre_kyc_controls, real_time_fee_group_token |
| data[].config.is_reloadable boolean Conditionally returned | If set to false, this control prohibits an account holder’s account from being reloaded with funds after the initial load.This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: true, falseDefault value: false |
| data[].config.kyc_required string Conditionally returned | If set to ALWAYS, new account holders are created in an UNVERIFIED status and must pass identity verification (KYC) before they can be active; if set to CONDITIONAL, new account holders begin in a LIMITED status and have limited actions available before passing identity verification; if set to NEVER, new account holders are created in an active state.Allowable Values: ALWAYS, CONDITIONAL, NEVERDefault value: NEVER |
| data[].config.pre_kyc_controls object Conditionally returned | Contains configuration fields for a number of controls. NOTE: These controls are in effect only if kyc_required is ALWAYS or CONDITIONAL and the account holder has not yet passed KYC.Allowable Values: balance_max, cash_access_enabled, enable_non_program_loads, international_enabled, is_reloadable_pre_kyc |
| data[].config.pre_kyc_controls.balance_max decimal Conditionally returned | Specifies the maximum ledger balance allowed for members of the account holder group. Allowable Values: 0.01 min Default value: 0 |
| data[].config.pre_kyc_controls.cash_access_enabled boolean Conditionally returned | If set to false, this control prohibits an account holder’s cards from being used at an ATM.NOTE: If a card product’s config.poi.atm field is set to false, associated cards are prohibited from being used at an ATM regardless of this control’s setting.Allowable Values: true, falseDefault value: false |
| data[].config.pre_kyc_controls.enable_non_program_loads boolean Conditionally returned | If set to true, funds can only be loaded from a program funding source.This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: true, falseDefault value: false |
| data[].config.pre_kyc_controls.international_enabled boolean Conditionally returned | If set to false, this control prohibits an account holder from conducting transactions with a non-domestic country code.NOTE: If a card product is configured to prohibit non-domestic transactions, its associated cards are prohibited from such transactions regardless of this control’s setting. Allowable Values: true, falseDefault value: false |
| data[].config.pre_kyc_controls.is_reloadable_pre_kyc boolean Conditionally returned | If set to false, this control prohibits an account holder’s account from being reloaded with funds after an initial load.This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: true, falseDefault value: false |
| data[].config.real_time_fee_group_token string Conditionally returned | Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
| data[].name string Conditionally returned | Descriptive name for the account holder group. This field is returned if it exists in the resource. Allowable Values: Existing account holder group name |
| data[].token string Conditionally returned | Unique identifier of the account holder group. This field is always returned. Allowable Values: Existing account holder group token |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Sample response body
JSON
{
"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
}
}
}
]
}
Retrieve account holder group
Action:GETEndpoint:
/accountholdergroups/{token}
Use this endpoint to retrieve a specific account holder group.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the account holder group. Allowable Values: Existing account holder group token |
Response body
| Fields | Description |
|---|---|
| config object Conditionally returned | Contains configuration fields for the account holder group. Allowable Values: is_reloadable, kyc_required, pre_kyc_controls, real_time_fee_group_token |
| config.is_reloadable boolean Conditionally returned | If set to false, this control prohibits an account holder’s account from being reloaded with funds after the initial load.This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: true, falseDefault 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, NEVERDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, falseDefault 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
}
}
}
Update account holder group
Action:PUTEndpoint:
/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.
While you can update account holder groups that you create, the default group is restricted and requires special permissions to update.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the account holder group. Allowable Values: Existing account holder group token |
Request body
| Fields | Description |
|---|---|
| config object Optional | Contains configuration fields for the account holder group. Allowable Values: is_reloadable, kyc_required, pre_kyc_controls, real_time_fee_group_token |
| config.is_reloadable boolean Optional | If set to false, this control prohibits an account holder’s account from being reloaded with funds after the initial load.This restriction applies to GPA orders, peer transfers, and direct deposits, but does not apply to operator adjustments. Allowable Values: true, falseDefault 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, NEVERDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, falseDefault value: false |
| config.real_time_fee_group_token string Optional | Associates the specified real-time fee group with the members of the account holder group. Allowable Values: 36 char max |
| name string Optional | Descriptive name for the account holder group. Allowable Values: 1–40 chars |
Sample request body
JSON
{
"config": {
"pre_kyc_controls": {
"balance_max": 500
}
}
}
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, falseDefault 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, NEVERDefault 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, falseDefault 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, falseDefault 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, falseDefault 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, falseDefault 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 |