An offer is the offer letter issued on an application. Your recruiters issue it in the app when they move a candidate to Offered with an offer template; Jadiroon renders the letter as a PDF and sends it to the candidate. Use these endpoints to read offers and download the letters into your HR or ERP system. Offers are read-only in the API.
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/offers | List offers (cursor pagination, updatedSince) | recruitment.view |
GET /api/v1/offers/{id} | Get one offer | recruitment.view |
GET /api/v1/offers/{id}/file | Download the offer letter | recruitment.view and recruitment.candidate.contact |
An offer has the same id as its application. An application without an issued offer, or an id from another workspace, returns 404 not_found.
The offer object
| Field | Type | Notes |
|---|---|---|
id, applicationId | string | The application's id. |
openingId, positionId, personId | string | The opening, position and candidate of the application. |
templateId | string or null | The offer template the letter was rendered from. |
issuedAt | ISO 8601 or null | When the letter was issued. |
hasFile | boolean | The letter file is ready; it is rendered just after the move to Offered. |
externalRefs | array | [{ system, externalId }] links to your systems. |
createdAt, updatedAt | ISO 8601 |
Downloading the letter
GET /api/v1/offers/{id}/file streams the file itself, with Content-Disposition: attachment; filename="offer-<id>.pdf". The storage location is never returned. The response is 404 not_found while the letter is still being rendered.
The letter can print the candidate's national ID / Iqama number, so the download needs recruitment.candidate.contact as well as recruitment.view. A key without it gets 403 forbidden with details.reason candidate_contact_required and details.required ["recruitment.candidate.contact"]. hasFile on the offer object is shown to every key that can read offers. Deployment-level keys can download letters.
curl -o offer.pdf https://jadiroon.com/api/v1/offers/cmvm6j7ek000qkncrqplvazrv/file \
-H "Authorization: Bearer $JADIROON_KEY"
Webhook events
Offers have no events of their own in v1. Watch application.stage_changed with the application's stage OFFERED and hasOffer true, then read the offer.
Errors
| Status and code | Meaning |
|---|---|
403 forbidden | The key lacks recruitment.view, or candidate_contact_required on the letter download. |
404 not_found | No offer with that id in your workspace, or no letter file yet. |
Example
curl https://jadiroon.com/api/v1/offers/cmvm6j7ek000qkncrqplvazrv \
-H "Authorization: Bearer $JADIROON_KEY"
{
"id": "cmvm6j7ek000qkncrqplvazrv",
"applicationId": "cmvm6j7ek000qkncrqplvazrv",
"openingId": "cmvm6inad0002kncr1pytpf2x",
"positionId": "cmvikf8270086knoq85hjhu3u",
"personId": "cmvm6it4n000dkncrplgeongm",
"templateId": "cmvk1o2t50003kn9xq4w6e8rt",
"issuedAt": "2026-10-24T09:12:34.999Z",
"hasFile": true,
"externalRefs": [],
"createdAt": "2026-10-24T09:12:34.999Z",
"updatedAt": "2026-10-24T09:12:35.017Z"
}