Setting up a hierarchy to match your organization
Creating a hierarchy with levels
You can set up levels using the Create hierarchy levels endpoint.
| Parameter | Description | Type | Required |
|---|---|---|---|
| levels | Attributes of the level | Array of objects:
| 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
| Parameter | Description | Type | Required |
|---|---|---|---|
| hierarchyId | Hierarchy ID | String | Yes |
| levelId | Level ID | String | Yes |
Body Parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
| id | Division level ID | String | |
| parent_id | Parent level division ID | String | |
| name | Division name | String | Yes |
| description | Division description | String |
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.
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
| Parameter | Description | Type | Required |
|---|---|---|---|
| hierarchyId | Hierarchy ID | String | Yes |
| levelId | Level ID | String | Yes |
| divisionId | Division ID | String | Yes |
Body parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
| program_ids | Program IDs | Array 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.
Updated almost 2 years ago