Suppliers

For HR administrators

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 pathWhat it doesPermission
GET /api/v1/suppliersList suppliers. Filters type, status, updatedSince, externalSystem + externalId; limit, cursorsuppliers.view
GET /api/v1/suppliers/{id}Get one suppliersuppliers.view
GET /api/v1/supplier-contractsList contracts. Filters supplierId, status, updatedSincesuppliers.view
GET /api/v1/supplier-contracts/{id}Get one contractsuppliers.view
GET /api/v1/supplier-contracts/{id}/fileStream the contract PDF (the final counter-signed PDF when it exists)suppliers.view
GET /api/v1/supplier-invoicesList invoices. Filters supplierId, status (for example APPROVED), updatedSincesuppliers.view
GET /api/v1/supplier-invoices/{id}Get one invoicesuppliers.view
GET /api/v1/supplier-invoices/{id}/fileStream the supplier's own tax invoice, if uploadedsuppliers.view
POST /api/v1/supplier-invoices/{id}/mark-paidRecord that an approved invoice was paidsuppliers.payments.record
GET /api/v1/supplier-payment-vouchersList vouchers. Filters supplierId, invoiceId, updatedSince, includeCancelledsuppliers.payments.record
GET /api/v1/supplier-payment-vouchers/{id}Get one voucher, with the full IBANsuppliers.payments.record
GET /api/v1/supplier-payment-vouchers/{id}/fileStream the voucher PDFsuppliers.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

FieldTypeNotes
idstring
typestringHEADHUNTING_AGENCY, UNIVERSITY; TRAINING_CENTER and OTHER are reserved, not used yet.
legalNameAr, legalNameEnstring, string or null
legalFormstringINDIVIDUAL, ESTABLISHMENT, COMPANY.
crNumber, vatNumberstring or null
ibanMaskedstring or nullSA•• •••• •••• •••• •• plus the last two digits. The full IBAN is never on this resource.
bankName, contactName, email, phone, citystring or null
statusstringPENDING, VERIFIED, SUSPENDED, REJECTED.
verifiedAtISO 8601 or null
externalRefsarray[{ system, externalId }]
createdAt, updatedAtISO 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

FieldTypeNotes
id, supplierId, contractIdstring
directionstringPAYABLE
originstringHIRE, MANUAL or CLAIM.
numberstring or nullINV-2026-0001, set when issued.
statusstringDRAFT, ISSUED, APPROVED, PAID, CANCELLED.
applicationIdstring or nullThe hire's application (pipeline entry).
positionTitleAr, positionTitleEn, candidateNamestringSnapshots taken at creation.
feeModel, feePercent, feeFixedAmountSnapshot of the contract fee.
baseAnnualSalary, baseSourcedecimal string, stringnull without structure.functional.salary, in reads and in webhooks. baseSource is PAY_GRADE, POSITION, JD_MIN, MANUAL or MISSING.
amount, vatRate, vatAmount, totaldecimal stringsAmounts in currency (SAR).
dueDate, issuedAt, approvedAt, paidAt, cancelledAtISO 8601 or null
paymentReferencestring or null
supplierInvoiceNumber, hasSupplierInvoiceFilestring or null, booleanThe supplier's own tax invoice.
createdAt, updatedAtISO 8601

Poll GET /api/v1/supplier-invoices?status=APPROVED&updatedSince=… to find invoices ready to pay.

The voucher object

FieldTypeNotes
id, invoiceId, supplierId, numberstringnumber is PV-2026-0001.
amount, currencydecimal string, stringThe invoice total.
ibanstringThe full IBAN, as snapshotted at approval. This is the only place it leaves Jadiroon, and it needs suppliers.payments.record.
ibanLast4, bankName, beneficiaryNamestring
hasFileboolean
invoiceStatusstringThe status of the invoice. CANCELLED means the voucher is void.
createdAtISO 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 paymentReference on an invoice that is already PAID is a no-op that returns 200 with the invoice.
  • 409 conflict with details.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 not APPROVED.

Events

Webhook events for this resource group:

EventWhenObject
supplier.verifiedA supplier is verified or reinstated.supplier
supplier_contract.signedThe workspace counter-signs, so the contract is active.contract
application.supplier_submittedA supplier submitted a candidate (not a duplicate).application
supplier_invoice.issuedAn invoice is issued.invoice
supplier_invoice.approvedAn invoice is approved and its voucher generated.invoice
supplier_invoice.paidAn 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.