Corporate Hierarchy is a way to create a hierarchy of groups and then associate accounts with the groups. A hierarchy starts with a root group, which contains a business profile, and then other groups are created as subgroups (child groups), for up to five levels down from the root group. After you create the group hierarchy you can associate accounts (either new or existing) with the groups.

With this arrangement, you can use your own tools to create a dashboard to display the spending for all of the accounts in a group, or all of the accounts in a group plus the subgroups.

## Result of following this procedure

One root group and multiple non-root groups have been created in a hierarchy, and various accounts are associated with the groups.

## Prerequisites

Your core must be on a Galileo AWS instance.

## General characteristics

• You can create multiple root groups in your core.

• A group can have only one parent group.

• An account can belong to only one group at a time.

• The maximum number of levels below a root group is five, making six levels total.

To create a corporate hierarchy, perform these steps:

1. Create a root group with its business profile.

2. Create subgroups, starting at the next level down from the root group. When creating a subgroup, specify the parent group to create the hierarchy.

3. Add accounts to the groups.

## Example hierarchy

This is an example hierarchy. From the root group there are three subgroup levels.

<!--Corp-hierarchy-sample-1111-->

Follow these steps to create the example hierarchy. The example assumes that ten card accounts already exist: their PRNs are represented as PRN1, PRN2, etc. The `externalId`, an optional parameter, contains sample values that specify the hierarchy level of the group. In your setup, you can use `externalId` however you choose.

1. Call <a href="ref:post_creategroup" target="_blank">Create Group</a> with these parameters:

   • `groupName: CDE Root Group`

   • `externalId: L0000`

   • `phone:` [valid phone number, digits only], required

   • `phoneCountryCode: +`[valid country code], required

   • Other business profile information as desired

   • `maxLevel: 3`

   • `smartdata:` Set to `Y` if you are signed up for the <a href="doc:business-banking-enhancements#mastercard-smart-data" target="_blank">Mastercard Smart Data</a> service, and you would like to receive Smart Data for all of the accounts associated with this root level and below.

2. The endpoint returns `group_id: 0`.

3. Call Create Group four more times with these parameters. For `smartdata` do not pass a value.

4. Associate existing accounts with the groups. Call <a href="ref:post_setaccountgrouprelationships" target="_blank">Set Account Group Relationships</a> with these parameters:

   • `groupId: 0`

   • `accountNos: ["PRN1", "PRN2"]` (See [Inputting multiple values](🔗) for instructions on passing more than one value for this parameter.)

5. Repeat the previous step for each group of accounts to associate with a group.

<!--

### Adding new accounts to the groups

After your hierarchy is created, you can add accounts to the hierarchy at the time of account creation. When you use the <a href="ref:post_createaccount" target="_blank">Create Account</a>, <a href="ref:post_completeenrollment" target="_blank">Complete Enrollment</a>, or <a href="ref:post_addaccount" target="_blank">Add Account</a> endpoint to create an account, pass the `groupId` parameter with the ID of the group to associate with the account.

-->

## Managing the hierarchy

Follow these instructions to manage the example hierarchy.

### Change the business profile

To change the business profile, such as the phone number, call <a href="ref:post_updategroup" target="_blank">Update Group</a> and pass the parameter(s) to change:

• `phone: 18015552323`

### Retrieve group information

To retrieve group metadata, call <a href="ref:post_getgroupsinfo" target="_blank">Get Groups Info</a>. For example, to retrieve the metadata for the root group and Group D, call Get Groups Info with this parameter:

• `groupIds: ["0", "4"]` (See [Inputting multiple values](🔗) for instructions on passing more than one value for this parameter.)

Response:

### Retrieve root groups

To retrieve all of the root groups in your core, call <a href="ref:post_getrootgroups" target="_blank">Get Root Groups</a>. The endpoint returns this:

### Retrieve the hierarchy

To retrieve the groups in the hierarchy, call <a href="ref:post_getgrouphierarchy" target="_blank">Get Group Hierarchy</a>. This endpoint returns only the groups, not the accounts.

For example, to return all of the subgroups for Group B (Groups C and D), call Get Group Hierarchy with these parameters:

• `groupId: 2`

• `subGroupLevel:` Leave blank or `0`

Response:

To return only one level below Group B (meaning Group C), pass these parameters:

• `groupId: 2`

• `subGroupLevel: 1`

Response:

### Retrieve the accounts in a group or groups

To retrieve the accounts in one or more groups, call <a href="ref:post_getaccountgrouprelationships" target="_blank">Get Account Group Relationships</a>. For example, to retrieve the accounts for Group B only, call Get Account Group Relationships with these parameters:

• `groupId: 2`

• `includeSubGroups: N`

Response:

To retrieve the accounts for Group B as well as the accounts in Group B's subgroups, pass these parameters:

• `groupId: 2`

• `includeSubGroups: Y`

Response:

### Move an account to a new group

To move Account 1 to Group A, call <a href="ref:post_setaccountgrouprelationships" target="_blank">Set Account Group Relationships</a> with these parameters:

• `groupId: 1`

• `accountNos:` PRN1 (See [Inputting multiple values](🔗) for instructions on passing more than one value for this parameter.)

Response:

The resulting hierarchy looks like this:

<!--Corp-hierarchy-sample-2222-->

### Delete a group

Use <a href="ref:post_deletegroups" target="_blank">Delete Groups</a> to delete one or more groups; however, you cannot delete a group that has subgroups or accounts linked to it.

• To delete a group that has linked accounts, follow the instructions in [Move an account to a new group](🔗) to move the linked accounts to a different group. Alternatively, you can use <a href="ref:post_removeaccountgrouprelationships" target="_blank">Remove Account Group Relationships</a> to remove the accounts without moving them to a new group. You can link the accounts to another group later using <a href="ref:post_setaccountgrouprelationships" target="_blank">Set Account Group Relationships</a>.

• If the group to delete has subgroups, you cannot change the parent ID of those subgroups, so you must recreate the subgroups in another location in the hierarchy, move the subgroups' accounts to the new groups, and then delete the subgroups before deleting the current group.

To delete Group C, for example, you first have to move Group D and its linked accounts to another location in the hierarchy. In this example, the new Group D will become a subgroup of Group B, and the accounts linked to Group C will be moved to Group D.

1. Recreate Group D as a subgroup of Group B by calling <a href="ref:post_creategroup" target="_blank">Create Group</a> with these parameters:

   • `groupName: Group D`

   • `externalId: L2001`

   • `parentGroupId: 2`

2. The endpoint returns `group_id: 5`.

3. Move the Group C and old Group D accounts to the new Group D by calling <a href="ref:post_setaccountgrouprelationships" target="_blank">Set Account Group Relationships</a> with these parameters:

   • `groupId: 5`

   • `accountNos: ["PRN7", "PRN8", "PRN9", "PRN10"]` (See [Inputting multiple values](🔗) for instructions on passing more than one value for this parameter.)

4. Delete the old Group D and Group C by calling <a href="ref:post_deletegroups" target="_blank">Delete Groups</a> with this parameter:

   • `groupIds: ["3", "4"]` (See [Inputting multiple values](🔗) for instructions on passing more than one value for this parameter.)

The resulting hierarchy looks like this:

<!--Corp-hierarchy-sample-3333-->

### Inputting multiple values

Two of the parameters in some endpoints can accept multiple values:

• `accountNos`

• `groupIds`

You have two options to input multiple values: repeat the parameter or use a JSON list. Each option requires a different `Content-Type` header.

#### Repeated parameter

For this method, specify `Content-Type: application/x-www-form-urlencoded` in the header. In the body of the request, pass one parameter/value pair for each value. For example:

#### JSON list

For this method, specify `Content-Type: application/json` in the header. In the body of the request, specify the values as a JSON list. For example: