Patients

Patients are the people treated at a clinic. You can search the patient list, fetch a single patient, and read a patient's appointments, treatments, and payments.

All patient endpoints require the patients:read scope (sub-resources additionally require their own scope, noted below).

#The patient object

Field	Type	Description
`id`	string	Unique patient id (clinic-scoped).
`first_name`	string \| null	Given name.
`last_name`	string \| null	Family name.
`phone`	string \| null	Primary phone.
`email`	string \| null	Primary email.
`gender`	string \| null	`male`, `female`, or `null`.
`birth_date`	string \| null	ISO `YYYY-MM-DD`.
`status`	object \| null	Embedded status reference (`id`, `name`, `color`).
`created_at`	string \| null	ISO 8601 timestamp.
`updated_at`	string \| null	ISO 8601 timestamp.

With response_format=detailed, additional fields such as address, contacts, balance, and id number are included where available.

#List / search patients

GET

Returns a paginated list of patients. Combine filters to narrow the search.

Parameter	In	Description
`phone`	query	Match by phone number.
`email`	query	Match by email.
`query`	query	Name search.
`limit`, `cursor`	query	Pagination.
`response_format`	query	`concise` (default) or `detailed`.

curl -G https://api.smile-app.co.il/v1/patients \
  -H "Authorization: Bearer sk_live_..." \
  --data-urlencode "query=levi" \
  --data-urlencode "limit=25"

{
  "data": [
    { "id": "8842", "first_name": "Dana", "last_name": "Levi", "phone": "0521234567", "email": "dana@example.com" }
  ],
  "next_cursor": null
}

#Retrieve a patient

GET

Parameter	In	Description
`id`	path	The patient id.
`response_format`	query	`concise` or `detailed`.

curl -G https://api.smile-app.co.il/v1/patients/8842 \
  -H "Authorization: Bearer sk_live_..." \
  --data-urlencode "response_format=detailed"

{
  "data": {
    "id": "8842",
    "first_name": "Dana",
    "last_name": "Levi",
    "phone": "0521234567",
    "email": "dana@example.com",
    "gender": "female",
    "birth_date": "1990-04-12",
    "status": { "id": "1", "name": "Active", "color": "#16a34a" },
    "created_at": "2024-01-08T10:22:00+02:00",
    "updated_at": "2026-05-30T14:01:00+03:00"
  }
}

#A patient's appointments

GET

Paginated list of the patient's appointments. Requires appointments:read. The items use the appointment object.

curl https://api.smile-app.co.il/v1/patients/8842/appointments \
  -H "Authorization: Bearer sk_live_..."

#A patient's treatments

GET

Paginated list of treatments performed/recorded for the patient. Requires treatments:read.

Parameter	In	Description
`appointment_id`	query	Only treatments for one appointment.
`limit`, `cursor`	query	Pagination.

See the treatment object.

#A patient's payments

GET

Paginated list of the patient's payments and refunds. Requires payments:read. See the payment object.

Card details are never returned

Payment responses include the amount, currency, method type, and whether it's a refund - but never card numbers, check numbers, or bank details.