Division erstellen

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

Auf einen Blick

Eigenschaft	Verhalten
Authentifizierung	Erforderlich in `X-API-Key`
Tenant-Kontext	Bedingt; aus Parent oder Scope nur bei Eindeutigkeit ableiten
Dry Run	Unterstützt mit `dryRun=true`
Request-Body	`application/json`; geschlossenes Schema; maximal dokumentierte Body-Größe 5 MiB
Response	JSON
Primärer Erfolg	`200`, `201`
Side Effects	Erstellt eine Division; Dry Run unterdrückt die Speicherung
Retry-Empfehlung	Nicht blind wiederholen; zuerst die Geschwisterebene durchsuchen und abgleichen

Betriebsverhalten

Erstellt eine Division. X-Tenant-ID wählt den Tenant aus. Fehlt der Header, ermittelt die API den Tenant aus parentId oder dem Scope des API-Keys; bei Mehrdeutigkeit schlägt die Anfrage fehl. Mit dryRun=true gibt die API die projizierte Division zurück, ohne sie zu speichern.

parentId: null erstellt eine Root-Division.
Der Name muss unter Geschwistern eindeutig sein.
Eine Dry-Run-Vorschau-ID darf später nicht verwendet werden.

Häufige Fehler

Fehlercode	Bedeutung
`VALIDATION_ERROR`	Schema- oder fachliche Validierung ist fehlgeschlagen
`INVALID_REQUEST_ID`	`X-Request-ID` ist keine UUID v4 oder v7
`INVALID_API_KEY`	API-Key fehlt, ist ungültig, gelöscht oder inaktiv
`TENANT_NOT_IN_SCOPE`	Ausgewählter Tenant liegt außerhalb des API-Key-Scopes
`NOT_FOUND`	Ressource fehlt oder ist im Scope nicht zugänglich
`NOT_ACCEPTABLE`	Angeforderter Response-Medientyp ist nicht verfügbar
`DIVISION_CYCLE`	Parent-Änderung würde einen Hierarchiezyklus erzeugen
`DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL`	Geschwistername wird bereits verwendet
`PAYLOAD_TOO_LARGE`	Vollständiger Request überschreitet das dokumentierte Limit
`UNSUPPORTED_MEDIA_TYPE`	Request-Medientyp wird nicht akzeptiert
`TENANT_CONTEXT_AMBIGUOUS`	Es kann kein eindeutiger Tenant ermittelt werden
`INVALID_REFERENCE`	Referenzierte Ressource fehlt oder ist nicht verfügbar

Die Response-Liste der Operation und die Seite Fehlerbehandlung sind für die vollständige Behandlung maßgeblich.

Vor der Implementierung

Erzeugen und protokollieren Sie für den Versuch eine neue X-Request-ID.
Behandeln Sie jeden dokumentierten Response-Status.
Protokollieren Sie weder X-API-Key noch unnötige personenbezogene Daten.
Gleichen Sie die aktuelle Geschwisterebene ab, bevor Sie einen mehrdeutigen Create-Vorgang wiederholen.

Zugehöriger Integrationsleitfaden

Prüfen Sie den vollständigen Prozess sowie Status-, Retry- und Betriebsmuster für diese Operation.

Autorisierungen

X-API-Key

string

header

erforderlich

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.

Header

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

Abfrageparameter

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.

Beispiel:

true

Body

application/json

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

Fields accepted when creating a division.

name

string

erforderlich

Division name. It must be unique among siblings.

Minimum string length: 1

Beispiel:

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

Beispiel:

"68920e08eeaea4f2301eecb3"

order

number

inactive

optional

not sent by default

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

Beispiel:

1

costCenter

string

inactive

optional

not sent by default

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

Beispiel:

"CC-SALES"

Antwort

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

Division details.

string

erforderlich

read-only

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

Beispiel:

"68920e08eeaea4f2301eecb3"

tenant

string

erforderlich

read-only

ID of the tenant that owns the division.

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

Beispiel:

"68a000000000000000000010"

name

string

erforderlich

Division name.

Beispiel:

"Sales"

parentId

string | null

erforderlich

nullable

Parent division ID, or null for a root division.

Minimum string length: 1

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

Beispiel:

null

order

number

erforderlich

Display order among sibling divisions.

Beispiel:

1

costCenter

string | null

erforderlich

nullable

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

Minimum string length: 1

Beispiel:

"CC-SALES"

createdAt

string<date-time>

erforderlich

read-only

UTC creation timestamp.

Minimum string length: 1

Pattern: Z$

Beispiel:

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

updatedAt

string<date-time>

erforderlich

read-only

UTC timestamp of the latest update.

Minimum string length: 1

Pattern: Z$

Beispiel:

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

Zuletzt geändert am 27. August 2026

Übersicht

Datenmodelle

Spezifikation

Auf einen Blick

Betriebsverhalten

Häufige Fehler

Vor der Implementierung

Zugehöriger Integrationsleitfaden

Autorisierungen

Header

Abfrageparameter

Body

Antwort

​Auf einen Blick

​Betriebsverhalten

​Häufige Fehler

​Vor der Implementierung

Zugehöriger Integrationsleitfaden

Autorisierungen

Header

Abfrageparameter

Body

Antwort

Auf einen Blick

Betriebsverhalten

Häufige Fehler

Vor der Implementierung