Create a division

curl --request POST \
  --url https://api.jobhandy.io/v1/divisions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "Sales"
}
'

{
  "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"
}

POST

https://api.jobhandy.io/v1

divisions

curl --request POST \
  --url https://api.jobhandy.io/v1/divisions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "Sales"
}
'

{
  "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"
}

At a glance

Property	Behavior
Authentication	Required in X-API-Key
Tenant context	Conditional; infer from parent or scope only when unambiguous
Dry run	Supported with dryRun=true
Request body	application/json; closed schema; maximum documented body 5 MiB
Response	JSON
Primary success	`200`, `201`
Side effects	Creates a division; dry run suppresses persistence
Retry guidance	Do not retry blindly; search the sibling level and reconcile first

Operational behavior

Creates a division. X-Tenant-ID selects the tenant. If omitted, the API infers the tenant from parentId or the API key’s scope; the request fails if this is ambiguous. With dryRun=true, the API returns the projected division without saving it.

parentId null creates a root division.
Name must be unique among siblings.
A dry-run preview ID cannot be used later.

Common errors

Error code	Meaning
`VALIDATION_ERROR`	Schema or business validation failed
`INVALID_REQUEST_ID`	X-Request-ID is not UUID v4 or v7
`INVALID_API_KEY`	Missing, invalid, deleted, or inactive API key
`TENANT_NOT_IN_SCOPE`	Selected tenant is outside API-key scope
`NOT_FOUND`	Resource is absent or not accessible in scope
`NOT_ACCEPTABLE`	Requested response media type is unavailable
`DIVISION_CYCLE`	Parent update would create a hierarchy cycle
`DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL`	Sibling name is already used
`PAYLOAD_TOO_LARGE`	Complete request exceeds the documented limit
`UNSUPPORTED_MEDIA_TYPE`	Request media type is not accepted
`TENANT_CONTEXT_AMBIGUOUS`	One tenant cannot be resolved
`INVALID_REFERENCE`	Referenced resource is missing or unavailable

The operation response list and 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.

Related integration guidance

Review the complete process, state, retry, and operational pattern for this operation.

Authorizations

X-API-Key

string

header

required

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.

Headers

X-Tenant-ID

string

inactive

optional

not sent by default

Tenant in which to create the resource. If omitted, the API infers the tenant as described for this operation. In interactive clients, use the {{tenantId}} variable when a tenant must be selected. Keep the header disabled when tenant selection is not required.

Pattern: ^[0-9a-fA-F]{24}$

X-Request-ID

string<uuid>

inactive

optional

not sent by default

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.

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}$

Query Parameters

dryRun

boolean

inactive

optional

server default: false

not sent by default

When true, the API validates the request without applying the change. The operation's responses specify the returned representation. When omitted, the server uses false.

Example:

true

Body

application/json

The JSON request body must not exceed 5,242,880 bytes.

Fields accepted when creating a division.

name

string

required

Division name. It must be unique among siblings.

Minimum string length: 1

Example:

"Sales"

parentId

string | null

inactive

nullable

optional

not sent by default

Parent division ID. Use null or omit the field to create a root division.

Pattern: ^[0-9a-fA-F]{24}$

Example:

"68920e08eeaea4f2301eecb3"

order

number

inactive

optional

not sent by default

Display order among sibling divisions. Defaults after the last sibling.

Example:

1

costCenter

string

inactive

optional

not sent by default

Optional customer-defined cost center. Omit the field when no cost center is assigned.

Example:

"CC-SALES"

Response

Dry-run validation succeeded. Returns the division that would be created; it is not stored.

Division details.

string

required

read-only

Division ID. A create dry run returns a preview ID that cannot be used in later requests.

Example:

"68920e08eeaea4f2301eecb3"

tenant

string

required

read-only

ID of the tenant that owns the division.

Pattern: ^[0-9a-fA-F]{24}$

Example:

"68a000000000000000000010"

name

string

required

Division name.

Example:

"Sales"

parentId

string | null

required

nullable

Parent division ID, or null for a root division.

Minimum string length: 1

Pattern: ^[0-9a-fA-F]{24}$

Example:

null

order

number

required

Display order among sibling divisions.

Example:

1

costCenter

string | null

required

nullable

Customer-defined cost center, or null when none is assigned.

Minimum string length: 1

Example:

"CC-SALES"

createdAt

string<date-time>

required

read-only

UTC creation timestamp.

Minimum string length: 1

Pattern: Z$

Example:

"2026-01-15T10:30:00.000Z"

updatedAt

string<date-time>

required

read-only

UTC timestamp of the latest update.

Minimum string length: 1

Pattern: Z$

Example:

"2026-07-01T08:15:00.000Z"

Last modified on August 27, 2026

Overview

Data Models

Specification

At a glance

Operational behavior

Common errors

Before implementation

Related integration guidance

Authorizations

Headers

Query Parameters

Body

Response

​At a glance

​Operational behavior

​Common errors

​Before implementation

Related integration guidance

Authorizations

Headers

Query Parameters

Body

Response

At a glance

Operational behavior

Common errors

Before implementation