--- updatedAt: 2026-04-20T19:56:08.000Z --- Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. # Create hierarchy Creates a hierarchy. This can be used generically, but it's typically used to create business hierarchies along territorial lines: headquarters > countries > regions > branches, and so on. This endpoint generates a [Corporate hierarchy created](https://developers.pismo.io/events/docs/corporate-hierarchy-creation-1) event. See the [Data and reporting](doc:data-reporting-overview) guide for more information on events and setting up event notifications. For more information on hierarchies, see [Hierarchy](doc:hierarchies-2). # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Banking - Transaction banking", "version": "0.9.0", "description": "Transaction banking API", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io", "description": "Sandbox API server for testing" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Hierarchies", "description": "Hierarchy-related endpoints" } ], "components": { "schemas": { "CreateHierarchiesRequest": { "description": "Create hierarchy payload request object", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/HierarchyName" }, "levels": { "type": "array", "description": "Levels and their descriptions and indexes. (Indexes must be sequential.)", "maxItems": 10, "items": { "type": "object", "properties": { "index": { "$ref": "#/components/schemas/HierarchyLevelIndex" }, "name": { "$ref": "#/components/schemas/HierarchyLevelName" }, "description": { "$ref": "#/components/schemas/HierarchyLevelDescription" } }, "required": [ "index" ] } } }, "required": [ "name", "levels" ], "example": { "name": "string", "levels": [ { "name": "string", "index": 0, "description": "string" } ] } }, "CreateHierarchiesResponse": { "description": "Create hierarchy response object", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/HierarchyIdGeneratedInternally" }, "levels": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/LevelIdGeneratedInternally" }, "index": { "$ref": "#/components/schemas/HierarchyLevelIndex" }, "name": { "$ref": "#/components/schemas/HierarchyLevelName" }, "description": { "$ref": "#/components/schemas/HierarchyLevelDescription" } }, "required": [ "id", "index", "name" ] } }, "name": { "type": "string", "description": "Hierarchy One" } }, "required": [ "id", "levels" ] }, "ErrorCode": { "description": "Error code\n`minLength: 1`\n`maxLength: 12`\n", "type": "string", "minLength": 1, "maxLength": 12, "example": "WPMT0017" }, "ErrorMessage": { "description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n", "type": "string", "minLength": 1, "maxLength": 1000, "example": "Invalid JSON payload received: Error unmarshalling request" }, "ErrorResponse": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "$ref": "#/components/schemas/ErrorMessage" } } }, "HierarchyIdGeneratedInternally": { "type": "string", "description": "Hierarchy ID generated internally", "format": "uuid" }, "HierarchyLevelDescription": { "type": "string", "description": "Hierarchy level description", "maxLength": 80 }, "HierarchyLevelIndex": { "type": "integer", "format": "int32", "description": "Hierarchy level index", "minimum": 0, "maximum": 9, "example": 2 }, "HierarchyLevelName": { "type": "string", "description": "Hierarchy level name", "maxLength": 40 }, "HierarchyName": { "type": "string", "description": "Hierarchy name", "maxLength": 40 }, "LevelIdGeneratedInternally": { "type": "string", "description": "Level ID generated internally" } }, "responses": { "401Unauthorized": { "description": "Access token is missing or invalid" }, "403Forbidden": { "description": "The request has been lost" }, "500InternalServer": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Generic internal error": { "value": { "code": "ECMN9999", "message": "Internal error" } } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "paths": { "/corporate/v1/hierarchies": { "post": { "summary": "Create hierarchy", "description": "Creates a hierarchy. This can be used generically, but it's typically used to create business hierarchies along territorial lines: headquarters > countries > regions > branches, and so on.\n\nThis endpoint generates a [Corporate hierarchy created](https://developers.pismo.io/events/docs/corporate-hierarchy-creation-1) event. See the [Data and reporting](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview) guide for more information on events and setting up event notifications.\n\nFor more information on hierarchies, see [Hierarchy](https://developers.pismo.io/pismo-docs/docs/hierarchies-2).\n", "operationId": "post-hierarchies", "tags": [ "Hierarchies" ], "requestBody": { "description": "Create hierarchy request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHierarchiesRequest" }, "examples": { "New hierarchy": { "value": { "name": "Hierarchy One", "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" } ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHierarchiesResponse" }, "examples": { "Example hierarchy level structure": { "value": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "Hierarchy One", "levels": [ { "id": "df48f983-c906-4bb3-83c7-ac2e18babb59", "name": "Central", "index": 0, "description": "Root level" }, { "id": "e7685dd9-e2c8-4a05-baf7-c7dd72c0969f", "name": "Region", "index": 1, "description": "Regional level" }, { "id": "0b05d677-602f-4874-92ea-a23471573c67", "name": "Country", "index": 2, "description": "Country level" }, { "id": "3cf5d1cf-e440-4813-ab14-7de22d2418e3", "name": "City", "index": 3, "description": "Main cities level" }, { "id": "22f4f976-11f2-451c-b62c-d4e2e174d90b", "name": "Branch", "index": 4, "description": "Branch level" } ] } } } } } }, "400": { "description": "A Bad Request validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Invalid JSON payload": { "value": { "code": "WHIE0001", "message": "Invalid JSON payload received: Error unmarshalling request" } }, "name required": { "value": { "code": "WHIE0002", "message": "name is a required field" } }, "name exceed size": { "value": { "code": "WHIE0002", "message": "name must be a maximum of 40 characters in length" } }, "levels required": { "value": { "code": "WHIE0002", "message": "levels is a required field" } }, "levels.index required": { "value": { "code": "WHIE0002", "message": "index is a required field" } }, "levels.index negative": { "value": { "code": "WHIE0002", "message": "index must be 0 or greater" } }, "levels.name exceed size": { "value": { "code": "WHIE0002", "message": "name must be a maximum of 40 characters in length" } }, "levels.description exceed size": { "value": { "code": "WHIE0002", "message": "description must be a maximum of 80 characters in length" } }, "levels maximum items in a Hierarchy": { "value": { "code": "WHIE0002", "message": "levels must contain at maximum 10 items" } }, "levels different indexes": { "value": { "code": "WHIE0003", "message": "First Level index must be 0" } }, "levels indexes values duplicated": { "value": { "code": "WHIE0004", "message": "Levels must have different index values" } }, "levels indexes values sequential order": { "value": { "code": "WHIE0005", "message": "Levels index values must be in a sequential order" } }, "levels should have at least 1 item": { "value": { "code": "WHIE0007", "message": "levels should have at least 1 item" } } } } } }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "403": { "$ref": "#/components/responses/403Forbidden" }, "500": { "$ref": "#/components/responses/500InternalServer" } }, "parameters": [] } } } } ```