List patients

Returns a paginated list of patients accessible to the clinic associated with your API key. ### Access Model Patients in Vetigen are **global entities** — a single patient record may be shared across multiple clinics via `CustomerClinicConnection`. This endpoint returns patients that have an active connection to the caller's clinic, regardless of which clinic originally created the record. ### Sorting Results are sorted by `updated_at DESC` by default — most recently modified first. ### Pagination Use `page` and `page_size` query parameters. The response includes `has_more: true` when additional pages are available. Prefer cursor-style iteration over random page access for large datasets — page numbers may shift as records change. ### Common Errors - `PATIENT.ACCESS_DENIED` — API key's clinic has no connection to the requested patients. - `AUTH.RATE_LIMITED` — see rate-limit headers.

Authorization

JWT-auth

AuthorizationBearer <token>

API key issued from the Vetigen Developer Portal. Pass as Authorization: Bearer YOUR_API_KEY.

In: header

Query Parameters

page?integer

Page number (1-indexed).

Default1

Range1 <= value

page_size?integer

Items per page. Max 100.

Default20

Range1 <= value <= 100

species?string

Filter by species (e.g. dog, cat, rabbit).

updated_since?string

Only return patients updated after this ISO 8601 timestamp. Useful for incremental sync.

Formatdate-time

Response Body

`application/json`

curl -H "Authorization: Bearer $VETIGEN_API_KEY" \  "https://api.vetigen.com/api/v1/patients?page=1&page_size=20&species=dog"

{
  "success": true,
  "data": {
    "items": [
      {
        "fp": "patient_01JABC9XYZKL4N7P3Q8TRM2ZDE",
        "name": "Boncuk",
        "species": "dog",
        "breed": "Golden Retriever",
        "sex": "male",
        "date_of_birth": "2019-06-15",
        "weight_kg": 28.4,
        "owner_customer_fp": "customer_01JABC...",
        "created_at": "2024-11-03T09:24:17.000Z",
        "updated_at": "2026-03-18T14:02:41.000Z"
      }
    ],
    "total": 152,
    "page": 1,
    "page_size": 20,
    "has_more": true
  },
  "message": "OK"
}

{
  "success": false,
  "error": {
    "code": "AUTH.UNAUTHORIZED",
    "message": "Authentication required.",
    "severity": "error"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH.FORBIDDEN",
    "message": "Insufficient permissions.",
    "severity": "error"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH.RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 42 seconds.",
    "severity": "warning"
  }
}

{
  "success": false,
  "error": {
    "code": "PATIENT.NOT_FOUND",
    "message": "Patient with fingerprint patient_01JABC does not exist.",
    "severity": "error",
    "details": {}
  }
}

Usage Notes

Incremental Sync Pattern

For dashboards and third-party integrations mirroring patient data, combine updated_since with periodic polling (every 5–15 minutes):

// Store the last successful sync timestamp per integration
const cursor = await db.getSyncCursor('vetigen:patients');
const nextCursor = new Date().toISOString();

const params = new URLSearchParams({
  page: '1',
  page_size: '100',
  ...(cursor && { updated_since: cursor }),
});

// Paginate until has_more === false, then persist nextCursor.

Using updated_since avoids full table scans and keeps bandwidth proportional to actual clinic activity.

Common Pitfalls

Species filter values are lowercase ISO codes where applicable (dog, cat, rabbit, bird, reptile, exotic). Uppercase values silently match nothing.
Page numbers shift if patients are created/deleted between requests. Prefer updated_since + full pagination for sync jobs.
Soft-deleted patients are excluded by default. To include them, use the admin endpoint (not available in the public API).

Response Size

A page_size=100 response with typical field coverage averages ~35 KB gzipped. Plan batch sizes accordingly if you're bandwidth-constrained (e.g. mobile sync).

200application/json

401application/json

403application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`