Suppliers are the external headhunting agencies and universities a workspace works with. Use these endpoints to read suppliers, their contracts, their invoices and the payment vouchers into your ERP, and to report an invoice as paid. For how the feature works in the app, see Suppliers.
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/suppliers | List suppliers. Filters type, status, updatedSince, externalSystem + externalId; limit, cursor | suppliers.view |
GET /api/v1/suppliers/{id} | Get one supplier | suppliers.view |
GET /api/v1/supplier-contracts | List contracts. Filters supplierId, status, updatedSince | suppliers.view |
GET /api/v1/supplier-contracts/{id} | Get one contract | suppliers.view |
GET /api/v1/supplier-contracts/{id}/file | Stream the contract PDF (the final counter-signed PDF when it exists) | suppliers.view |
GET /api/v1/supplier-invoices | List invoices. Filters supplierId, status (for example APPROVED), updatedSince | suppliers.view |
GET /api/v1/supplier-invoices/{id} | Get one invoice | suppliers.view |
GET /api/v1/supplier-invoices/{id}/file | Stream the supplier's own tax invoice, if uploaded | suppliers.view |
POST /api/v1/supplier-invoices/{id}/mark-paid | Record that an approved invoice was paid | suppliers.payments.record |
GET /api/v1/supplier-payment-vouchers | List vouchers. Filters supplierId, invoiceId, updatedSince, includeCancelled | suppliers.payments.record |
GET /api/v1/supplier-payment-vouchers/{id} | Get one voucher, with the full IBAN | suppliers.payments.record |
GET /api/v1/supplier-payment-vouchers/{id}/file | Stream the voucher PDF | suppliers.payments.record |
Lists use cursor pagination (limit up to 100). Deployment-level keys can read suppliers, contracts and invoices, but are refused (403) on payment vouchers.
The supplier object
| Field | Type | Notes |
|---|---|---|
id | string | |
type | string | HEADHUNTING_AGENCY, UNIVERSITY; TRAINING_CENTER and OTHER are reserved, not used yet. |
legalNameAr, legalNameEn | string, string or null | |
legalForm | string | INDIVIDUAL, ESTABLISHMENT, COMPANY. |
crNumber, vatNumber | string or null | |
ibanMasked | string or null | SA•• •••• •••• •••• •• plus the last two digits. The full IBAN is never on this resource. |
bankName, contactName, email, phone, city | string or null | |
status | string | PENDING, VERIFIED, SUSPENDED, REJECTED. |
verifiedAt | ISO 8601 or null | |
externalRefs | array | [{ system, externalId }] |
createdAt, updatedAt | ISO 8601 |
The contract object
id, supplierId, direction (PAYABLE; RECEIVABLE is reserved, not used yet), title, feeModel (PERCENT_OF_ANNUAL_SALARY, FIXED_AMOUNT or null for a no-fee agreement; PER_SUBMISSION and SUBSCRIPTION are reserved, not used yet), feePercent, feeFixedAmount (decimal strings or null), currency, vatRate, paymentTermsDays, startDate, endDate, ownershipWindowDays, scope (ALL_OPEN or SELECTED), positionIds, status (DRAFT, SENT, SIGNED, EXPIRED, TERMINATED), sentAt, terminatedAt, hasFile, createdAt, updatedAt, and a signature object: signerName, signedAt, countersignedAt, pdfSha256, finalPdfSha256. The signer's IP address and user agent are not exposed.
The invoice object
| Field | Type | Notes |
|---|---|---|
id, supplierId, contractId | string | |
direction | string | PAYABLE |
origin | string | HIRE, MANUAL or CLAIM. |
number | string or null | INV-2026-0001, set when issued. |
status | string | DRAFT, ISSUED, APPROVED, PAID, CANCELLED. |
applicationId | string or null | The hire's application (pipeline entry). |
positionTitleAr, positionTitleEn, candidateName | string | Snapshots taken at creation. |
feeModel, feePercent, feeFixedAmount | Snapshot of the contract fee. | |
baseAnnualSalary, baseSource | decimal string, string | null without structure.functional.salary, in reads and in webhooks. baseSource is PAY_GRADE, POSITION, JD_MIN, MANUAL or MISSING. |
amount, vatRate, vatAmount, total | decimal strings | Amounts in currency (SAR). |
dueDate, issuedAt, approvedAt, paidAt, cancelledAt | ISO 8601 or null | |
paymentReference | string or null | |
supplierInvoiceNumber, hasSupplierInvoiceFile | string or null, boolean | The supplier's own tax invoice. |
createdAt, updatedAt | ISO 8601 |
Poll GET /api/v1/supplier-invoices?status=APPROVED&updatedSince=… to find invoices ready to pay.
The voucher object
| Field | Type | Notes |
|---|---|---|
id, invoiceId, supplierId, number | string | number is PV-2026-0001. |
amount, currency | decimal string, string | The invoice total. |
iban | string | The full IBAN, as snapshotted at approval. This is the only place it leaves Jadiroon, and it needs suppliers.payments.record. |
ibanLast4, bankName, beneficiaryName | string | |
hasFile | boolean | |
invoiceStatus | string | The status of the invoice. CANCELLED means the voucher is void. |
createdAt | ISO 8601 |
Cancelled invoices and void vouchers
A voucher becomes void when its invoice is cancelled. Vouchers of cancelled invoices are excluded from the list by default; send includeCancelled=true to include them, and read invoiceStatus. To keep your ERP in sync, watch invoice status: GET /api/v1/supplier-invoices?updatedSince=… shows CANCELLED, and do not pay a voucher whose invoice is cancelled.
Mark an invoice paid
POST /api/v1/supplier-invoices/{id}/mark-paid needs suppliers.payments.record. Send an optional Idempotency-Key header and a strict body:
{ "paymentReference": "BANK-2026-04411", "paidAt": "2026-11-20" }
paymentReference is 1 to 200 characters; paidAt is a date (YYYY-MM-DD) and cannot be later than today (Riyadh time). Unknown fields are rejected. The response is the updated invoice.
- The invoice must be
APPROVED. - Repeating the same
paymentReferenceon an invoice that is alreadyPAIDis a no-op that returns200with the invoice. 409 conflictwithdetails.reason:supplier_not_verified: the supplier is not Verified (for example suspended or sent back to Pending after a bank change);invalid_status: the invoice is notAPPROVED.
Events
Webhook events for this resource group:
| Event | When | Object |
|---|---|---|
supplier.verified | A supplier is verified or reinstated. | supplier |
supplier_contract.signed | The workspace counter-signs, so the contract is active. | contract |
application.supplier_submitted | A supplier submitted a candidate (not a duplicate). | application |
supplier_invoice.issued | An invoice is issued. | invoice |
supplier_invoice.approved | An invoice is approved and its voucher generated. | invoice |
supplier_invoice.paid | An invoice is marked paid. | invoice |
Invoice events carry the invoice with baseAnnualSalary and baseSource set to null for endpoints whose key lacks structure.functional.salary. Vouchers have no events. Other supplier changes (suspending, rejecting, drafts, cancellation) are in the audit feed but send no resource event. See the event catalog.
Positions
DELETE /api/v1/positions/{id} returns 409 conflict with details.reason has_supplier_submissions when a supplier has submitted a candidate to the position. See Positions.
Errors
The standard conventions apply. A key without the needed permission gets 403 forbidden; an id from another workspace gets 404 not_found.