REST API Reference

Full reference: the OpenAPI 3.1 document at packages/plugin-sdk/openapi/dentolize-v1.json (regenerate with yarn workspace @dentolize/server openapi:generate). Render it with any OpenAPI viewer; the published docs site uses a Scalar static build.

Conventions

• Base URL: https://<host>/api/v1; auth via Authorization: Bearer dtz_….
• Detail/write responses wrap the resource: { "data": { … } }. The SDK unwraps them.
• List responses: { "data": [...], "hasMore": bool, "nextCursor": "…" }; page with ?cursor=&limit= (limit ≤ 100, default 25).
• Errors: { "error": { "code", "message", "requestId", "details?" } }. Quote requestId (also in the X-Request-Id header) in support requests.
• POST requires an Idempotency-Key header (≤255 chars). Replays within 24h return the stored response with Idempotent-Replay: true; concurrent duplicates get 409 idempotency_conflict.
• Financial lists (/invoices, /payments, /quotations, /claims, /online-payments, /einvoice-submissions, /expenses, /incomes, /transactions) require a from/to range of at most 366 days.
• Core list endpoints accept ?updatedAfter=<ISO date-time> for delta syncs (records updated strictly after that instant).
• Responses carry Dentolize-Version (current 2026-07).

Resources

Bulk exports (POST /exports)

For initial sync/backfill instead of hammering paginated lists. Body: { resource, updatedAfter? } with resource one of patients | appointments | invoices | payments | treatments. Requires the read scope of the exported resource; serialized rows apply the same PII tiers as the list routes (e.g. patients without patients:read.pii export masked). Capped at 50,000 rows (413 export_too_large) — window larger datasets with updatedAfter. v1 runs the export inline and responds when the file is ready; poll GET /exports/{id} until status: "completed", then download the presigned NDJSON url (24h validity). The SDK wraps the poll: client.exports.waitFor(exportId, { intervalMs, timeoutMs }).

Events reconciliation (GET /events)

After webhook downtime, list the domain events you missed instead of re-syncing every resource — each row carries the same thin payload the webhook envelope would have delivered. Scoped to your installation's company, the token's mode, and the concrete event types granted at install time; ?type= filters to a single granted type (400 invalid_event_type for unknown, 403 event_not_granted for ungranted). Requires webhooks:manage.

Recording external payments (POST /payments)

For POS/gateway partners that collect money outside Dentolize. Body: { invoiceId, amount, type, treasuryId?, reference? } with type one of CARD | CASH | BANK_TRANSFER | MOBILE_WALLET | CHEQUE | OTHER (BALANCE and INSURANCE are rejected — those money flows are not reachable from the API). Runs the full platform money path: treasury routing via branch defaults, invoice/patient totals, payment.created / invoice.paid events. Idempotency-Key is required; the payment id is additionally derived from the key, so a retry can never record the money twice.

Creating visit invoices (POST /invoices)

For agentic bots and partner apps closing a visit. Body: { patientId, branchId, items: [{ procedureId, price?, tooth?, discount? }], appointmentId?, doctorId?, discount? | discountPercent?, notes? } (1-50 items; tooth is FDI numbers and multiplies the line quantity; use only ONE discount mode — invoice discount, invoice discountPercent, or per-item discounts). doctorId defaults to the appointment's doctor, then the patient's doctor.

Runs the exact clinic-app path: each item becomes a completed treatment line (doctor commissions, inventory usage, package counters all behave identically) and the invoice goes through the platform money core — patient totals, notifications and the invoice.created event included. v1 is cash-only: insurance/claim fields are rejected by the strict body (400 invalid_request) and diagnostic-fee lines are not accepted.

Idempotency-Key is required; the invoice id and every treatment-line id are derived from it, so a retry after a partial failure resumes (already-created lines are reused, an already-created invoice is returned as-is) — never a double charge.

Patient lookup (GET /patients/lookup?phone=)

Deterministic registered-or-new check for bots: the phone is normalized exactly like the clinic app normalizes it (so any accepted input format matches) and exact-matched against the stored full number. Returns { data: { object: "patient_lookup", registered, patientId, leadId } } — registered/patientId for an active patient, leadId (independently) when the phone matches a lead, letting you distinguish patient / known-lead / unknown. Ids only — no names or phones in the response, so plain patients:read suffices and no PII access is logged.

Payment links (POST /payment-links)

Body: { invoiceId, amount? } (amount defaults to the invoice pending amount). Creates a hosted payment page on the clinic's configured gateway — its default payment option, or its sole one — and returns 201 with the created online payment (paymentLink is the URL to share). Watch onlinepayment.succeeded / .failed / .refunded for the outcome; on success paymentId links the recorded payment. Idempotency-Key is required.

File uploads (two-step)

Uploading a document or x-ray to a patient record is a two-step flow. Allowed content types: image/jpeg, image/png, image/webp, image/tiff, image/bmp, application/pdf, application/dicom; max 100 MB (sizeBytes must be exact).

1. POST /patients/{id}/files with { fileName, contentType, sizeBytes, kind: "file" | "xray", operationId? } → { data: { fileId, uploadUrl, fields, method: "POST", expiresInSeconds } } — a presigned S3 POST.
2. Multipart-POST every fields entry plus the file (as the last field, named file) to uploadUrl — no Dentolize auth headers on this request.
3. POST /patients/{id}/files/{fileId}/confirm → the File row (and an Xray row when kind: "xray"), firing file.created / xray.created.

presign=$(curl -s -X POST "$BASE/patients/$PATIENT/files" \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: up-$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"fileName":"pano.png","contentType":"image/png","sizeBytes":102400,"kind":"xray"}')
# multipart-POST fields + file to the presigned URL (fields first, file last)
curl -s "$(jq -r .data.uploadUrl <<<"$presign")" \
  $(jq -r '.data.fields | to_entries[] | "-F \(.key)=\(.value)"' <<<"$presign") \
  -F "file=@pano.png"
curl -s -X POST "$BASE/patients/$PATIENT/files/$(jq -r .data.fileId <<<"$presign")/confirm" \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: confirm-$(uuidgen)"

The SDK wraps all three steps:

const file = await client.patientFiles.upload({
  patientId,
  buffer: await readFile('pano.png'),
  fileName: 'pano.png',
  contentType: 'image/png',
  kind: 'xray'
});