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.

Reading patients requires the patients:read scope; sub-resources additionally require their own scope, noted below. Creating a patient requires patients:write on its own — a key that only writes gets back the id of a patient it matched by id_number, not the patient's details.

At a veterinary clinic

The patient is the animal, and its owner is a separate record. These endpoints still work and return both — but /v1/animals and /v1/clients give you the species, breed, microchip and owner that this generic shape leaves out. Add ?include=owner,species to any endpoint on this page to get that context inside the embedded patient without switching endpoints.

#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 /v1/patients

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 /v1/patients/{id}

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"
  }
}

#Create a patient

POST /v1/patients · scope patients:write

Minimal creation: a name to file the record under, plus the identity fields you need to find the patient again or print on a document. Everything else (status, type, pricing, folders) is set inside Smile.

Field	Type	Description
`first_name`	string	Required.
`last_name`	string	Optional.
`id_number`	string	Optional. Israeli ID number, or a business's registration / VAT number. Not checksum-validated.
`phone`	string	Optional.
`email`	string	Optional.

Idempotent on id_number: when a patient already carries that number, it is returned with 200 and nothing is created. Without an id_number nothing is matched, so send one whenever you have it.

curl https://api.smile-app.co.il/v1/patients \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Dana", "last_name": "Levi", "id_number": "123456782", "phone": "0521234567"}'

{
  "data": {
    "id": "9120",
    "first_name": "Dana",
    "last_name": "Levi",
    "phone": "0521234567",
    "email": null,
    "gender": null,
    "birth_date": null,
    "status": null,
    "created_at": "2026-10-30T20:15:00+02:00",
    "updated_at": "2026-10-30T20:15:00+02:00"
  }
}

201 Created for a new patient, 200 OK when an existing one was returned.

#A patient's appointments

GET /v1/patients/{id}/appointments

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 /v1/patients/{id}/treatments

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 /v1/patients/{id}/payments

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.