# Create division

Creates a division by level and hierarchy ID. To use the holidays defined in an administrative division, specify its ID in `administrative_division_id` to link your division.

This endpoint generates a [Corporate division created](https://developers.pismo.io/events/docs/corporate-division-creation-2) event.


# 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": {
    "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
      },
      "CreateDivisionRequestV2": {
        "description": "Create division request body",
        "type": "object",
        "properties": {
          "division_code": {
            "$ref": "#/components/schemas/DivisionCode"
          },
          "hierarchy_id": {
            "$ref": "#/components/schemas/HierarchyID"
          },
          "level_id": {
            "$ref": "#/components/schemas/LevelID"
          },
          "name": {
            "$ref": "#/components/schemas/DivisionName"
          },
          "parent_code": {
            "$ref": "#/components/schemas/ParentCode"
          },
          "description": {
            "$ref": "#/components/schemas/DivisionDescription"
          },
          "timezone": {
            "$ref": "#/components/schemas/Timezone"
          },
          "program_ids": {
            "$ref": "#/components/schemas/ProgramIDs"
          },
          "administrative_division_id": {
            "$ref": "#/components/schemas/AdministrativeDivisionID"
          },
          "schema": {
            "$ref": "#/components/schemas/SchemaCreateTransactionBankingAccount"
          }
        },
        "required": [
          "division_code",
          "hierarchy_id",
          "level_id"
        ]
      },
      "CreateDivisionsResponseV2": {
        "description": "Create division response body",
        "type": "object",
        "properties": {
          "division_id": {
            "$ref": "#/components/schemas/DivisionID"
          },
          "division_code": {
            "$ref": "#/components/schemas/DivisionCode"
          },
          "parent_code": {
            "$ref": "#/components/schemas/ParentCode"
          },
          "level_id": {
            "$ref": "#/components/schemas/LevelID"
          },
          "description": {
            "$ref": "#/components/schemas/DivisionDescription"
          },
          "name": {
            "$ref": "#/components/schemas/DivisionName"
          },
          "administrative_division_id": {
            "$ref": "#/components/schemas/AdministrativeDivisionID"
          }
        },
        "required": [
          "division_id",
          "division_code",
          "level_id"
        ]
      },
      "DivisionCode": {
        "type": "string",
        "maxLength": 36,
        "description": "Code used to identify your division within the organization. Division code should only contain letters, numbers, and hyphens.",
        "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
      },
      "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"
      },
      "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"
      },
      "ProductID": {
        "description": "Product ID",
        "type": "integer",
        "format": "int64",
        "example": 1234
      },
      "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
        ]
      },
      "SchemaCreateTransactionBankingAccount": {
        "type": "object",
        "description": "Valid JSON schema as specified in https://json-schema.org/specification.html.\nUsed to validate the JSON of custom fields in the [Create transaction banking account](https://developers.pismo.io/pismo-docs/reference/post-account) process.\nIf this field is not set, the division inherits its schema from the parent division, if it exists.\n",
        "example": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "$id": "https://example.com/product.schema.json",
          "title": "Product",
          "description": "A product from Acme's catalog",
          "type": "object",
          "properties": {
            "product_id": {
              "$ref": "#/components/schemas/ProductID"
            }
          },
          "required": [
            "product_id"
          ]
        }
      },
      "Timezone": {
        "type": "string",
        "description": "Division timezone in timezone database format.<br>\nThis value is used in the calculations for holidays, weekends, and daily balances. If a timezone is not specified, the division inherits the timezone from its parent division. If the parent division also lacks a specified timezone, Pismo defaults to using UTC.\nTo clear this field, specify an empty string.\n",
        "example": "America/New_York"
      }
    },
    "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/v2/divisions": {
      "post": {
        "summary": "Create division",
        "operationId": "post-division-v2",
        "description": "Creates a division by level and hierarchy ID. To use the holidays defined in an administrative division, specify its ID in `administrative_division_id` to link your division.\n\nThis endpoint generates a [Corporate division created](https://developers.pismo.io/events/docs/corporate-division-creation-2) event.\n",
        "parameters": [],
        "tags": [
          "Divisions"
        ],
        "requestBody": {
          "description": "Create level division request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDivisionRequestV2"
              },
              "examples": {
                "New level division": {
                  "value": {
                    "division_code": "my-division",
                    "hierarchy_id": "9bb95e15-c0e6-4c84-b644-350c76a83358",
                    "level_id": "7d574f66-ebd0-4b83-85a1-98ce7569e5c3",
                    "name": "NORAM",
                    "parent_code": "my-parent-division",
                    "description": "North American regional division",
                    "program_ids": [
                      111,
                      222,
                      333
                    ],
                    "administrative_division_id": 13,
                    "timezone": "Pacific Standard Time",
                    "schema": {
                      "$schema": "https://json-schema.org/draft/2020-12/schema",
                      "$id": "https://example.com/product.schema.json",
                      "title": "Product",
                      "description": "A product from Acme's catalog",
                      "type": "object",
                      "properties": {
                        "product_id": {
                          "$ref": "#/components/schemas/ProductID"
                        }
                      },
                      "required": [
                        "product_id"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateDivisionsResponseV2"
                },
                "examples": {
                  "New division": {
                    "value": {
                      "division_id": "6f8a456a-8b1a-4022-a2f8-7612595330b5",
                      "division_code": "my-division",
                      "level_id": "3cb85fcc-c00c-4c83-ae89-cd2568531125",
                      "parent_code": "my-parent-division",
                      "name": "NORAM",
                      "description": "North American regional division"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Invalid JSON payload": {
                    "value": {
                      "code": "WDIV0015",
                      "message": "Invalid JSON payload received: Error unmarshalling request"
                    }
                  },
                  "hierarchy_id is a required field": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "hierarchy_id is a required field"
                    }
                  },
                  "level_id is a required field": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "level_id is a required field"
                    }
                  },
                  "Name is a required field": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "name is a required field"
                    }
                  },
                  "name must be a maximum of 40 characters in length": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "name must be a maximum of 40 characters in length"
                    }
                  },
                  "description must be a maximum of 80 characters in length": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "description must be a maximum of 80 characters in length"
                    }
                  },
                  "timezone is invalid": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "timezone is invalid"
                    }
                  },
                  "schema is invalid": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "schema is invalid"
                    }
                  },
                  "program_ids must contain unique values": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "program_ids must contain unique values"
                    }
                  },
                  "program_ids must contain at maximum 100 items": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "program_ids must contain at maximum 100 items"
                    }
                  },
                  "division_code must be a maximum of 36 characters in length": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "division_code must be a maximum of 36 characters in length"
                    }
                  },
                  "division_code is a required field": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "division_code is a required field"
                    }
                  },
                  "division_code contains character not permitted": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "division_code contains character not permitted"
                    }
                  },
                  "Invalid level": {
                    "value": {
                      "code": "WDIV0005",
                      "message": "Invalid level"
                    }
                  },
                  "Parent level division not found for the given hierarchy": {
                    "value": {
                      "code": "WDIV0007",
                      "message": "Parent level division not found for the given hierarchy"
                    }
                  },
                  "The parent division informed is at a level lower than or equal to the level": {
                    "value": {
                      "code": "WDIV0006",
                      "message": "The parent division informed is at a level lower than or equal to the level"
                    }
                  },
                  "Program with program_id {programId} not found": {
                    "value": {
                      "code": "WDIV0012",
                      "message": "Program with program_id {programId} not found"
                    }
                  },
                  "The administrative division ID is invalid": {
                    "value": {
                      "code": "WDIV0011",
                      "message": "Administrative division is invalid"
                    }
                  },
                  "Invalid hierarchy": {
                    "value": {
                      "code": "WDIV0018",
                      "message": "Invalid hierarchy"
                    }
                  },
                  "Administrative division is misconfigured": {
                    "value": {
                      "code": "WDIV0019",
                      "message": "Administrative division is misconfigured"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Parent division not found": {
                    "value": {
                      "code": "WDIV0017",
                      "message": "Parent division not found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Division code already exists": {
                    "value": {
                      "code": "WDIV0016",
                      "message": "A division with the same code already exists"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer"
          }
        }
      }
    }
  }
}
```