Org units

Org units are the nodes of your Organizational Structure: the entity, sectors, agencies, general administrations, administrations, sections and units, each with one parent. Use these endpoints to keep the tree in Jadiroon in sync with your ERP or HR system.

All endpoints sit under /api/v1 and need an API key (Authorization: Bearer jdr_live_…) created by your Workspace Admin in Settings → Integrations.

Endpoints

structure.org.act includes structure.org.view.

The org unit object

Creating and updating

POST takes name, type and optionally parent, function, headName, headRole, headcount and status (new units are DRAFT unless you send status). Unknown fields are rejected.

parent names the parent unit either by Jadiroon id or by your own id:

{ "parent": { "id": "cmv…" } }
{ "parent": { "externalSystem": "oracle-hcm", "externalId": "ORG-100" } }
{ "parent": null }

null moves the unit to the root. A parent that can't be found in your workspace returns 422 unresolved_reference. Moving a unit under itself or under one of its own descendants returns 422 validation_failed with details.reason self_parent or cycle.

Upsert by external id

PUT /api/v1/org-units/by-external/oracle-hcm/ORG-200 looks up the unit linked to oracle-hcm / ORG-200:

• Linked unit found: the body is applied like a PATCH and the response is 200.
• No linked unit: a unit is created from the body (send at least name.ar and type) and linked to the external id, and the response is 201.

system is up to 64 characters, externalId up to 128. To find a unit by your id without changing it, call GET /api/v1/org-units?externalSystem=oracle-hcm&externalId=ORG-200 (send both parameters; one alone returns 422 validation_failed).

Deleting

DELETE only removes a unit with no child units. Otherwise it returns 409 has_children with details.childCount: move or delete the children first.

When a unit is deleted:

• Positions placed in it stay, but become unplaced (no org unit). Their updatedAt moves, and a position.updated event is sent for each, up to 500 positions; above that, one position.bulk_changed covers the rest.
• Workload tasks of the unit are deleted with it.
• Its external links are removed, and the deletion appears in GET /api/v1/deleted?resource=org_unit for 180 days.

Webhook events

After org_unit.bulk_changed, re-read the list with updatedSince set to the event's occurredAt, and read GET /api/v1/deleted?resource=org_unit&since=… for removed units. A URL import that also creates positions or people sends position.bulk_changed / employee.bulk_changed as well.

Errors

Example

curl -X PUT https://jadiroon.com/api/v1/org-units/by-external/oracle-hcm/ORG-200 \
  -H "Authorization: Bearer $JADIROON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": { "ar": "إدارة الموارد البشرية", "en": "Human Resources" },
    "type": "ADMIN",
    "parent": { "externalSystem": "oracle-hcm", "externalId": "ORG-100" },
    "headcount": 12
  }'

The first call creates and links the unit and answers 201 Created; repeating it updates the same unit and answers 200 OK with the same body shape:

{
  "id": "cmvjmf15k0008kn4q404rqwgw",
  "name": { "ar": "إدارة الموارد البشرية", "en": "Human Resources" },
  "type": "ADMIN",
  "parentId": "cmvjmeq4p0002kn4qq820gqll",
  "function": { "ar": null, "en": null },
  "headName": null,
  "headRole": null,
  "headcount": 12,
  "ssoCode": null,
  "status": "DRAFT",
  "sortOrder": null,
  "externalRefs": [{ "system": "oracle-hcm", "externalId": "ORG-200" }],
  "createdAt": "2026-10-22T14:12:52.761Z",
  "updatedAt": "2026-10-22T14:12:52.761Z"
}