Setting up a hierarchy to match your organization

Creating a hierarchy with levels

You can set up levels using the Create hierarchy levels endpoint.

levelsAttributes of the levelArray of objects:

  • Name – (Level title, String)
  • Index – (Level index number, Integer, Required)
  • Description – (Level description, String)

A typical call might look like this:

// Create a level
 curl -X POST 
 -H 'Accept: application/json' -H 'content-type: application/json;charset=UTF-8'
 -H 'x-tenant: <Organization ID>'   
 -d '{"levels":[{"name":"Headquarters","index":0,"description":"Root level"},
     {"name":"Region","index":1,"description":"Regional level"},
     {"name":"Country","index":2,"description":"Country level"},
     {"name":"City","index":3,"description":"Main cities level"},
     {"name":"Branch","index":4,"description":"Branch level"}]}'


[{"id":"4f5a9e08-8bd2-4617-a2b9-bbddfe1e9866","index":0,"name":"Central","description":"Root level"},
{"id":"598b30bd-254f-403c-ac1c-e0721960aaa0","index":1,"name":"Region","description":"Regional level"},
{"id":"ffef5781-c286-45f1-8348-2836b9f6a1d3","index":2,"name":"Country","description":"Country level"},
{"id":"654e886f-45e8-4b7d-9413-43703ea08ded","index":3,"name":"City","description":"Main cities level"},
{"id":"baf1b1ea-5d76-457e-80c7-866ab0b014c0","index":4,"name":"Branch","description":"Branch level"}]}

Adding divisions

After creating your levels, you use their IDs to add divisions. The division is also used in scenarios related to account creation, holidays, program binding, and so on.

Path Parameters

hierarchyIdHierarchy IDStringYes
levelIdLevel IDStringYes

Body Parameters

idDivision level IDString
parent_idParent level division IDString
nameDivision nameStringYes
descriptionDivision descriptionString

A typical Create division call with a parent_ID parameter might look like this:

// Create a division
curl -X POST '<hierarchy ID>/levels/<level ID>/divisions'
-H 'x-tenant: <Organization ID>' -H 'Content-Type: application/json' 
-d '{"parent_id": 1c6ca187-e61f-4301-8dcb-0e9749e89eef, "name": "Sao Paulo", "description": "Brazil city"}'


  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "level_id": "3cb85fcc-c00c-4c83-ae89-cd2568531125",
  "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
  "name": "Sao Paulo",
  "description": "Brazil city division"

A division element (for example, Country = Brazil) can have a parent/child relationship with a division at a higher level. For example, Sao Paulo is not only a division element for the city level, it could also have Brazil as its parent division at the country level.


Parent/child relationships between divisions are represented by the red arrows.

Binding a program to a division

You bind the specific program IDs for a division and its children using the Update division endpoint. A division can be bound to one program set (the group of programs that are available to a division), so a subsequent call to this endpoint for the same division creates a new program set that effectively replaces the previous one.

Path parameters

hierarchyIdHierarchy IDStringYes
levelIdLevel IDStringYes
divisionIdDivision IDStringYes

Body parameters

program_idsProgram IDsArray of strings


curl --request POST \
     --url \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '


    204 no content

Other hierarchy endpoints

  • Get level divisions – Get level divisions. For example, the divisions for a country level could be Brazil and Japan.