Setting up a hierarchy to match your organization

Creating a hierarchy with levels

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

ParameterDescriptionTypeRequired
levelsAttributes of the levelArray of objects:

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

Request
A typical call might look like this:

// Create a level
 curl -X POST https://api-sandbox.pismolabs.io/corporate/hierarchies 
 -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"}]}'

Response

{"id":"c2695296-6c3b-471c-b710-3f01fc2275c4","levels":
[{"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

ParameterDescriptionTypeRequired
hierarchyIdHierarchy IDStringYes
levelIdLevel IDStringYes

Body Parameters

ParameterDescriptionTypeRequired
idDivision level IDString
parent_idParent level division IDString
nameDivision nameStringYes
descriptionDivision descriptionString

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

// Create a division
curl -X POST 'https://api-sandbox.pismolabs.io/corporate/hierarchies/<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"}'

Response

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

1878

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

ParameterDescriptionTypeRequired
hierarchyIdHierarchy IDStringYes
levelIdLevel IDStringYes
divisionIdDivision IDStringYes

Body parameters

ParameterDescriptionTypeRequired
program_idsProgram IDsArray of strings

Request

curl --request POST \
     --url https://api-sandbox.pismolabs.io/corporate/corporate/hierarchies/hierarchyId/levels/levelId/divisions/divisionId/program-set \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '

Response

{
    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.