SmileCloudDocs

API reference

The v1 REST API is a small, read-only surface over your clinic's data. This page covers the conventions that apply everywhere; the resource pages document each endpoint in detail.

#Base URL

text
https://api.smile-app.co.il

All endpoints are versioned under /v1. An OpenAPI 3.1 description of the entire surface is served unauthenticated at /openapi.json.

#Conventions

  • Auth - every request needs Authorization: Bearer sk_live_.... See Authentication.
  • Format - requests and responses are JSON. Successful responses wrap the payload in a data field.
  • Single resource - { "data": { ... } }.
  • Collection - { "data": [ ... ], "next_cursor": "..." | null } for paginated lists, or { "data": [ ... ] } for bounded lists.
  • Pagination - ?limit= and ?cursor=. See Pagination.
  • Detail level - ?response_format=concise|detailed where supported.
  • Errors - application/problem+json. See Errors.
  • Ids are strings - always treat ids as opaque strings, scoped to one clinic.

#Resources

ResourceEndpointsScope
AccountGET /v1/me(none)
PatientsGET /v1/patients, /v1/patients/{id} and sub-resourcespatients:read
AppointmentsGET /v1/appointments, /v1/appointments/{id}appointments:read
AvailabilityGET /v1/availabilityavailability:read
TreatmentsGET /v1/treatments/{id}, patient treatmentstreatments:read
PaymentsGET /v1/payments/{id}, patient payments, record a paymentpayments:read, payments:write
LeadsPOST /v1/leads — capture CRM leads from external channelsleads:write
CallsGET /v1/calls, summaries, transcripts, recording linkscalls:read
CatalogGET /v1/catalog/*catalog:read
AnalyticsGET /v1/metrics, POST /v1/queryanalytics:read
Webhooks APIPOST/GET/DELETE /v1/webhookswebhooks:manage

#Embedded references

To save you from chasing ids, list and detail responses embed compact references to related objects rather than returning bare ids. An appointment, for example, includes a small patient, branch, type, and status object inline:

json
{
  "data": {
    "id": "55021",
    "patient": { "id": "8842", "first_name": "Dana", "last_name": "Levi" },
    "branch": { "id": "1", "name": "Downtown Branch" },
    "type": { "id": "3", "name": "Cleaning", "duration_minutes": 30 },
    "status": { "id": "2", "name": "Confirmed", "color": "#16a34a" },
    "providers": [{ "id": "12", "name": "Dr. Cohen" }],
    "start": "2026-07-01T09:00:00+03:00",
    "end": "2026-07-01T09:30:00+03:00"
  }
}

These embedded shapes (PatientSummary, BranchRef, TypeRef, StatusRef, ProviderRef) are intentionally minimal - enough to display without a second request.

PreviousScopesNextAccount