Setting up a hierarchy to match your organization [Beta]

Every large bank has its own way of structuring its business. Taking a global bank for example, there is usually a corporate headquarters, followed by global regions, which are broken down into countries, within which there are states, and then cities where the branches are located.

To support a variety of complex organizational structures, Pismo's Corporate Banking solution extends the core platform by introducing a flexible, generic hierarchy that can accommodate any type of structure you need. A hierarchy is created under a single org and is divided into levels. Levels are categories, such as Country or City. Each level contains divisions. For example, the City level might contain the divisions São Paulo, Rio de Janeiro, etc. So level is the primary element and may contain one, or more divisions. Typically, levels are organized by geography. For example, beneath the Headquarters level, there might be levels for region > country > city > branch. For example:

Level

Description

Level 1: Region

Divisions in level 1: North America, Latin America, EMEA

Level 2: Country

Divisions in level 2: Brazil, Argentina

Level 3: City

Divisions in level 3: São Paulo, Rio de Janeiro, Buenos Ayres, Bariloche, etc.
São Paulo and Rio are child divisions of Brazil. Buenos Aires and Bariloche are child divisions of Argentina.

The hierarchy as a whole has a unique ID, as does each level and division. These IDs are used when creating account families. Each level and division has an index (0, 1, 2, ...), with 0 representing the Headquarters level, and a description.

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:

  • 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":"Central","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.Parent/child relationships between divisions are represented by the red arrows.

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


Did this page help you?