Jadiroon Docs · دليل جديرون

Pay scales are your workspace's salary scales: each one has grades, and each grade has steps with a base amount. Positions and job descriptions point at a scale and a grade. This endpoint is read-only: scales are managed in the app under Pay scales, and your ERP or payroll system reads them to map its own grades.

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

Endpoints

Method and path	What it does	Permission
`GET /api/v1/pay-scales`	List your pay scales with their grades and steps	`structure.functional.salary`

The list takes limit (1–100, default 50) and cursor and returns { data, nextCursor }. updatedSince (ISO 8601) returns only scales changed since then; adding, editing or removing a grade counts as a change to its scale. Inactive scales are included. ?externalSystem=&externalId= (both together) finds the scale linked to your own id.

The pay scale object

Field	Type	Notes
`id`	string	Jadiroon id (positions show it as `payScaleId`).
`name`	`{ ar, en }`
`kind`	string	`GENERAL`, `HEALTH`, `EDUCATION`, `MILITARY` or `CUSTOM`.
`builtIn`	boolean	true when the scale was copied from a Jadiroon template.
`period`	string	`MONTHLY` or `ANNUAL`: the unit of every amount on the scale.
`currency`	string	For example `SAR`.
`stepModel`	string	`COMPUTED` (base + step × increment) or `EXPLICIT` (amounts set per step).
`active`	boolean	Whether the scale is active in the app.
`grades`	array	Lowest grade first, see below.
`externalRefs`	array	`[{ system, externalId }]`.
`createdAt`, `updatedAt`	ISO 8601

Each grade has:

Field	Type	Notes
`id`	string	Positions show it as `payGradeId`.
`rank`	integer	Order on the scale, 1 = lowest.
`code`	string	The grade's label on the scale, for example `G6`.
`name`	`{ ar, en }`	Optional display name.
`baseMin`, `increment`	integer	Step 1 amount and the raise per step.
`stepCount`	integer	Number of steps.
`steps`	array	`[{ number, baseAmount }]` for every step, with any per-step amounts applied. A position's `payStepNumber` is one of these numbers.

Webhook events

Event	When	`data.object`
`pay_scale.created`	A scale is created or copied from a template	The pay scale
`pay_scale.updated`	A scale or one of its grades changes; `data.changedFields` lists the fields (`grades` for grade changes)	The pay scale
`pay_scale.deleted`	A scale is deleted	`{ id, externalRefs }`
`pay_scale.bulk_changed`	Workspace setup copied the sector's scales	`{ resource: "pay_scale" }`

Editing a grade's amounts or step count also reprices what sits on it: each position whose payStepNumber or baseSalary changes sends position.updated (changedFields: ["payStepNumber", "baseSalary"]), and each job description whose band changes sends job_description.updated (changedFields: ["salaryMin", "salaryMax"]), or <resource>.bulk_changed beyond 50. Renaming a grade or changing only its code or rank reprices nothing and sends only pay_scale.updated. Endpoints without structure.functional.salary don't receive these repricing position.updated and job_description.updated events, since only pay changed.

A deleted scale also appears in GET /api/v1/deleted?resource=pay_scale for 180 days. Only endpoints whose key holds structure.functional.salary receive these events.

Errors

Status and code	Meaning
`403 forbidden`	The key lacks `structure.functional.salary`.
`422 validation_failed`	`limit`, `cursor` or `updatedSince` is invalid.
`422 validation_failed`	Only one of `externalSystem` and `externalId` was sent.

Example

curl https://jadiroon.com/api/v1/pay-scales?limit=1 \
  -H "Authorization: Bearer $JADIROON_KEY"

{
  "data": [
    {
      "id": "cmvk2a7p10002kn5s3d4e5f6a",
      "name": { "ar": "سلم الموظفين العام", "en": "General civil service scale" },
      "kind": "GENERAL",
      "builtIn": true,
      "period": "MONTHLY",
      "currency": "SAR",
      "stepModel": "COMPUTED",
      "active": true,
      "grades": [
        {
          "id": "cmvk2a7q40003kn5s7a8b9c0d",
          "rank": 1,
          "code": "1",
          "name": { "ar": "المرتبة الأولى", "en": "Grade 1" },
          "baseMin": 3000,
          "increment": 135,
          "stepCount": 3,
          "steps": [
            { "number": 1, "baseAmount": 3000 },
            { "number": 2, "baseAmount": 3135 },
            { "number": 3, "baseAmount": 3270 }
          ]
        }
      ],
      "externalRefs": [],
      "createdAt": "2026-10-20T09:12:44.120Z",
      "updatedAt": "2026-10-20T09:12:44.120Z"
    }
  ],
  "nextCursor": null
}