Animals

At a veterinary clinic the patient is the animal. An animal belongs to a client — the person who brings it in — and that is where the contact details live: an animal record carries no phone or email of its own.

Animal endpoints require the patients:read scope. Vaccination and measurement history require their own scopes, noted below.

Veterinary clinics only

At a dental clinic these endpoints return 404 with the problem type unsupported_capability. Call GET /v1/me before integrating — the animals capability tells you whether a clinic has them.

#The animal object

Field	Type	Description
`id`	string	Unique animal id (clinic-scoped).
`name`	string \| null	The animal's name. Animals have no family name.
`species`	object \| null	`{ id, name }` from the clinic's species catalog.
`breed`	object \| null	`{ id, name }` from the clinic's breed catalog.
`sex`	string \| null	`male`, `female`, or `null`.
`reproductive_status`	string \| null	`neutered`, or `null` meaning unknown. Never read `null` as "intact" — it means no procedure is on file.
`neuter_date`	string \| null	ISO `YYYY-MM-DD`.
`birth_date`	string \| null	ISO `YYYY-MM-DD`.
`estimated_age`	string \| null	Recorded when the date of birth is unknown.
`weight_kg`	number \| null	The standing weight on the record. The measured history is `/measurements`, and the two can legitimately differ.
`color`	string \| null	Coat or markings.
`blood_type`	string \| null
`microchip_number`	string \| null
`tag_number`	string \| null
`license_number`	string \| null
`enclosure_number`	string \| null
`status`	object \| null	Embedded status reference (`id`, `name`, `color`).
`client`	object \| null	The owner: `{ id, first_name, last_name, phone, email }`. `null` when no owner is on file.
`created_at`	string \| null	ISO 8601 timestamp.
`updated_at`	string \| null	ISO 8601 timestamp.

#List / search animals

GET /v1/animals

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

Parameter	In	Description
`query`	query	Name search. Matches the animal's own name only, not the owner's.
`species_id`	query	Restrict to one species (see Catalog).
`breed_id`	query	Restrict to one breed.
`client_id`	query	Only this owner's animals.
`microchip`	query	Exact microchip number.
`limit`, `cursor`	query	Pagination.

curl -G https://api.smile-app.co.il/v1/animals \
  -H "Authorization: Bearer sk_live_..." \
  --data-urlencode "microchip=941000024688123"

{
  "data": [
    {
      "id": "4211",
      "name": "Rexi",
      "species": { "id": "3", "name": "Dog" },
      "breed": { "id": "17", "name": "Labrador" },
      "sex": "male",
      "reproductive_status": "neutered",
      "weight_kg": 28.4,
      "microchip_number": "941000024688123",
      "client": {
        "id": "4210",
        "first_name": "Dana",
        "last_name": "Levi",
        "phone": "0521234567",
        "email": "dana@example.com"
      }
    }
  ],
  "next_cursor": null
}

#Retrieve an animal

GET /v1/animals/{id}

Returns one animal. An id that belongs to a client returns 404 — an id that works here is always an animal.

#An animal's appointments, treatments, payments, calls and messages

GET /v1/animals/{id}/appointments GET /v1/animals/{id}/treatments GET /v1/animals/{id}/payments GET /v1/animals/{id}/calls GET /v1/animals/{id}/whatsapp/messages POST /v1/animals/{id}/payments

These are the same collections the generic API exposes under /v1/patients/{id}/…, with identical payloads, parameters and required scopes — an animal id is a patient id. They exist so a veterinary integration can stay in one vocabulary instead of switching to patients the moment it does anything with an animal.

Each requires the scope of the resource it returns, and each item takes the shape documented on that resource's own page:

Collection	Scope	Object
`appointments`	`appointments:read`	Appointment
`treatments`	`treatments:read`	Treatment
`payments`	`payments:read`	Payment
`payments` (POST)	`payments:write`	Recording a payment
`calls`	`calls:read`	Call
`whatsapp/messages`	`whatsapp:read`	Message

All of them are paginated and accept limit and cursor.

#List an animal's vaccinations

GET /v1/animals/{id}/vaccines · requires vaccines:read

Returns a paginated list of administered doses, most recent first.

Field	Type	Description
`id`	string	Record id.
`vaccine`	object \| null	`{ id, name, code, interval_months }` from the vaccine catalog.
`performed_at`	string \| null	ISO `YYYY-MM-DD`.
`next_due_at`	string \| null	When the clinic scheduled the next dose. Use it as given — clinics deviate from the catalog interval per animal, so do not recompute it.
`batch_number`	string \| null
`microchip_number`	string \| null	Recorded at administration, where the clinic captures it.
`tag_number`	string \| null
`price`	number \| null
`discount`	number \| null
`notes`	string \| null
`administered_by`	object \| null	`{ id, name }`.
`appointment_id`	string \| null	The visit it was given at, when linked.

#List an animal's measurements

GET /v1/animals/{id}/measurements · requires measurements:read

Returns a paginated list of measurement sessions, most recent first. A session is everything recorded at one moment — weight, temperature, pulse, respiration, body condition score — which is how a clinic records them and the only way a trend reads back correctly.

The catalog is open: the five seeded types are vital signs, but a clinic records whatever it needs. Fetch the available types from /v1/catalog/measurements.

Field	Type	Description
`id`	string	Session id.
`recorded_at`	string \| null	ISO 8601 timestamp.
`recorded_by`	object \| null	`{ id, name }`.
`notes`	string \| null
`values`	array	`{ measurement: { id, name, unit }, value }` per reading.

{
  "data": [
    {
      "id": "301",
      "recorded_at": "2026-08-12T10:30:00+03:00",
      "recorded_by": { "id": "7", "name": "Dr Cohen" },
      "notes": null,
      "values": [
        { "measurement": { "id": "1", "name": "Weight", "unit": "kg" }, "value": 28.4 }
      ]
    }
  ],
  "next_cursor": null
}