Creating a Corporate Hierarchy

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.

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 Create Group with these parameters:

   • groupName: CDE Root Group
   • externalId: L0000
   • phone: [valid phone number, digits only]; if this parameter is populated, then phoneCountryCode is required.
   • phoneCountryCode: +[valid country code]; if this parameter is populated, then phone is required.
   • Other business profile information as desired
   • maxLevel: 3
   • smartdata: Set to Y if you are signed up for the Mastercard Smart Data service, and you would like to receive Smart Data for all of the accounts associated with this root level and below.
   • employerId: The employer ID (EID) from the IRS, if known.

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 Set Account Group Relationships 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.

Viewing the group ID

The group ID is available in the following:

• Posted Transactions RDF as CH GROUP ID
• Events messages as ch_group_id. You must request that ch_group_id be enabled for each event message, as desired.

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 Update Group and pass the parameter(s) to change:

• phone: 18015552323

Retrieve group information

To retrieve group metadata, call Get Groups Info. 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:

"response_data": [
    {
      "group_id": "0",
      "parent_group_id": Null,
      "group_name": "CDE Root Group",
      "external_id": "L0000",
      "max_level": 3,
      "phone_country_code": "+1",
      "phone": "18015551456",
      "business_legal_name": "CDE Corp",
      "doing_business_as": "SportsBall Enterprises",
      "primary_contact_email": "[email protected]",
      "primary_contact_name": "Maxina Seward",
      "smartdata": "Y",
      "employer_id": "99-9999999"
    },
    {
      "group_id": "4",
      "parent_group_id": "3",
      "max_level": Null,
      "group_name": "Group D",
      "external_id": "L3001",
      "business_legal_name": "",
      "doing_business_as": "",
      "phone_country_code": "",
      "phone": "",
      "primary_contact_email": "",
      "primary_contact_name": "",
      "smartdata": "",  
      "employer_id": "" 
      }
]

Retrieve root groups

To retrieve all of the root groups in your core, call Get Root Groups. The endpoint returns this:

"response_data":
    {
      "group_id": "0",
      "group_name": "Root Group"
    }

Retrieve the hierarchy

To retrieve the groups in the hierarchy, call Get Group Hierarchy. 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:

"response_data": {
	"group_id": "2",
	"group_name": "Group B",
	"children": [
		{
		"group_id": "3",  
		"group_name": "Group C", 
		"children": [
			{
				"group_id": "4",  
				"group_name": "Group D", 
				"children": []
			} 
	 	]
    }
	]
}

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

• groupId: 2
• subGroupLevel: 1

Response:

"response_data": {
    "group_id": "2",
    "group_name": "Group B",
    "children": [
        {
		"group_id": "3",  
		"group_name": "Group C", 
		"children": []}
       ]
   }

Retrieve the accounts in a group or groups

To retrieve the accounts in one or more groups, call Get Account Group Relationships. For example, to retrieve the accounts for Group B only, call Get Account Group Relationships with these parameters:

• groupId: 2
• includeSubGroups: N

Response:

"response_data": [
    	{
        	"group_id": "1001",
        	"pmt_ref_no": [
            	"('PRN5',)",
            	"('PRN6',)"
        	]
    	}
	]

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:

"response_data": [
    	{
        	"group_id": "2",
        	"pmt_ref_no": [
            	"('PRN5',)",
            	"('PRN6',)"
        	]
    	},
    	{
        	"group_id": "3",
        	"pmt_ref_no": [
            	"('PRN7',)",
            	"('PRN8',)"
        	]
    	},
    	{
        	"group_id": "4",
        	"pmt_ref_no": [
            	"('PRN9',)",
            	"('PRN10',)"
        	]
    	}	
]

Move an account to a new group

To move Account 1 to Group A, call Set Account Group Relationships with these parameters:

• groupId: 1
• accountNos: PRN1 (See Inputting multiple values for instructions on passing more than one value for this parameter.)

Response:

"response_data": [
	{
      "group_id": "1",
      "pmt_ref_no": [
		  "PRN1" 
	 ]
   }
]

The resulting hierarchy looks like this:

Delete a group

Use Delete Groups 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 Remove Account Group Relationships to remove the accounts without moving them to a new group. You can link the accounts to another group later using Set Account Group Relationships.
• 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 Create Group 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 Set Account Group Relationships 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 Delete Groups 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:

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:

POST /intserv/4.0/setAccountGroupRelationships HTTP/1.1
Host: [URL]
response-content-type: json
Content-Type: application/x-www-form-urlencoded
Content-Length: 174

apiLogin=[redacted]&apiTransKey=[redacted]&providerId=19&transactionId=45d7ecbd-3e53-4a69-8971-af3bbaf17956&groupId=1001&accountNos=777777777777&accountNos=888888888888

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:

POST /intserv/4.0/getGroupsInfo HTTP/1.1
Host: [URL]
response-content-type: json
Content-Type: application/json
Content-Length: 179

{
    "apiLogin": [redacted],
    "apiTransKey": [redacted],
    "providerId": "19",
    "transactionId": "d3914a0b-ce55-4d95-9926-2c8f3a3a9f10",
    "groupIds": ["1", "2", "5"]
}