> ## Documentation Index > Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt > Use this file to discover all available pages before exploring further. # List divisions > Lists divisions in the API key's scope. Filter and sort fields: `id`, `tenant`, `name`, `parentId`, `order`, `costCenter`, `createdAt`, `updatedAt`. ## At a glance | Property | Behavior | | --------------- | ------------------------------------------------------------------------ | | Authentication | Required in X-API-Key | | Tenant context | Optional; omit to query all authorized tenants | | Dry run | Not supported | | Request body | None | | Response | JSON | | Primary success | `200` | | Side effects | None beyond reading or downloading the authorized resource | | Retry guidance | Transient read failures are generally safe to retry with bounded backoff | ## Operational behavior Lists divisions in the API key's scope. Filter and sort fields: `id`, `tenant`, `name`, `parentId`, `order`, `costCenter`, `createdAt`, `updatedAt`. * Use parentId and order to reconstruct the tenant hierarchy. ## Common errors | Error code | Meaning | | ----------------------------- | ---------------------------------------------- | | `VALIDATION_ERROR` | Schema or business validation failed | | `INVALID_REQUEST_ID` | X-Request-ID is not UUID v4 or v7 | | `UNKNOWN_QUERY_PARAMETER` | Query parameter is not supported | | `INVALID_FILTER_SYNTAX` | Filter expression cannot be parsed | | `UNSUPPORTED_FILTER_FIELD` | Filter field is not supported | | `UNSUPPORTED_FILTER_OPERATOR` | Operator is not supported for the field | | `UNSUPPORTED_SORT_FIELD` | Sort field is not supported | | `INVALID_API_KEY` | Missing, invalid, deleted, or inactive API key | | `TENANT_NOT_IN_SCOPE` | Selected tenant is outside API-key scope | | `NOT_ACCEPTABLE` | Requested response media type is unavailable | | `RATE_LIMIT_EXCEEDED` | API-key rate limit was exceeded | | `INTERNAL_SERVER_ERROR` | Unexpected server failure | The operation response list and [Error handling](/concepts/error-handling) page are authoritative for complete handling. ## Before implementation * Generate and log a new `X-Request-ID` for the attempt. * Handle every documented response status. * Do not log `X-API-Key` or unnecessary personal data. * Reconcile current resource state before replaying an ambiguous write. Review the complete process, state, retry, and operational pattern for this operation. ## OpenAPI ````yaml https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.json GET /divisions openapi: 3.1.0 info: title: JobHandy Public API version: 1.0.0 summary: Production API for HR, order, incident, division, and payroll integrations. description: >- Integrate HR and payroll systems with JobHandy through a versioned REST API. ## Production endpoint All public requests use `https://api.jobhandy.io/v1`. ## Core conventions - Authenticate protected operations with `X-API-Key`. - Use `X-Tenant-ID` where supported to select one tenant within the API-key scope. - Use `X-Request-ID` for end-to-end request correlation. - Validate supported writes with `dryRun=true` before applying them. - Collection endpoints support pagination, sorting, and the documented filter expression language. - Error responses use a stable JSON envelope with a machine-readable error code. Optional query and header parameters are documented but omitted from generated requests by default in the accompanying Mintlify configuration. servers: - url: https://api.jobhandy.io/v1 description: Production security: - apiKeyAuth: [] tags: - name: Employees description: Synchronize employee master data, account state, and division assignments. - name: Orders description: Read employee orders, record HR decisions, and download order documents. - name: Incidents description: Report and maintain employee incidents and upload supported attachments. - name: Divisions description: Maintain organizational divisions, hierarchy, ordering, and cost centers. - name: Payroll export documents description: List payroll export metadata and download generated payroll files. - name: Health description: Check basic public API availability without authentication. paths: /divisions: get: tags: - Divisions summary: List divisions description: >- Lists divisions in the API key's scope. Filter and sort fields: `id`, `tenant`, `name`, `parentId`, `order`, `costCenter`, `createdAt`, `updatedAt`. operationId: listDivisions parameters: - in: query required: false name: page description: One-based page number. When omitted, the server uses `1`. schema: type: integer example: 1 minimum: 1 multipleOf: 1 x-mint: post: - optional - 'server default: 1' - not sent by default x-client-default-state: inactive - in: query required: false name: pageSize description: Number of resources per page. When omitted, the server uses `100`. schema: type: integer example: 100 maximum: 1000 minimum: 1 multipleOf: 1 x-mint: post: - optional - 'server default: 100' - not sent by default x-client-default-state: inactive - in: query required: false name: sort description: >- One endpoint-supported public scalar field. Prefix with `-` for descending order. Multiple fields and whitespace are rejected. Null values sort first in ascending order and last in descending order. schema: type: string x-mint: post: - optional - not sent by default x-client-default-state: inactive examples: ascending: summary: Name ascending value: name descending: summary: Most recently updated first value: '-updatedAt' - in: query required: false name: filter description: >- Expression over endpoint-supported public scalar fields. Operators: =, !=, >, >=, <, <=, IN (...), CONTAINS, STARTS_WITH, ENDS_WITH, IS NULL, IS NOT NULL. AND binds before OR; parentheses override precedence. Whitespace outside quoted values is ignored. String comparisons are case-insensitive. String values may be unquoted, single-quoted, or double-quoted. Values containing whitespace must be enclosed in single or double quotes. An apostrophe may be escaped as \' in either quote style; the escape backslash is not part of the matched value. Nested, object, and array fields are rejected. Examples show decoded filter expressions; URL-encode the query parameter value when constructing a raw URL. schema: type: string x-mint: post: - optional - not sent by default x-client-default-state: inactive examples: rootDivisions: summary: Root divisions value: parentId IS NULL salesName: summary: Division name contains sales value: name CONTAINS "sales" costCenterPrefix: summary: Cost center prefix value: costCenter STARTS_WITH "CC-" - in: query required: false name: createdAtFrom description: >- Inclusive lower bound for `createdAt`. Must be an ISO-8601 UTC timestamp ending in `Z`. schema: type: string example: '2026-01-01T00:00:00.000Z' pattern: Z$ format: date-time x-mint: post: - optional - not sent by default x-client-default-state: inactive - in: query required: false name: createdAtTo description: >- Inclusive upper bound for `createdAt`. Must be an ISO-8601 UTC timestamp ending in `Z`. schema: type: string example: '2026-12-31T23:59:59.999Z' pattern: Z$ format: date-time x-mint: post: - optional - not sent by default x-client-default-state: inactive - name: X-Tenant-ID description: >- Restricts results to one tenant in the API key's scope. Omit the header to query all tenants in scope. In interactive clients, use the `{{tenantId}}` variable when a tenant must be selected. Keep the header disabled when tenant selection is not required. in: header required: false schema: type: string pattern: ^[0-9a-fA-F]{24}$ x-mint: post: - optional - not sent by default x-client-default-state: inactive x-default: '{{tenantId}}' - in: header name: X-Request-ID required: false description: >- Optional request identifier. If supplied, it must be a UUID v4 or v7 and is returned unchanged in every response. If omitted, the API generates one. Invalid values return `400 INVALID_REQUEST_ID`. If your client uses a `{{requestId}}` variable, refresh it with a new UUID version 4 or 7 for every HTTP request attempt. Keep the header disabled to let the API generate the request identifier. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ x-mint: post: - optional - not sent by default x-client-default-state: inactive x-default: '{{requestId}}' responses: '200': content: application/json: schema: $ref: '#/components/schemas/DivisionList' examples: page: summary: Page of divisions value: page: 1 pageSize: 100 totalPages: 1 totalElements: 2 items: - id: 68920e08eeaea4f2301eecb3 tenant: 68a000000000000000000010 name: Sales parentId: null order: 1 costCenter: CC-SALES createdAt: '2026-01-15T10:30:00.000Z' updatedAt: '2026-07-01T08:15:00.000Z' - id: 68920e08eeaea4f2301eecb4 tenant: 68a000000000000000000010 name: Enterprise Sales parentId: 68920e08eeaea4f2301eecb3 order: 2 costCenter: CC-ENT createdAt: '2026-02-01T09:00:00.000Z' updatedAt: '2026-07-10T14:20:00.000Z' description: A page of divisions. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: >- The request cannot be parsed or violates the request contract. value: error: code: VALIDATION_ERROR message: The request contains an invalid value. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 invalidRequestId: summary: X-Request-ID is not UUID v4 or v7 value: error: code: INVALID_REQUEST_ID message: The supplied X-Request-ID is invalid. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 unknownQueryParameter: summary: Unknown query parameter value: error: code: UNKNOWN_QUERY_PARAMETER message: The request contains an unknown query parameter. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 invalidFilterSyntax: summary: Filter cannot be parsed value: error: code: INVALID_FILTER_SYNTAX message: The filter expression is invalid. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 unsupportedFilterField: summary: Filter field is not supported value: error: code: UNSUPPORTED_FILTER_FIELD message: >- The filter uses a field that is not supported by this endpoint. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 unsupportedFilterOperator: summary: Operator is not supported for the field value: error: code: UNSUPPORTED_FILTER_OPERATOR message: The filter uses an unsupported operator. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 unsupportedSortField: summary: Sort field is not supported value: error: code: UNSUPPORTED_SORT_FIELD message: The sort field is not supported by this endpoint. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The request cannot be parsed or violates the request contract. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidApiKey: summary: API key is missing, invalid, or inactive value: error: code: INVALID_API_KEY message: The supplied API key is missing, invalid, or inactive. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The X-API-Key credential is missing, invalid, or inactive. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: tenantNotInScope: summary: Selected tenant is not in the API-key scope value: error: code: TENANT_NOT_IN_SCOPE message: >- The integration does not have access to the selected tenant. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The API key does not grant access to the selected tenant. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '406': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notAcceptable: summary: Accept excludes all success media types value: error: code: NOT_ACCEPTABLE message: >- The endpoint cannot produce a response in a media type accepted by the request. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The requested response media type is not supported. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: >- The request matches the contract, but a value or referenced resource fails validation. value: error: code: VALIDATION_ERROR message: The request contains an invalid value. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: >- The request matches the contract, but a value or referenced resource fails validation. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimitExceeded: summary: API-key request quota exceeded value: error: code: RATE_LIMIT_EXCEEDED message: The API key request rate limit has been exceeded. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The API key request rate limit was exceeded. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string Retry-After: description: >- Seconds to wait before retrying after request-rate admission was rejected. schema: type: integer example: 60 '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalServerError: summary: Unexpected server error value: error: code: INTERNAL_SERVER_ERROR message: The request failed. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: An unexpected server error occurred. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 security: - apiKeyAuth: [] components: schemas: DivisionList: type: object properties: page: type: integer example: 1 description: Current one-based page number. multipleOf: 1 pageSize: type: integer example: 100 description: Maximum number of resources returned per page. multipleOf: 1 totalPages: type: integer example: 1 description: Number of available pages. multipleOf: 1 totalElements: type: integer example: 2 description: Number of resources matching the request. multipleOf: 1 items: type: array items: $ref: '#/components/schemas/Division' description: Divisions on the current page. required: - page - pageSize - totalPages - totalElements - items description: One page of divisions. example: page: 1 pageSize: 100 totalPages: 1 totalElements: 2 items: - id: 68920e08eeaea4f2301eecb3 tenant: 68a000000000000000000010 name: Sales parentId: null order: 1 costCenter: CC-SALES createdAt: '2026-01-15T10:30:00.000Z' updatedAt: '2026-07-01T08:15:00.000Z' - id: 68920e08eeaea4f2301eecb4 tenant: 68a000000000000000000010 name: Enterprise Sales parentId: 68920e08eeaea4f2301eecb3 order: 2 costCenter: CC-ENT createdAt: '2026-02-01T09:00:00.000Z' updatedAt: '2026-07-10T14:20:00.000Z' ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - type: object description: Public error details. description: Machine-readable and human-readable details for the failed request. example: error: code: INVALID_API_KEY message: The supplied API key is missing, invalid, or inactive. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: Error envelope returned by every public API endpoint. required: - error Division: type: object properties: id: type: string example: 68920e08eeaea4f2301eecb3 description: >- Division ID. A create dry run returns a preview ID that cannot be used in later requests. readOnly: true tenant: type: string example: 68a000000000000000000010 description: ID of the tenant that owns the division. pattern: ^[0-9a-fA-F]{24}$ readOnly: true name: type: string example: Sales description: Division name. parentId: example: null description: Parent division ID, or `null` for a root division. type: - string - 'null' minLength: 1 pattern: ^[0-9a-fA-F]{24}$ x-mint: post: - nullable order: type: number example: 1 description: Display order among sibling divisions. costCenter: example: CC-SALES description: Customer-defined cost center, or null when none is assigned. type: - string - 'null' minLength: 1 x-mint: post: - nullable createdAt: type: string example: '2026-01-15T10:30:00.000Z' description: UTC creation timestamp. pattern: Z$ format: date-time readOnly: true minLength: 1 updatedAt: type: string example: '2026-07-01T08:15:00.000Z' description: UTC timestamp of the latest update. pattern: Z$ format: date-time readOnly: true minLength: 1 example: id: 68920e08eeaea4f2301eecb3 tenant: 68a000000000000000000010 name: Sales parentId: null order: 1 costCenter: CC-SALES createdAt: '2026-01-15T10:30:00.000Z' updatedAt: '2026-07-01T08:15:00.000Z' description: Division details. required: - id - tenant - name - parentId - order - costCenter - createdAt - updatedAt ApiError: type: object properties: code: type: string example: INVALID_API_KEY description: >- Machine-readable public error code. Values are stable and case-sensitive. - `INVALID_API_KEY`: The API key is missing, invalid, inactive, or otherwise unusable. - `INVALID_REQUEST_ID`: X-Request-ID is not a valid UUID version 4 or 7. - `NOT_ACCEPTABLE`: The Accept header excludes all success media types produced by the operation. - `UNSUPPORTED_MEDIA_TYPE`: The request Content-Type is not supported by the operation. - `MISSING_ATTACHMENT`: A required multipart attachment field or file is missing. - `PAYLOAD_TOO_LARGE`: The complete request body exceeds the documented 5 MiB limit. - `UNKNOWN_QUERY_PARAMETER`: The request contains a query parameter that the operation does not accept. - `UNSUPPORTED_HEADER`: The request contains a header value or header usage that the public contract does not support. - `NOT_FOUND`: The target resource does not exist or is not visible in the caller scope. - `FILE_NOT_FOUND`: The referenced file is not available. - `BAD_GATEWAY`: A downstream file or integration service failed while processing the request. - `SERVICE_UNAVAILABLE`: The requested service is temporarily unavailable. - `GATEWAY_TIMEOUT`: A downstream operation did not complete before the timeout. - `INTERNAL_SERVER_ERROR`: An unexpected server-side error occurred. - `TENANT_CONTEXT_AMBIGUOUS`: The API cannot infer exactly one tenant from the supplied selectors and API-key scope. - `EMPLOYEE_PLACEMENT_AMBIGUOUS`: The API cannot infer one permitted employee division placement. - `TENANT_NOT_IN_SCOPE`: The selected tenant is not accessible to the API key. - `INVALID_REFERENCE_ID`: A referenced identifier is invalid for the requested operation. - `VALIDATION_ERROR`: The request is malformed or a supplied value fails contract or business validation. - `INVALID_FILTER_SYNTAX`: The filter expression cannot be parsed. - `UNSUPPORTED_FILTER_FIELD`: The filter uses a field that the operation does not expose for filtering. - `UNSUPPORTED_FILTER_OPERATOR`: The filter uses an operator that is not supported for the selected field. - `UNSUPPORTED_SORT_FIELD`: The sort field is not supported by the operation. - `UNSUPPORTED_FIELD`: The request contains a field that is not accepted by the operation. - `INVALID_REFERENCE`: A referenced resource cannot be used in the requested context or scope. - `EMPLOYEE_BLOCKED`: The requested operation cannot continue because the employee account is blocked. - `DIVISION_CYCLE`: The requested parent relationship would create a division hierarchy cycle. - `DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL`: A sibling division already uses the requested name. - `DUPLICATE_RESOURCE`: The request would create or update a resource to a value that must be unique. - `INVALID_STATE_TRANSITION`: The requested action is not permitted from the resource current lifecycle state. - `ORDER_ALREADY_DECIDED`: The order already has an HR review decision and cannot be decided again. - `RATE_LIMIT_EXCEEDED`: The API-key request quota has been exceeded. enum: - INVALID_API_KEY - INVALID_REQUEST_ID - NOT_ACCEPTABLE - UNSUPPORTED_MEDIA_TYPE - MISSING_ATTACHMENT - PAYLOAD_TOO_LARGE - UNKNOWN_QUERY_PARAMETER - UNSUPPORTED_HEADER - NOT_FOUND - FILE_NOT_FOUND - BAD_GATEWAY - SERVICE_UNAVAILABLE - GATEWAY_TIMEOUT - INTERNAL_SERVER_ERROR - TENANT_CONTEXT_AMBIGUOUS - EMPLOYEE_PLACEMENT_AMBIGUOUS - TENANT_NOT_IN_SCOPE - INVALID_REFERENCE_ID - VALIDATION_ERROR - INVALID_FILTER_SYNTAX - UNSUPPORTED_FILTER_FIELD - UNSUPPORTED_FILTER_OPERATOR - UNSUPPORTED_SORT_FIELD - UNSUPPORTED_FIELD - INVALID_REFERENCE - EMPLOYEE_BLOCKED - DIVISION_CYCLE - DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL - DUPLICATE_RESOURCE - INVALID_STATE_TRANSITION - ORDER_ALREADY_DECIDED - RATE_LIMIT_EXCEEDED minLength: 1 message: type: string example: The supplied API key is missing, invalid, or inactive. description: Human-readable error summary. minLength: 1 requestId: type: string example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: >- Request identifier also returned in the X-Request-ID response header. pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ format: uuid minLength: 1 description: Stable public API error details. required: - code - message - requestId example: code: VALIDATION_ERROR message: The request contains an invalid value. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 securitySchemes: apiKeyAuth: type: apiKey name: X-API-Key in: header description: >- JobHandy integration API key. Send the credential in the `X-API-Key` header. Treat the key as a secret and use it only from trusted server-side environments. ````