# List division

Lists divisions by hierarchy ID or level ID. Only one of the parameters should be provided with the request. Providing both generates an error.

# OpenAPI definition

```json
{
  "openapi": "3.0.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": "Divisions",
      "description": "Divisions endpoints"
    }
  ],
  "components": {
    "parameters": {
      "HierarchyIdQuery": {
        "name": "hierarchyId",
        "in": "query",
        "required": false,
        "description": "Hierarchy ID generated by the [Create hierarchy](https://developers.pismo.io/pismo-docs/reference/post-hierarchies) endpoint. You only need to provide one of the parameters.",
        "schema": {
          "type": "string"
        },
        "example": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
      },
      "LevelIdQuery": {
        "name": "levelId",
        "in": "query",
        "required": false,
        "description": "Level ID generated by the [Create hierarchy](https://developers.pismo.io/pismo-docs/reference/post-hierarchies) endpoint. You only need to provide one of the parameters.",
        "schema": {
          "type": "string"
        },
        "example": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
      }
    },
    "schemas": {
      "AdministrativeDivisionID": {
        "type": "integer",
        "format": "int64",
        "description": "Administrative division ID. Specifying an administrative division ID in this field links your division to it. This is useful when you want to use the holidays defined in that administrative division.",
        "example": 13
      },
      "Cursor": {
        "type": "string",
        "description": "Cursor pointing to the next page of results",
        "example": "eyJJRCI6IjBjOGVhMTA4LWNhZTYtNDA2Mi1iMmQzLTFhMTZkNmJiNGIyOCIsIk9yZ0lEIjoiMDllYThhMDQtNWY5My0xMWVkLTliNmEtMDI0MmFjMTIwMDAyIn0="
      },
      "DivisionCode2": {
        "type": "string",
        "description": "Division code registered in the [Create division](https://developers.pismo.io/pismo-docs/reference/post-division-v2) endpoint.",
        "maximum": 36,
        "example": "US"
      },
      "DivisionDescription": {
        "type": "string",
        "nullable": true,
        "maxLength": 80,
        "description": "Division description",
        "example": "NY - New York City"
      },
      "DivisionID": {
        "type": "string",
        "description": "Pismo generates the division ID when you use the [Create division](https://developers.pismo.io/pismo-docs/reference/post-division-v2) endpoint.",
        "format": "uuid",
        "example": "6f8a456a-8b1a-4022-a2f8-7612595330b5"
      },
      "DivisionName": {
        "type": "string",
        "description": "Division name",
        "example": "NY",
        "maximum": 40
      },
      "DivisionResponseV2": {
        "type": "object",
        "properties": {
          "division_id": {
            "$ref": "#/components/schemas/DivisionID"
          },
          "division_code": {
            "$ref": "#/components/schemas/DivisionCode2"
          },
          "parent_code": {
            "$ref": "#/components/schemas/ParentCode"
          },
          "name": {
            "$ref": "#/components/schemas/DivisionName"
          },
          "description": {
            "$ref": "#/components/schemas/DivisionDescription"
          },
          "level_id": {
            "$ref": "#/components/schemas/LevelID"
          },
          "hierarchy_id": {
            "$ref": "#/components/schemas/HierarchyID"
          },
          "administrative_division_id": {
            "$ref": "#/components/schemas/AdministrativeDivisionID"
          },
          "program_ids": {
            "$ref": "#/components/schemas/ProgramIDs"
          }
        },
        "required": [
          "division_id"
        ]
      },
      "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"
          }
        }
      },
      "HierarchyID": {
        "type": "string",
        "description": "Hierarchy ID generated by the [Create hierarchy](https://developers.pismo.io/pismo-docs/reference/post-hierarchies) endpoint.",
        "format": "uuid",
        "maxLength": 36,
        "example": "9bb95e15-c0e6-4c84-b644-350c76a83358"
      },
      "LevelID": {
        "type": "string",
        "description": "Level ID generated by the [Create hierarchy](https://developers.pismo.io/pismo-docs/reference/post-hierarchies) endpoint.",
        "format": "uuid",
        "maximum": 36,
        "example": "9bb95e15-c0e6-4c84-b644-350c76a83358"
      },
      "ListDivisionsResponseV2": {
        "title": "ListDivisionsResponse",
        "type": "object",
        "properties": {
          "divisions": {
            "type": "array",
            "description": "List of divisions",
            "items": {
              "$ref": "#/components/schemas/DivisionResponseV2"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "MaxItemsPerPage": {
        "type": "integer",
        "format": "int32",
        "description": "Maximum number of items per page",
        "example": 10
      },
      "Pagination": {
        "type": "object",
        "description": "Data related to list pagination using a cursor.",
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/MaxItemsPerPage"
          },
          "cursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "ParentCode": {
        "type": "string",
        "description": "Division code that can be set as the parent of the division being created. The parent must be at a level with a lower index than the division being created. It must comply with the rule `^[a-zA-Z0-9-]+$`.",
        "pattern": "^[a-zA-Z0-9-]+$",
        "example": "my-parent-division"
      },
      "ProgramIDs": {
        "type": "array",
        "maximum": 100,
        "description": "List of allowed program IDs. The programs must belong to the organization.\nThis list is used for validation during the [Create transaction banking account](https://developers.pismo.io/pismo-docs/reference/post-account) process.\nYou can retrieve the organization programs using the [List programs](https://developers.pismo.io/pismo-docs/reference/programs-1) endpoint.\nIf no program IDs are specified, this division inherits the `program_ids` list from the parent division, if it exists.\n",
        "items": {
          "type": "integer",
          "format": "int32",
          "example": 1
        },
        "example": [
          1,
          2,
          3
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/corporate/v2/divisions": {
      "get": {
        "summary": "List division",
        "description": "Lists divisions by hierarchy ID or level ID. Only one of the parameters should be provided with the request. Providing both generates an error.",
        "operationId": "list-division-v2",
        "parameters": [
          {
            "$ref": "#/components/parameters/HierarchyIdQuery"
          },
          {
            "$ref": "#/components/parameters/LevelIdQuery"
          }
        ],
        "tags": [
          "Divisions"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListDivisionsResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Only hierarchy ID or level ID must be provided but not both": {
                    "value": {
                      "code": "WDIV0001",
                      "message": "Only hierarchy ID or level ID must be provided but not both"
                    }
                  },
                  "hierarchyId or levelId params must be provided": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "hierarchyId or levelId params must be provided"
                    }
                  },
                  "invalid cursor": {
                    "value": {
                      "code": "WCMN0004",
                      "message": "Invalid cursor"
                    }
                  },
                  "limit exceeded maximum value": {
                    "value": {
                      "code": "WCMN0006",
                      "message": "Limit must be less than or equal to 100"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```