Conventions

The Shepherd API is consistent across resources. Once you know the conventions on this page, every endpoint reads about the same.

POST almost everywhere

Every endpoint accepts POST with Content-Type: application/json and returns JSON. There are no GET, PATCH, or DELETE verbs. Reads, creates, searches, and deletes are all POSTs, distinguished by the URL path. See Overview for the reasoning.

The exception is updating an existing record: clients, patients, and appointments each expose a PUT .../{id}/update endpoint. Those behave differently enough to deserve their own section.

Updating records is a full replacement

Update endpoints are PUT, and they mean it. A PUT submits the complete representation of the record, so any editable field you omit is interpreted as an intentional change and is cleared: set to null, empty, or its default. It is not a partial update, and there is no PATCH.

This catches integrators out most often on nested collections. If you send a client update whose clientCoOwner block has no clientCoOwnerPhones array, you are telling the API the co-owner has no phone numbers, and the existing ones are removed.

A partial body is a destructive body

Never build an update payload from just the fields you want to change. On a PUT endpoint that is a delete instruction for everything else.

Read, merge, write

The safe pattern, and the one we recommend for any synchronisation logic, is three steps:

1. Read the current record, embedding every nested collection you are about to send back.
2. Merge your changes into that full representation in memory.
3. Write the merged whole back to the update endpoint.

GET current state  ──►  apply your changes  ──►  PUT the complete object
   (with embeds)          (in memory)              (nothing omitted)

Step 1 is where most data loss originates: if the read did not include a nested collection, the merged object will not contain it either, and the write will clear it. Embed defensively.

Fields that survive omission

A few fields are deliberately exempt from the full-replace rule, either because they are immutable or because they are managed elsewhere:

Resource	Preserved when omitted	Cannot be changed here
Client	clientStatusId, the clientInfo contact block	Home clinic, system identifiers, deleted status
Patient	(none)	Home clinic, system identifiers, client association, deleted status

authorizedAgents on a client update is a further exception: it is an explicit edit list rather than a replacement. Each entry adds an agent (omit id), edits one in place (include id), or removes one (set authorizedAgentIdForRemove with a removalNote). Agents you do not reference are left untouched.

Everything not listed above follows the full-replace rule.

Responses

Update endpoints return 200 OK with the updated record, not 201 Created. A 404 means the {id} in the path does not resolve within the clinic named by X-Clinic-Id.

The collection envelope

List endpoints return a wrapper, not a bare array. The shape is:

{
  "item": [ /* the records on this page */ ],
  "totalRecords": 1432,
  "page": 1,
  "recordsPerPage": 10,
  "sort": "dateCreated|desc",
  "searchQuery": null,
  "embed": "clients,clientPhones.phoneType",
  "links": []
}

A few things worth noting:

• item is always an array, even when there is one record.
• totalRecords is the total across all pages, not just this page.
• links is currently always empty. Do not depend on it.
• sort, searchQuery, and embed echo what you sent in the request.

Single-record endpoints return the record directly, without the envelope.

Pagination

Pagination is driven by two body fields:

Field	Default	Maximum	Notes
page	1	n/a	1-indexed. page: 0 is not valid.
rpp	10	1000	Records per page.

There is a hard ceiling of 10,000 items reachable through pagination: page * rpp must not exceed 10000. A request that would cross that line returns HTTP 400. To pull more than 10,000 records, narrow the result set with a filter (typically a date range) and re-paginate.

Embedding related entities

Most endpoints accept an embed field with comma-separated dot-paths. The API inlines the named relations into the response instead of returning only their IDs.

{
  "page": 1,
  "rpp": 50,
  "embed": "clients,clientPhones.phoneType"
}

Dot-paths walk relationships. clientPhones.phoneType inlines the phones on each client and the phone-type lookup record for each phone. Embeds compound, so be deliberate: a deep embed on a large rpp can return a lot of JSON.

Sorting

Sort with the sort field. The format is field|direction, where direction is asc or desc:

{ "sort": "dateCreated|desc" }

Only one sort key at a time is honored.

Date-range filtering

Many list endpoints require a date-range filter. The pairs are:

• dateCreatedFrom / dateCreatedTo
• dateUpdatedFrom / dateUpdatedTo

Both ends of the pair are required when filtering, and the range is capped at one calendar month. To pull a longer window, sweep month by month.

Timestamps are ISO 8601 in UTC, for example 2025-04-01T00:00:00Z.

Soft deletes

Many records carry a deleted boolean flag. Records flagged deleted: true have been soft-deleted in Shepherd. Filter on deleted in the request body, or check it on each record before processing.

Timestamps

Every record includes:

• dateCreated: when the record was first created, ISO 8601 UTC.
• dateUpdated: when the record was last modified, ISO 8601 UTC.

Use dateUpdated for incremental syncs (paired with dateUpdatedFrom/dateUpdatedTo).

Example: paginating patients

The following pulls the second page of 100 patients, sorted by most-recent update, with each patient’s breed inlined:

curl

curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients \
  -H "Content-Type: application/json" \
  -H "X-Integration-Public-Key: $SHEPHERD_PUBLIC_KEY" \
  -H "X-Integration-Private-Key: $SHEPHERD_PRIVATE_KEY" \
  -H "X-Clinic-Id: $SHEPHERD_CLINIC_ID" \
  -d '{"page":2,"rpp":100,"sort":"dateUpdated|desc","embed":"breed"}'

Python

import os, requests

resp = requests.post(
    "https://open-api.shepherd.vet/pav2/open-api-patients",
    headers={
        "Content-Type": "application/json",
        "X-Integration-Public-Key": os.environ["SHEPHERD_PUBLIC_KEY"],
        "X-Integration-Private-Key": os.environ["SHEPHERD_PRIVATE_KEY"],
        "X-Clinic-Id": os.environ["SHEPHERD_CLINIC_ID"],
    },
    json={
        "page": 2,
        "rpp": 100,
        "sort": "dateUpdated|desc",
        "embed": "breed",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()
print(f"Page {data['page']} of {-(-data['totalRecords'] // data['recordsPerPage'])}")
for patient in data["item"]:
    print(patient["id"], (patient.get("breed") or {}).get("name"))

C#

using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Integration-Public-Key", publicKey);
http.DefaultRequestHeaders.Add("X-Integration-Private-Key", privateKey);
http.DefaultRequestHeaders.Add("X-Clinic-Id", clinicId);

var body = JsonContent.Create(new
{
    page = 2,
    rpp = 100,
    sort = "dateUpdated|desc",
    embed = "breed",
});
var resp = await http.PostAsync(
    "https://open-api.shepherd.vet/pav2/open-api-patients", body);
resp.EnsureSuccessStatusCode();
var json = await resp.Content.ReadAsStringAsync();
Console.WriteLine(json);

PHP

<?php
$ch = curl_init('https://open-api.shepherd.vet/pav2/open-api-patients');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Integration-Public-Key: ' . getenv('SHEPHERD_PUBLIC_KEY'),
        'X-Integration-Private-Key: ' . getenv('SHEPHERD_PRIVATE_KEY'),
        'X-Clinic-Id: ' . getenv('SHEPHERD_CLINIC_ID'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'page' => 2,
        'rpp' => 100,
        'sort' => 'dateUpdated|desc',
        'embed' => 'breed',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
foreach ($data['item'] as $patient) {
    echo $patient['id'] . "\t" . ($patient['breed']['name'] ?? '') . "\n";
}

JavaScript

const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-patients', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Integration-Public-Key': process.env.SHEPHERD_PUBLIC_KEY,
    'X-Integration-Private-Key': process.env.SHEPHERD_PRIVATE_KEY,
    'X-Clinic-Id': process.env.SHEPHERD_CLINIC_ID,
  },
  body: JSON.stringify({
    page: 2,
    rpp: 100,
    sort: 'dateUpdated|desc',
    embed: 'breed',
  }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
console.log(`Page ${data.page} of ${Math.ceil(data.totalRecords / data.recordsPerPage)}`);
for (const patient of data.item) {
  console.log(patient.id, patient.breed?.name);
}

Next

• Errors for the two JSON error body shapes and status codes.
• Rate limits for how aggressive you can be with paging loops.