"}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-payments",
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": 1,
"rpp": 100,
"sort": "paymentDate|desc",
"clientIds": os.environ["SHEPHERD_CLIENT_ID"],
},
timeout=30,
)
resp.raise_for_status()
for p in resp.json()["item"]:
print(p["paymentDate"], p["amount"], p["paymentMethodId"])
```
* C#
```csharp
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 = 1,
rpp = 100,
sort = "paymentDate|desc",
clientIds = clientId,
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-payments", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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' => 1,
'rpp' => 100,
'sort' => 'paymentDate|desc',
'clientIds' => getenv('SHEPHERD_CLIENT_ID'),
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-payments', {
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: 1,
rpp: 100,
sort: 'paymentDate|desc',
clientIds: process.env.SHEPHERD_CLIENT_ID,
}),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const p of page.item) console.log(p.paymentDate, p.amount, p.paymentMethodId);
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "c1d2e3f4-...",
"clientId": "a1b2c3d4-...",
"clinicId": "f2a4c6e8-...",
"paymentDate": "2026-05-21T13:42:00Z",
"amount": 128.5,
"paymentMethodId": "5e6f7a8b-...",
"paymentStatusId": "9c8d7e6f-...",
"referenceNumber": null,
"authCode": "0091AB",
"cardType": "Visa",
"lastDigits": "4242",
"transactionId": "txn_8c2...",
"payToCreditBalance": 0,
"clientBalanceAfterPayment": 0,
"refundedPaymentId": null,
"processedByUserId": "bb551122-...",
"note": null,
"isDeleted": false,
"dateVoided": null,
"dateCreated": "2026-05-21T13:42:01Z",
"dateUpdated": "2026-05-21T13:42:01Z"
}
],
"totalRecords": 1,
"page": 1,
"recordsPerPage": 100,
"sort": "paymentDate|desc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## Payment methods
[Section titled “Payment methods”](#payment-methods)
POST `/pav2/open-api-payment-methods`
The list of tender types the clinic accepts (cash, card brands, check, in-house credit, gift card, etc.). Use this to populate a UI picker, or to translate the `paymentMethodId` on a payment record into a human-readable name.
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-payment-methods \
-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":1,"rpp":100}'
```
A parallel endpoint, `/pav2/open-api-payment-statuses`, returns the payment-status catalog (pending, approved, declined, voided, refunded). Both are also discoverable through [Lookups](/api-reference/resources/lookups/).
## Client balances
[Section titled “Client balances”](#client-balances)
The `open-api-client-balances` controller exposes four aging cuts of client A/R. Each is a separate sub-route under the same prefix; pick the one that matches what you need to surface.
POST `/pav2/open-api-client-balances/balances`
POST `/pav2/open-api-client-balances/aging`
POST `/pav2/open-api-client-balances/outstanding-balance-aging`
POST `/pav2/open-api-client-balances/credit-balance-aging`
| Sub-route | What it returns |
| --------------------------- | ----------------------------------------------------- |
| `balances` | Current balance per client (net of credits). |
| `aging` | Standard A/R aging buckets (0-30, 31-60, 61-90, 90+). |
| `outstanding-balance-aging` | Aging of unpaid invoices only. |
| `credit-balance-aging` | Aging of in-house credit on file. |
`balances` filters on `dateUpdatedFrom` / `dateUpdatedTo`, `clientIds`, and `clientClinicAccountIds`. It accepts `dateCreatedFrom` / `dateCreatedTo`, `ids`, and `embed` without an error but does not apply them. Sorting `balances` by `dateCreated`, or by any field whose name contains `id`, returns `501`.
### Example: aging summary
[Section titled “Example: aging summary”](#example-aging-summary)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-client-balances/aging \
-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":1,"rpp":100}'
```
* JavaScript
```js
const resp = await fetch(
'https://open-api.shepherd.vet/pav2/open-api-client-balances/aging',
{
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: 1, rpp: 100 }),
},
);
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const row of page.item) console.log(row.clientId, row);
```
## See also
[Section titled “See also”](#see-also)
* [Invoices](/api-reference/resources/invoices/) for the upstream charges payments apply against.
* [Clients](/api-reference/resources/clients/) for the client records balances roll up under.
* [Conventions](/api-reference/conventions/) for pagination, sorting, and date filters.
* [Errors](/api-reference/errors/) for the error body shapes.
# Prescriptions
> Dispensed and prescribed medications tied to a patient and prescribing doctor.
A prescription represents a medication a clinician has prescribed or dispensed for a patient. It is tied to the patient receiving the medication, the doctor prescribing it, and (unless it is a written script) the product in the clinic catalog being dispensed. Refills are tracked as related refill records with their own endpoint, so the original prescription stays the source of truth for the script.
Use prescriptions to surface a patient’s active medications, drive pharmacy fulfilment, or feed compliance dashboards.
Note
A prescription in Shepherd represents an active dispensing event, not a historical record. Its creation date is always assigned by the server and cannot be backdated; see [Dates and backdating](#dates-and-backdating) before planning any data migration.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Notes |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `id` | UUID | Server-assigned identifier. |
| `patientId` | UUID | Patient the prescription is written for. |
| `prescribingDoctorId` | UUID | User who prescribed the medication. |
| `productId` | UUID | Catalog product being dispensed. Null when `isWritten` is true. |
| `name` | string | Name of the prescription. |
| `direction` | string | Free-text directions explaining how to use the medication. |
| `quantity` | decimal | Quantity dispensed. |
| `refillQuantity` | integer | Total available refill amount. |
| `refillCount` | integer | Refills available on the script; cannot exceed `refillQuantity`. |
| `refillPrn` | boolean | Whether PRN (as-needed) refills are supported. |
| `isRefillAllowed` | boolean | True when `refillQuantity` is greater than 0. |
| `isWritten` | boolean | True for a written script filled outside the clinic; use `writtenProduct` instead of `productId`. |
| `writtenProduct` | string | Product name for a written prescription. |
| `writtenIsControlled` | boolean | Whether the written product is a controlled substance. |
| `isChronicMedication` | boolean | Flags long-term medications. |
| `soapId` | UUID | Optional SOAP record this prescription was created against. |
| `expirationDate` | ISO 8601 | Labeled “Rx Valid Thru” in Shepherd: the last date the script is valid for refills. |
| `isCanceled` | boolean | Whether the prescription was canceled (`cancelNote` carries the reason). |
| `clinicId` | UUID | Clinic the prescription belongs to. |
| `createdByUserId` | UUID | User who created the record. |
| `dateCreated` | ISO 8601 | Server-assigned creation timestamp (UTC). Cannot be set or overridden. |
| `dateUpdated` | ISO 8601 | Last server-side mutation (UTC). |
## List / search
[Section titled “List / search”](#list--search)
POST `/pav2/open-api-prescriptions`
Standard collection envelope. Filter with comma-separated ID lists (`patientIds`, `productIds`, `clientIds`), embed related records such as `createdByUser`, and page through results with `page` and `rpp`.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-prescriptions \
-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 '{
"patientIds": "12ab...",
"page": 1,
"rpp": 50,
"sort": "dateCreated|desc"
}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-prescriptions",
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={"patientIds": "12ab...", "page": 1, "rpp": 50, "sort": "dateCreated|desc"},
timeout=30,
)
resp.raise_for_status()
page = resp.json()
for rx in page["item"]:
print(rx["name"], rx["quantity"], rx["expirationDate"])
```
* C#
```csharp
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 {
patientIds = "12ab...",
page = 1,
rpp = 50,
sort = "dateCreated|desc",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-prescriptions", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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([
'patientIds' => '12ab...',
'page' => 1,
'rpp' => 50,
'sort' => 'dateCreated|desc',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-prescriptions', {
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({ patientIds: '12ab...', page: 1, rpp: 50, sort: 'dateCreated|desc' }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const rx of page.item) {
console.log(rx.name, rx.quantity, rx.expirationDate);
}
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "7ad2...",
"clinicId": "c3f1...",
"patientId": "12ab...",
"prescribingDoctorId": "bb55...",
"createdByUserId": "9c0d...",
"productId": "44de...",
"name": "Amoxicillin 250 mg",
"direction": "Give one tablet by mouth every 12 hours for 7 days.",
"quantity": 14,
"refillQuantity": 2,
"refillCount": 2,
"refillPrn": false,
"isRefillAllowed": true,
"isWritten": false,
"writtenProduct": null,
"writtenIsControlled": null,
"isChronicMedication": false,
"isCanceled": false,
"cancelNote": null,
"substitutionPermitted": false,
"soapId": null,
"expirationDate": "2026-10-21T00:00:00Z",
"dateCreated": "2026-04-21T14:11:09Z",
"dateUpdated": "2026-04-21T14:11:09Z"
}
],
"totalRecords": 312,
"page": 1,
"recordsPerPage": 50,
"sort": "dateCreated|desc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## Create
[Section titled “Create”](#create)
POST `/pav2/open-api-prescriptions/write`
Creates a new prescription record. `patientId` and `expirationDate` are required. For an in-clinic product, provide `productId`; for a written script filled outside the clinic, set `isWritten` to true, provide `writtenProduct` instead, and omit `productId`. See the [live Swagger UI](https://app.shepherd.vet/swagger/) for the authoritative schemas.
The created record’s `dateCreated` is assigned by the server at insert time; there is no request field that sets or overrides it (see [Dates and backdating](#dates-and-backdating)).
### Example
[Section titled “Example”](#example-1)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-prescriptions/write \
-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 '{
"patientId": "12ab...",
"prescribingDoctorId": "bb55...",
"productId": "44de...",
"quantity": 14,
"refillQuantity": 2,
"direction": "Give one tablet by mouth every 12 hours for 7 days.",
"expirationDate": "2026-12-31T00:00:00Z",
"isChronicMedication": false
}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-prescriptions/write",
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={
"patientId": "12ab...",
"prescribingDoctorId": "bb55...",
"productId": "44de...",
"quantity": 14,
"refillQuantity": 2,
"direction": "Give one tablet by mouth every 12 hours for 7 days.",
"expirationDate": "2026-12-31T00:00:00Z",
"isChronicMedication": False,
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())
```
* C#
```csharp
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 {
patientId = "12ab...",
prescribingDoctorId = "bb55...",
productId = "44de...",
quantity = 14,
refillQuantity = 2,
direction = "Give one tablet by mouth every 12 hours for 7 days.",
expirationDate = "2026-12-31T00:00:00Z",
isChronicMedication = false,
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-prescriptions/write", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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([
'patientId' => '12ab...',
'prescribingDoctorId' => 'bb55...',
'productId' => '44de...',
'quantity' => 14,
'refillQuantity' => 2,
'direction' => 'Give one tablet by mouth every 12 hours for 7 days.',
'expirationDate' => '2026-12-31T00:00:00Z',
'isChronicMedication' => false,
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch(
'https://open-api.shepherd.vet/pav2/open-api-prescriptions/write',
{
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({
patientId: '12ab...',
prescribingDoctorId: 'bb55...',
productId: '44de...',
quantity: 14,
refillQuantity: 2,
direction: 'Give one tablet by mouth every 12 hours for 7 days.',
expirationDate: '2026-12-31T00:00:00Z',
isChronicMedication: false,
}),
},
);
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
console.log(await resp.json());
```
## Dates and backdating
[Section titled “Dates and backdating”](#dates-and-backdating)
Two date behaviors matter when you work with prescriptions, especially if you are moving data from another system:
**`dateCreated` is server-assigned and cannot be backdated.** A prescription in Shepherd represents an active dispensing event: creating one runs the live clinical workflow, including label generation, so the system always treats the prescription as something happening now. The API does not expose a prescribed or created date on the write model; this is deliberate and preserves the integrity and auditability of prescription records. Shepherd itself does not support backdating prescriptions, and the API mirrors the product.
**`expirationDate` is the date you control.** It is required on create, appears in Shepherd as “Rx Valid Thru”, and represents the last date the script is valid for refills. It can be a date in the past, for example when recording a script whose validity window has already ended.
Passing a `soapId` associates the prescription with a SOAP record, but it does not change the prescription’s own `dateCreated`; a prescription linked to an older visit still carries the timestamp of the moment it was created.
### Migrating historical prescriptions
[Section titled “Migrating historical prescriptions”](#migrating-historical-prescriptions)
Do not create native prescriptions for historical scripts. Every migrated record would carry the migration date as its creation date, which misrepresents the patient’s medication history and triggers the active dispensing workflow for medications that were dispensed long ago.
Instead, import each historical prescription as a patient note. This is the same approach Shepherd’s own data-migration process uses (those notes are labeled “imported prescription”): the note preserves the historical fact that a prescription was issued at a specific point in time, without creating a new dispensing event. Put the original prescribed date, drug, strength, directions, quantity, and refill details in the note body.
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-patient-notes/write \
-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 '{
"patientId": "12ab...",
"title": "Imported prescription: Carprofen 75 mg",
"note": "Prescribed 2024-03-14 by Dr. Alvarez. Carprofen 75 mg, give 1 tablet by mouth every 12 hours for 14 days. Quantity 28, no refills. Rx valid through 2024-09-14."
}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-patient-notes/write",
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={
"patientId": "12ab...",
"title": "Imported prescription: Carprofen 75 mg",
"note": (
"Prescribed 2024-03-14 by Dr. Alvarez. Carprofen 75 mg, give 1 tablet "
"by mouth every 12 hours for 14 days. Quantity 28, no refills. "
"Rx valid through 2024-09-14."
),
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())
```
* C#
```csharp
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 {
patientId = "12ab...",
title = "Imported prescription: Carprofen 75 mg",
note = "Prescribed 2024-03-14 by Dr. Alvarez. Carprofen 75 mg, give 1 tablet " +
"by mouth every 12 hours for 14 days. Quantity 28, no refills. " +
"Rx valid through 2024-09-14.",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-patient-notes/write", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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([
'patientId' => '12ab...',
'title' => 'Imported prescription: Carprofen 75 mg',
'note' => 'Prescribed 2024-03-14 by Dr. Alvarez. Carprofen 75 mg, give 1 tablet '
. 'by mouth every 12 hours for 14 days. Quantity 28, no refills. '
. 'Rx valid through 2024-09-14.',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch(
'https://open-api.shepherd.vet/pav2/open-api-patient-notes/write',
{
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({
patientId: '12ab...',
title: 'Imported prescription: Carprofen 75 mg',
note:
'Prescribed 2024-03-14 by Dr. Alvarez. Carprofen 75 mg, give 1 tablet ' +
'by mouth every 12 hours for 14 days. Quantity 28, no refills. ' +
'Rx valid through 2024-09-14.',
}),
},
);
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
console.log(await resp.json());
```
Tip
If the historical script belongs to a visit you are also migrating, you can reference that visit in the note body. The patient-notes endpoints follow the same list / write conventions as the rest of the API; schemas are in the [live Swagger UI](https://app.shepherd.vet/swagger/).
## List refills
[Section titled “List refills”](#list-refills)
POST `/pav2/open-api-refills`
Refills are read-only through the API: they are recorded in Shepherd when the clinic fills a script. Filter by `prescriptionIds` to pull the refill history for a script, or by `patientIds` and `refillStatusIds`; embed `refillStatus` to inline the status lookup.
### Example
[Section titled “Example”](#example-2)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-refills \
-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 '{
"prescriptionIds": "7ad2...",
"embed": "refillStatus"
}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-refills",
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={"prescriptionIds": "7ad2...", "embed": "refillStatus"},
timeout=30,
)
resp.raise_for_status()
for refill in resp.json()["item"]:
print(refill["dateFilled"], refill["refillQuantity"])
```
* C#
```csharp
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 {
prescriptionIds = "7ad2...",
embed = "refillStatus",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-refills", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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([
'prescriptionIds' => '7ad2...',
'embed' => 'refillStatus',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-refills', {
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({ prescriptionIds: '7ad2...', embed: 'refillStatus' }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const refill of page.item) {
console.log(refill.dateFilled, refill.refillQuantity);
}
```
### Response
[Section titled “Response”](#response-1)
```json
{
"item": [
{
"id": "e7d8...",
"prescriptionId": "7ad2...",
"name": "Amoxicillin 250 mg",
"prescribingDoctorId": "bb55...",
"refillQuantity": 1,
"refillPrn": false,
"isInitial": false,
"dateFilled": "2026-05-06T15:38:33Z",
"expirationDate": "2026-10-21T00:00:00Z",
"refillStatusId": "d6c5...",
"refillStatus": {
"abrv": "completed",
"name": "Completed",
"id": "d6c5..."
},
"requestedById": "9c0d...",
"dateCreated": "2026-05-06T15:38:28Z",
"dateUpdated": "2026-05-06T15:38:35Z"
}
],
"totalRecords": 3,
"page": 1,
"recordsPerPage": 10,
"sort": null,
"searchQuery": null,
"embed": "refillStatus",
"links": []
}
```
## See also
[Section titled “See also”](#see-also)
* [Conventions](/api-reference/conventions/) for pagination, embedding, sorting, and date filters.
* [Errors](/api-reference/errors/) for the error body shapes.
* [Products](/api-reference/resources/products/) for the catalog products prescriptions reference.
* [SOAP records](/api-reference/resources/soap-records/) for the visit records prescriptions can be created against.
* [Providers](/api-reference/resources/providers/) for the clinicians prescribing medications.
# Products
> The catalog of services and items a clinic sells.
A product is anything a clinic sells or charges for: vaccines, exams, surgical procedures, food, retail items, and any other line that can appear on an invoice. Products are organized into categories, can be grouped into bundles for common visit types, and are linked to tax rates that drive the line-item math on invoices.
Products are the catalog. Inventory tracks the physical stock of products; invoice items reference products to record what was sold.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Description |
| ------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id` | string | Server-assigned identifier. |
| `name` | string | Human-readable name (e.g. “Canine DA2PP vaccine”). |
| `customProductId` | string | Clinic’s own product code, used for easier search. |
| `price` | number | Default sale price. |
| `productCategoryId` | string | Category this product belongs to. `productCategory` expands it. |
| `productTypeId` | string | Product type reference. `productType` expands it. |
| `isTaxable` | boolean | Whether tax applies. There is no tax-rate reference on the product itself; see the product tax-rate sub-resources. |
| `isDiscountable` | boolean | Whether discounts may be applied. |
| `isControlled` | boolean | Whether this is a controlled substance. |
| `isActive` | boolean | Whether the product is currently sellable. |
| `dispensingFeeId` / `customDispensingFee` | string / number | Dispensing fee reference and per-product override. |
| `medicationProduct` / `vaccineProduct` / `serviceProduct` / `injectionProduct` | object | Type-specific detail blocks; only the one matching the product type is populated. |
| `inventoryProductSetting` | object | Stock-tracking settings for this product. |
| `includedOnInvoice` / `includedInMedicalRecord` | boolean | Whether the product appears on the invoice and in the medical record. |
| `dateCreated` | string | ISO 8601 UTC timestamp of creation. |
| `dateUpdated` | string | ISO 8601 UTC timestamp of last update. |
| `isDeleted` | boolean | Soft-delete flag. Note this is `isDeleted`, not `deleted`. |
## List / search
[Section titled “List / search”](#list--search)
POST `/pav2/open-api-products`
Standard collection envelope. Filter and page through the catalog with the usual pagination, sort, and embed conventions.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-products \
-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": 1,
"rpp": 100,
"sort": "name|asc"
}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-products",
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": 1, "rpp": 100, "sort": "name|asc"},
timeout=30,
)
resp.raise_for_status()
page = resp.json()
for p in page["item"]:
print(p["name"], p["price"])
```
* C#
```csharp
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 = 1,
rpp = 100,
sort = "name|asc",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-products", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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' => 1,
'rpp' => 100,
'sort' => 'name|asc',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-products', {
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: 1, rpp: 100, sort: 'name|asc' }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const p of page.item) console.log(p.name, p.price);
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "44de1c2e-18b4-4a91-a5c9-abc123456789",
"name": "Canine DA2PP vaccine",
"customProductId": "VAC-DA2PP",
"price": 38.00,
"productCategoryId": "c1aa3c4d-5e6f-789a-bcde-0123456789ab",
"productTypeId": "7b2e4f10-9c3a-4d51-8e6f-2a1b3c4d5e6f",
"productCategory": null,
"productType": null,
"isTaxable": true,
"isDiscountable": true,
"isControlled": false,
"isActive": true,
"includedOnInvoice": true,
"includedInMedicalRecord": true,
"vaccineProduct": null,
"medicationProduct": null,
"serviceProduct": null,
"dateCreated": "2025-09-10T16:55:01Z",
"dateUpdated": "2026-02-14T08:09:33Z",
"isDeleted": false
}
],
"totalRecords": 1284,
"page": 1,
"recordsPerPage": 100,
"sort": "name|asc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## Writing products
[Section titled “Writing products”](#writing-products)
The product catalog is **read only** through the public API. There is no create, update, or delete endpoint for products; the catalog is maintained by the clinic inside Shepherd, and integrations read it to resolve product IDs, pricing, and tax treatment.
Cache the catalog rather than re-reading it per transaction; it changes rarely. See [Lookups](/api-reference/resources/lookups/) for the caching approach.
## Sub-resources
[Section titled “Sub-resources”](#sub-resources)
The product catalog has several adjacent endpoints. Each follows the same request shape: POST, JSON body, the three auth headers, the standard pagination conventions.
| Endpoint | Purpose |
| ------------------------------------------ | ------------------------------------------------------------- |
| `POST /pav2/open-api-product-budle` | Bundles: pre-built groups of products for common visit types. |
| `POST /pav2/open-api-product-bundle-items` | Line items that make up each bundle. |
| `POST /pav2/open-api-product-categories` | Catalog categories used to organize products. |
| `POST /pav2/open-api-product-tax-rates` | Tax rates referenced by products and invoice items. |
## See also
[Section titled “See also”](#see-also)
* [Invoices](/api-reference/resources/invoices/) for how products end up on a bill.
* [Inventory](/api-reference/resources/inventory/) for stock tracking against the catalog.
* [Conventions](/api-reference/conventions/) for pagination, embedding, sorting, and date filters.
# Providers
> The clinicians who deliver care, plus scheduling templates and appointment types.
Providers are the people who deliver care at a clinic: veterinarians, vet techs, and other staff who can be assigned to appointments or attached to medical records. Each provider record carries their role and the availability windows that drive scheduling. Schedule templates sit alongside providers and define the appointment types, durations, and color-coding the clinic uses on its calendar.
Most scheduling integrations read providers to populate dropdowns, and read schedule templates to render the right slot length per appointment type.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Description |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Server-assigned identifier. |
| `name` | string | The provider’s display name. There are no separate `firstName` / `lastName` fields; `doctor` expands to the underlying user record. |
| `initials` | string | Provider’s initials. |
| `clinicId` | string | Clinic the provider belongs to. |
| `doctorId` | string | The related doctor/user record. `doctor` expands it. |
| `appointmentTypeIds` | array | Appointment types this provider offers (“Services Offered”). `appointmentTypes` expands them. |
| `isReliefDoctor` | boolean | Whether this provider is a relief doctor. |
| `isArchived` | boolean | Whether the provider is archived. Archived providers are not bookable; there is no `active` field. |
| `color` | string | Hex colour used for the provider on the calendar. |
| `sortOrder` | integer | Display order for provider lists. |
| `dateCreated` | string | ISO 8601 UTC timestamp of creation. |
| `dateUpdated` | string | ISO 8601 UTC timestamp of last update. |
## List providers
[Section titled “List providers”](#list-providers)
POST `/pav2/open-api-providers`
Returns the providers configured for the clinic identified by `X-Clinic-Id`. Availability is included on the record so most calendar UIs need a single round trip.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-providers \
-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":1,"rpp":100,"sort":"lastName|asc"}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-providers",
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": 1, "rpp": 100, "sort": "lastName|asc"},
timeout=30,
)
resp.raise_for_status()
for p in resp.json()["item"]:
print(p["lastName"], p["firstName"], p["role"])
```
* C#
```csharp
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 = 1,
rpp = 100,
sort = "lastName|asc",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-providers", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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' => 1,
'rpp' => 100,
'sort' => 'lastName|asc',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-providers', {
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: 1, rpp: 100, sort: 'lastName|asc' }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const p of page.item) console.log(p.lastName, p.firstName, p.role);
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "bb551122-18b4-4a91-a5c9-abc123456789",
"clinicId": "9890662f-52db-4a41-a5c1-b2e300d400b4",
"name": "Dr. Alex Rivera",
"initials": "AR",
"doctorId": "6a5b4c3d-2e1f-0a9b-8765-4321fedcba09",
"doctor": null,
"appointmentTypeIds": ["8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4"],
"appointmentTypes": null,
"isReliefDoctor": false,
"isArchived": false,
"color": "#2878FD",
"sortOrder": 1,
"dateCreated": "2025-07-01T13:21:09Z",
"dateUpdated": "2026-03-04T10:00:01Z"
}
],
"totalRecords": 12,
"page": 1,
"recordsPerPage": 100,
"sort": "lastName|asc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## Schedule templates
[Section titled “Schedule templates”](#schedule-templates)
POST `/pav2/open-api-schedule-templates`
Returns the appointment-type catalog used by the clinic calendar: each template carries a name, duration, color, and the rules that decide which providers it applies to. Combine providers and schedule templates to build a slot picker. The list is small and has no date filter: it accepts the standard `dateCreated` / `dateUpdated` pairs but does not apply them, so page it with `rpp` of 100 or less and cache it.
### Example
[Section titled “Example”](#example-1)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-schedule-templates \
-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":1,"rpp":100}'
```
* JavaScript
```js
const resp = await fetch(
'https://open-api.shepherd.vet/pav2/open-api-schedule-templates',
{
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: 1, rpp: 100 }),
},
);
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const t of page.item) {
console.log(t.name, t.durationMinutes);
}
```
## See also
[Section titled “See also”](#see-also)
* [Conventions](/api-reference/conventions/) for pagination, embedding, sorting, and date filters.
* [Lookups](/api-reference/resources/lookups/) for the enumerated values used elsewhere in scheduling.
* [Errors](/api-reference/errors/) for the error body shapes.
# Reminders
> Vaccine and follow-up reminders for clients and patients, plus the templates that drive them.
Reminders are the recurring nudges a clinic sends clients about upcoming vaccines, follow-up exams, refills, and other recurring care. Each reminder is tied to a client and patient and has a due date driven by an underlying reminder *setting* (the template that defined the cadence). Once a reminder fires it produces one or more reminder *notifications*, which are the per-channel messages (email, SMS, postcard) the clinic queues to send.
Communication and marketing integrations typically read reminders to know what’s coming due, and read notifications to know what was sent and when.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Notes |
| ------------------- | -------- | ---------------------------------------------------------------------------- |
| `id` | UUID | Server-assigned reminder identifier. |
| `clientId` | UUID | Client the reminder is for. |
| `patientId` | UUID | Patient the reminder is for. |
| `clinicId` | UUID | Clinic the reminder belongs to. |
| `reminderSettingId` | UUID | The template (cadence, message, channel set) that produced this reminder. |
| `dateDue` | ISO 8601 | When the underlying care is due (UTC). |
| `dateTriggered` | ISO 8601 | When the reminder fired and notifications were generated (UTC). |
| `isCompleted` | boolean | Whether the reminder has been satisfied (e.g. the vaccine was administered). |
| `isDeleted` | boolean | Soft-delete flag. |
| `dateCreated` | ISO 8601 | Server-assigned creation timestamp (UTC). |
| `dateUpdated` | ISO 8601 | Last server-side mutation (UTC). |
## List reminders
[Section titled “List reminders”](#list-reminders)
POST `/pav2/open-api-reminders`
Returns reminders for the clinic in `X-Clinic-Id`. Useful filters: `clientIds`, `patientIds`, `dateDueFrom` / `dateDueTo`, `isCompleted`, `isDeleted`. In a group with sharing enabled, set `clinicIds` to widen the query; `includePatientHomeClinic=true` also pulls reminders that belong to a patient’s home clinic.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-reminders \
-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":1,"rpp":100,"sort":"dateDue|asc","isCompleted":false,"dateDueFrom":"2026-05-28","dateDueTo":"2026-06-30"}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-reminders",
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": 1,
"rpp": 100,
"sort": "dateDue|asc",
"isCompleted": False,
"dateDueFrom": "2026-05-28",
"dateDueTo": "2026-06-30",
},
timeout=30,
)
resp.raise_for_status()
for r in resp.json()["item"]:
print(r["dateDue"], r["clientId"], r["patientId"])
```
* C#
```csharp
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 = 1,
rpp = 100,
sort = "dateDue|asc",
isCompleted = false,
dateDueFrom = "2026-05-28",
dateDueTo = "2026-06-30",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-reminders", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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' => 1,
'rpp' => 100,
'sort' => 'dateDue|asc',
'isCompleted' => false,
'dateDueFrom' => '2026-05-28',
'dateDueTo' => '2026-06-30',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-reminders', {
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: 1,
rpp: 100,
sort: 'dateDue|asc',
isCompleted: false,
dateDueFrom: '2026-05-28',
dateDueTo: '2026-06-30',
}),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const r of page.item) console.log(r.dateDue, r.clientId, r.patientId);
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "2f3a4b5c-...",
"clientId": "a1b2c3d4-...",
"patientId": "8c7d6e5f-...",
"clinicId": "f2a4c6e8-...",
"reminderSettingId": "7e8f9a0b-...",
"dateDue": "2026-06-12T00:00:00Z",
"dateTriggered": "2026-05-28T08:00:00Z",
"isCompleted": false,
"isDeleted": false,
"dateCreated": "2026-05-28T08:00:00Z",
"dateUpdated": "2026-05-28T08:00:00Z"
}
],
"totalRecords": 1,
"page": 1,
"recordsPerPage": 100,
"sort": "dateDue|asc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## Reminder notifications
[Section titled “Reminder notifications”](#reminder-notifications)
POST `/pav2/open-api-reminder-notifications`
The per-channel send records produced when a reminder fires: one notification per channel (email / SMS / postcard) per reminder. Use these to surface “what did the clinic send and when” in a marketing dashboard or to suppress duplicate sends from your own outbound stack.
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-reminder-notifications \
-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":1,"rpp":100,"sort":"dateCreated|desc"}'
```
## Reminder settings (templates)
[Section titled “Reminder settings (templates)”](#reminder-settings-templates)
POST `/pav2/open-api-reminder-settings`
POST `/pav2/open-api-reminder-notification-settings`
Reminder *settings* are the templates that drive how reminders are produced: which trigger (a vaccine product, an appointment type), what cadence, and which message goes out. The settings endpoint returns the template definitions; the notification-settings endpoint returns the per-channel rules (when to send the first nudge, the second, etc.). Read these to render a clinic’s reminder strategy in a configuration UI, or to map a reminder back to the rule that produced it.
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-reminder-settings \
-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":1,"rpp":100}'
```
## See also
[Section titled “See also”](#see-also)
* [Clients](/api-reference/resources/clients/) and [Patients](/api-reference/resources/patients/) for the ids on each reminder.
* [Products](/api-reference/resources/products/) for the vaccines and services that reminder settings typically trigger from.
* [Groups and multi-site](/guides/groups-and-multi-site/) for how reminders behave when sharing is enabled across a group.
* [Conventions](/api-reference/conventions/) for pagination, sorting, and date filters.
# SOAP records
> Clinical notes captured during a visit, organized as Subjective, Objective, Assessment, and Plan.
A **SOAP record** is the clinical note captured during a visit. SOAP stands for **Subjective, Objective, Assessment, Plan**: the four sections veterinarians use to structure their findings, from the owner’s reported history through the physical exam to the diagnosis and treatment plan.
In Shepherd, a SOAP record is typically created against an appointment ID; the appointment is the calendar anchor, the SOAP record is the clinical content. The SOAP root record carries the metadata (patient, provider, appointment, signed status); the four narrative sections plus vitals, imaging, discharge instructions, and notes are managed through dedicated sub-resource endpoints.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Description |
| ----------------------------------------------------------- | ------- | -------------------------------------------------------- |
| `id` | string | Unique identifier for the SOAP record. |
| `patientId` | string | The patient (pet) seen. |
| `title` | string | Short descriptive title used in the chart timeline. |
| `soapStatusId` | string | Current status of the record. |
| `supervisingDoctorId` | string | The supervising doctor. |
| `createdByUserId` | string | The user who created the record. |
| `soapAssignedUsers` | array | Users assigned to the record. |
| `locationId` | string | Where in the clinic the patient is. |
| `invoiceId` | string | The invoice this visit was billed to, when there is one. |
| `dateCheckedIn` | string | ISO 8601 UTC check-in time. |
| `patient` / `location` / `soapStatus` / `supervisingDoctor` | object | Expanded related records. `null` unless embedded. |
| `dateCreated` | string | ISO 8601 UTC timestamp of creation. |
| `dateUpdated` | string | ISO 8601 UTC timestamp of last update. |
| `dateDeleted` | string | When the record was deleted, if it was. |
| `deleted` | boolean | Soft-delete flag. |
## List / search
[Section titled “List / search”](#list--search)
POST `/pav2/open-api-soaps`
Returns a paginated collection of SOAP records for the clinic. Filter by `patientIds` (a comma-separated list, so it takes one or many) to pull a chart history for a single pet, or by the `dateCreatedFrom` / `dateCreatedTo` pair (max 1-month range) for time-series analysis. Use `embed` to inline related records, for example `embed: "patient,appointment"`.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-soaps \
-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": 1,
"rpp": 25,
"sort": "dateCreated|desc",
"patientIds": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
"embed": "patient,appointment"
}'
```
* Python
```python
import os
import requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-soaps",
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": 1,
"rpp": 25,
"sort": "dateCreated|desc",
"patientIds": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
"embed": "patient,appointment",
},
timeout=30,
)
resp.raise_for_status()
for soap in resp.json()["item"]:
print(soap["id"], soap["title"], soap["signed"])
```
* C#
```csharp
using System.Net.Http;
using System.Net.Http.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Integration-Public-Key", Environment.GetEnvironmentVariable("SHEPHERD_PUBLIC_KEY"));
http.DefaultRequestHeaders.Add("X-Integration-Private-Key", Environment.GetEnvironmentVariable("SHEPHERD_PRIVATE_KEY"));
http.DefaultRequestHeaders.Add("X-Clinic-Id", Environment.GetEnvironmentVariable("SHEPHERD_CLINIC_ID"));
var response = await http.PostAsJsonAsync(
"https://open-api.shepherd.vet/pav2/open-api-soaps",
new
{
page = 1,
rpp = 25,
sort = "dateCreated|desc",
patientIds = "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
embed = "patient,appointment",
});
response.EnsureSuccessStatusCode();
```
* PHP
```php
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' => 1,
'rpp' => 25,
'sort' => 'dateCreated|desc',
'patientIds' => 'a1b2c3d4-e5f6-7890-abcd-ef0123456789',
'embed' => 'patient,appointment',
]),
]);
$payload = json_decode(curl_exec($ch), true);
curl_close($ch);
```
* JavaScript
```js
const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-soaps', {
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: 1,
rpp: 25,
sort: 'dateCreated|desc',
patientIds: 'a1b2c3d4-e5f6-7890-abcd-ef0123456789',
embed: 'patient,appointment',
}),
});
if (!response.ok) {
throw new Error(`Shepherd API ${response.status}: ${await response.text()}`);
}
const payload = await response.json();
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "3f9a1c2e-18b4-4a91-a5c9-abc123456789",
"patientId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
"title": "Annual wellness exam",
"soapStatusId": "9f8e7d6c-5b4a-3210-a9f8-fedcba098765",
"supervisingDoctorId": "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219",
"createdByUserId": "6a5b4c3d-2e1f-0a9b-8765-4321fedcba09",
"soapAssignedUsers": [],
"locationId": "1a2b3c4d-5e6f-789a-bcde-0123456789ab",
"invoiceId": "8b1f2c3d-4e5f-6789-abcd-ef0123456789",
"dateCheckedIn": "2026-05-22T14:30:00Z",
"patient": null,
"location": null,
"soapStatus": null,
"clinicId": "9890662f-52db-4a41-a5c1-b2e300d400b4",
"dateCreated": "2026-05-22T14:35:00Z",
"dateUpdated": "2026-05-22T15:42:00Z",
"dateDeleted": null,
"deleted": false
}
],
"totalRecords": 12,
"page": 1,
"recordsPerPage": 25,
"sort": "dateCreated|desc",
"searchQuery": null,
"embed": "patient,appointment",
"links": []
}
```
## Writing SOAP records
[Section titled “Writing SOAP records”](#writing-soap-records)
A SOAP record itself is **read only** through the public API: there is no endpoint that creates, updates, or deletes a SOAP. Clinical documentation is authored by clinicians inside Shepherd, and integrations read the resulting records.
Two pieces of a visit can be written:
| Endpoint | Purpose |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /pav2/open-api-soap-vital-entries/write` | Record a vitals entry against a visit. |
| `POST /pav2/open-api-soap-imaging/file-presigned-upload-url` then `POST /pav2/open-api-soap-imaging/file-entry-write` | Attach an imaging file, using the same three-step presigned-upload flow as [patient files](/api-reference/resources/patients/#file-uploads). |
Everything else in the SOAP structure (subjective, objective/physical exam, assessment, plan) is read only.
## Sub-resources
[Section titled “Sub-resources”](#sub-resources)
The four SOAP sections plus the related clinical content each live on their own endpoints, following the same list / write conventions as the parent resource. Pass the parent `soapId` when writing.
| Endpoint | Purpose |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/pav2/open-api-soap-subjectives` | The Subjective section: owner-reported history and presenting complaint. |
| `/pav2/open-api-physical-exams` | The Objective section: physical-exam findings by body system. |
| `/pav2/open-api-soap-assessments` | The Assessment section: diagnoses and differential list. |
| `/pav2/open-api-soap-plan/note` | Free-form notes on the Plan section. |
| `/pav2/open-api-soap-plan/recommendation` | Recommendations recorded on the Plan section. |
| `/pav2/open-api-soap-plan/treatment` | The plan’s treatment line items; covered in detail on [Treatments](/api-reference/resources/treatments/), including the `dose` vs `quantity` semantics. |
| `/pav2/open-api-soap-plan/treatment-note` | Notes attached to individual treatments. |
| `/pav2/open-api-soap-vital-entries` | Vitals captured during the visit (temperature, heart rate, weight, etc.). |
| `/pav2/open-api-soap-imaging-notes` | Notes on imaging studies attached to the SOAP record. |
| `/pav2/open-api-soap-imaging/file-presigned-upload-url` | Step 1 of an imaging file upload: request a presigned S3 URL. |
| `/pav2/open-api-soap-imaging/file-entry-write` | Step 3 of an imaging file upload: register the uploaded file. |
| `/pav2/open-api-soap-discharge-instructions` | Discharge instructions printed for the client. |
| `/pav2/open-api-soap-assessment-notes` | Notes attached to the Assessment section. |
| `/pav2/open-api-soap-assessment-diagnosis-description` | Diagnosis descriptions on the Assessment section. |
Physical exams and discharge instructions are large records, about 12 KB to 20 KB each, so a 1000-record page is over 10 MB. Keep `rpp` at 100 or less on those two. On physical exams, filter by date with the standard `dateCreatedFrom` / `dateCreatedTo`: the endpoint also lists `creationDateFrom` / `creationDateTo`, but does not apply them.
## See also
[Section titled “See also”](#see-also)
* [Conventions](/api-reference/conventions/): pagination, embed, sort, and date-range rules.
* [Treatments](/api-reference/resources/treatments/): the plan’s treatment line items and what `dose` and `quantity` mean.
* [Appointments](/api-reference/resources/appointments/): the calendar anchor most SOAP records are written against.
* [Patients](/api-reference/resources/patients/): the pet whose chart the SOAP record joins.
* [Errors](/api-reference/errors/): HTTP status codes and the error body shapes.
# Tasks
> Staff to-dos in Shepherd. List, create, update, and attach notes to task entries.
Tasks (called *task entries* in the data model) are the to-do items clinic staff use to track follow-ups: “call the owner about lab results”, “verify the controlled-substance log”, “prep for tomorrow’s surgery”. A task has a due date, a priority, an assignee (a user or a team), and an optional client and patient context. Integrations create tasks when their workflow needs a human handoff inside Shepherd.
Tasks are clinic-scoped even in a multi-site group: they’re created at one clinic and stay there. In a group with sharing enabled, they can be read and updated from any clinic in the group.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Notes |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `id` | UUID | Server-assigned identifier. |
| `clinicId` | UUID | Clinic the task was created at. |
| `name` | string | Short title shown in the UI list. |
| `description` | string | Rich-text body (HTML). |
| `dateDue` | ISO 8601 | When the task is due (UTC). Required on create. |
| `taskEntryPriorityStatusId` | UUID | Priority (low / normal / high / urgent). See [Lookups](/api-reference/resources/lookups/). |
| `taskEntryStatusId` | UUID | Status (pending / in progress / completed). See [Lookups](/api-reference/resources/lookups/). |
| `clientId` | UUID | Client context, optional. |
| `patientId` | UUID | Patient context, optional. Must belong to `clientId` if both are set. |
| `taskAssignedToUsers` | array | Users the task is assigned to. Mutually exclusive with team assignment. |
| `taskAssignedToTeams` | array | Teams the task is assigned to. Mutually exclusive with user assignment. |
| `taskNotes` | array | Free-text notes attached to the task (see notes endpoint below). |
| `completedByUserId` | UUID | User who marked the task complete, if any. |
| `isDeleted` | boolean | Soft-delete flag. |
| `dateCreated` | ISO 8601 | Server-assigned creation timestamp (UTC). |
| `dateUpdated` | ISO 8601 | Last server-side mutation (UTC). |
## List tasks
[Section titled “List tasks”](#list-tasks)
POST `/pav2/open-api-task-entries`
Returns tasks at the clinic identified by `X-Clinic-Id`. Common filters: `searchQuery` (matches name, description, attached client and patient names), `assignedToUserIds`, `taskEntryStatusIds`, `taskEntryPriorityStatusIds`, `clientIds`, `patientIds`, and `dueDateFrom` / `dueDateTo`. In a group with sharing enabled, `clinicIds` widens to other clinics.
Use `embed=taskEntryPriorityStatus,taskEntryStatus` to inline the lookup objects on each task, saving a follow-up round trip.
Bound every list: a due-date or `dateUpdated` window of one calendar month or less, or an id filter such as `assignedToUserIds` or `clientIds`. Deleted tasks are included unless you send `"isDeleted": false`. The example below lists tasks due in the coming week.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-task-entries \
-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":1,"rpp":50,"sort":"dateDue|asc","embed":"taskEntryPriorityStatus,taskEntryStatus","isDeleted":false,"dueDateFrom":"2026-05-28T00:00:00Z","dueDateTo":"2026-06-04T00:00:00Z"}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-task-entries",
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": 1,
"rpp": 50,
"sort": "dateDue|asc",
"embed": "taskEntryPriorityStatus,taskEntryStatus",
"isDeleted": False,
"dueDateFrom": "2026-05-28T00:00:00Z",
"dueDateTo": "2026-06-04T00:00:00Z",
},
timeout=30,
)
resp.raise_for_status()
for t in resp.json()["item"]:
print(t["dateDue"], t["name"], t["taskEntryStatus"]["name"])
```
* C#
```csharp
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 = 1,
rpp = 50,
sort = "dateDue|asc",
embed = "taskEntryPriorityStatus,taskEntryStatus",
isDeleted = false,
dueDateFrom = "2026-05-28T00:00:00Z",
dueDateTo = "2026-06-04T00:00:00Z",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-task-entries", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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' => 1,
'rpp' => 50,
'sort' => 'dateDue|asc',
'embed' => 'taskEntryPriorityStatus,taskEntryStatus',
'isDeleted' => false,
'dueDateFrom' => '2026-05-28T00:00:00Z',
'dueDateTo' => '2026-06-04T00:00:00Z',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch(
'https://open-api.shepherd.vet/pav2/open-api-task-entries',
{
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: 1,
rpp: 50,
sort: 'dateDue|asc',
embed: 'taskEntryPriorityStatus,taskEntryStatus',
isDeleted: false,
dueDateFrom: '2026-05-28T00:00:00Z',
dueDateTo: '2026-06-04T00:00:00Z',
}),
},
);
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const t of page.item) console.log(t.dateDue, t.name, t.taskEntryStatus.name);
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "e8a1d2c3-...",
"clinicId": "f2a4c6e8-...",
"name": "Call owner about lab results",
"description": "Follow up on the CBC from yesterday's visit.
",
"dateDue": "2026-05-29T17:00:00Z",
"clientId": "a1b2c3d4-...",
"patientId": "8c7d6e5f-...",
"taskEntryPriorityStatusId": "9c8d7e6f-...",
"taskEntryStatusId": "f6e5d4c3-...",
"taskAssignedToUsers": [
{ "user": { "firstName": "Alex", "lastName": "Rivera" } }
],
"taskAssignedToTeams": [],
"taskNotes": [],
"completedByUserId": null,
"isDeleted": false,
"dateCreated": "2026-05-28T13:21:09Z",
"dateUpdated": "2026-05-28T13:21:09Z"
}
],
"totalRecords": 1,
"page": 1,
"recordsPerPage": 50,
"sort": "dateDue|asc",
"searchQuery": null,
"embed": "taskEntryPriorityStatus,taskEntryStatus",
"links": []
}
```
## Create a task
[Section titled “Create a task”](#create-a-task)
POST `/pav2/open-api-task-entries/write`
Creates a new task. `name`, `dateDue`, and `taskEntryPriorityStatusId` are required. A task may be assigned to **either** users or teams, not both: send `assignedToUsersIds` *or* `assignedToTeamsIds`, not the two together. If you set `patientId`, you must also set `clientId`, and the patient must belong to that client.
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-task-entries/write \
-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 '{
"name": "Call owner about lab results",
"description": "Follow up on the CBC from yesterday's visit.
",
"dateDue": "2026-05-29T17:00:00Z",
"taskEntryPriorityStatusId": "",
"clientId": "",
"patientId": "",
"assignedToUsersIds": [""]
}'
```
The server returns the created task as the response body, with `id` populated. Creates are not idempotent: a retried create makes a second task, so never retry one automatically after a timeout or a `5xx`.
## Update a task
[Section titled “Update a task”](#update-a-task)
PUT `/pav2/open-api-task-entries/update/{id}`
This is **not a partial update**, even though a few fields survive omission. What happens to each field you leave out of the body:
| Kept when omitted | Cleared when omitted |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `taskEntryPriorityStatusId`, `taskEntryStatusId`, `dateDue` | `name`, `description`, `clientId`, `patientId`, `assignedToUsersIds`, `assignedToTeamsIds` |
So a body that only changes the status wipes the task’s title, description, client and patient context, and assignees. To change one thing, read the task first, embedding its assignments, and resend everything:
1. Read it: `POST /pav2/open-api-task-entries` with `{"ids": "", "rpp": 1, "embed": "taskAssignedToUsers,taskAssignedToTeams"}`.
2. Build the update body from that record: `name`, `description`, `clientId`, `patientId`, `dateDue`, `taskEntryPriorityStatusId`, `taskEntryStatusId`, plus `assignedToUsersIds` from `taskAssignedToUsers[].user.id` or `assignedToTeamsIds` from `taskAssignedToTeams[].team.id`.
3. Apply your change and send the whole body.
To mark a task complete, set `taskEntryStatusId` to the completed status from the status lookup. The same assignment rule applies on update: users or teams, not both. Note the route puts `update` **before** the id.
```sh
curl -X PUT https://open-api.shepherd.vet/pav2/open-api-task-entries/update/ \
-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 '{
"name": "Call owner about lab results",
"description": "Follow up on the CBC from yesterday's visit.
",
"dateDue": "2026-05-29T17:00:00Z",
"taskEntryPriorityStatusId": "",
"taskEntryStatusId": "",
"clientId": "",
"patientId": "",
"assignedToUsersIds": [""]
}'
```
Returns `200 OK` with an empty body. There is no concurrency check: if someone edits the task between your read and your write, your write wins.
## Task notes
[Section titled “Task notes”](#task-notes)
POST `/pav2/open-api-task-notes`
POST `/pav2/open-api-task-notes/write`
PUT `/pav2/open-api-task-notes/update/{id}`
Task notes are free-text comments attached to a task. List them by the standard search-filter pattern, create with `/write`, update with `/update/{id}`. The note carries a `taskEntryId` linking back to its parent. On update, only `note` can change; send it in full. The note update returns `204 No Content`.
## Priority lookup
[Section titled “Priority lookup”](#priority-lookup)
POST `/pav2/open-api-task-entry-priority-statuses`
Returns the priority catalog (low / normal / high / urgent) with the ids you pass to `taskEntryPriorityStatusId`. Also discoverable through [Lookups](/api-reference/resources/lookups/).
## See also
[Section titled “See also”](#see-also)
* [Users](/api-reference/resources/users/) for the assignee ids that go into `assignedToUsersIds`.
* [Clients](/api-reference/resources/clients/) and [Patients](/api-reference/resources/patients/) for the context ids on a task.
* [Conventions](/api-reference/conventions/) for pagination, embedding, sorting, and date filters.
* [Errors](/api-reference/errors/) for the error body shapes.
# Treatments
> Treatment line items on the plan section of a SOAP record, including what dose and quantity mean and when each applies.
A **treatment** is a line item on the Plan section of a [SOAP record](/api-reference/resources/soap-records/): a medication administered, a procedure performed, a lab run, or a supply dispensed during a visit. Treatments are where the medical record meets the invoice; each one documents what happened clinically and also produces the invoice line the client is charged for. That dual role is why a treatment carries two amount fields, `dose` and `quantity`, which answer different questions (see [`dose` vs `quantity`](#dose-vs-quantity) below).
Treatments are read-only through the API: clinic staff create them in Shepherd as part of the SOAP workflow. Use them to reconstruct what was done during a visit, feed medical-records integrations, or reconcile clinical activity against invoices.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Notes |
| ------------------------- | -------- | --------------------------------------------------------------------------------- |
| `id` | UUID | Server-assigned identifier. |
| `soapPlanId` | UUID | The Plan section this treatment belongs to. |
| `name` | string | Treatment name as it appears on the plan. |
| `productId` | UUID | Catalog product or service behind the line item. |
| `productCategoryId` | UUID | Catalog category lookup. |
| `dose` | decimal | Clinical amount administered. Null or 0 when no dosage was calculated; see below. |
| `quantity` | decimal | Billable units charged on the invoice. |
| `concentration` | decimal | Concentration used by the dosage calculator, where applicable. |
| `price` | decimal | Unit price. |
| `dispensingFee` | decimal | Dispensing fee applied to the line item. |
| `invoiceItemId` | UUID | Invoice line item this treatment produced. |
| `includedInMedicalRecord` | boolean | Whether the treatment appears in the medical record. |
| `includedOnInvoice` | boolean | Whether the treatment appears on the invoice. |
| `isControlled` | boolean | Controlled-substance flag. |
| `isDeclined` | boolean | True when the client declined the treatment (`dateDeclined` carries when). |
| `timeAdministered` | ISO 8601 | When the treatment was administered. |
| `administeredById` | UUID | Team member who administered it. |
| `additionalInstruction` | string | Free-text instructions attached to the line item. |
| `lotNumber` | string | Lot number, where tracked. |
| `dateCreated` | ISO 8601 | Server-assigned creation timestamp (UTC). |
| `dateUpdated` | ISO 8601 | Last server-side mutation (UTC). |
| `deleted` | boolean | Soft-delete flag. |
## List / search
[Section titled “List / search”](#list--search)
POST `/pav2/open-api-soap-plan/treatment`
Standard collection envelope. Filter with comma-separated ID lists (`patientIds`, `productIds`, `soapPlanIds`, `clientIds`), or by the `dateCreatedFrom` / `dateCreatedTo` pair for time-series pulls; `searchQuery` matches on patient name. Page through results with `page` and `rpp`.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-soap-plan/treatment \
-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 '{
"patientIds": "12ab...",
"page": 1,
"rpp": 50,
"sort": "dateCreated|desc"
}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-soap-plan/treatment",
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={"patientIds": "12ab...", "page": 1, "rpp": 50, "sort": "dateCreated|desc"},
timeout=30,
)
resp.raise_for_status()
for treatment in resp.json()["item"]:
print(treatment["name"], treatment["dose"], treatment["quantity"])
```
* C#
```csharp
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 {
patientIds = "12ab...",
page = 1,
rpp = 50,
sort = "dateCreated|desc",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-soap-plan/treatment", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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([
'patientIds' => '12ab...',
'page' => 1,
'rpp' => 50,
'sort' => 'dateCreated|desc',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch(
'https://open-api.shepherd.vet/pav2/open-api-soap-plan/treatment',
{
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({ patientIds: '12ab...', page: 1, rpp: 50, sort: 'dateCreated|desc' }),
},
);
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const treatment of page.item) {
console.log(treatment.name, treatment.dose, treatment.quantity);
}
```
### Response
[Section titled “Response”](#response)
Note the two line items below: the injectable was run through the dosage calculator, so it carries a clinical `dose` alongside its billable `quantity`; the catheter placement is a procedure, so `dose` is null and only `quantity` is populated. Both shapes are normal.
```json
{
"item": [
{
"id": "13f7...",
"soapPlanId": "ba0e...",
"name": "Buprenorphine 0.3 mg/mL injectable",
"productId": "98f4...",
"productCategoryId": "45e7...",
"dose": 0.6,
"quantity": 1,
"concentration": 0.3,
"price": 42,
"dispensingFee": 0,
"invoiceItemId": "db24...",
"includedInMedicalRecord": true,
"includedOnInvoice": true,
"isControlled": true,
"isDeclined": false,
"timeAdministered": "2026-06-12T10:25:45Z",
"administeredById": "9baf...",
"additionalInstruction": "",
"lotNumber": null,
"dateCreated": "2026-06-12T10:25:30Z",
"dateUpdated": "2026-06-12T10:25:48Z",
"deleted": false
},
{
"id": "20aa...",
"soapPlanId": "ba0e...",
"name": "IV catheter placement",
"productId": "77cd...",
"productCategoryId": "45e7...",
"dose": null,
"quantity": 1,
"concentration": 0,
"price": 68,
"dispensingFee": 0,
"invoiceItemId": "db31...",
"includedInMedicalRecord": true,
"includedOnInvoice": true,
"isControlled": false,
"isDeclined": false,
"timeAdministered": "2026-06-12T10:12:02Z",
"administeredById": "9baf...",
"additionalInstruction": "",
"lotNumber": null,
"dateCreated": "2026-06-12T10:11:50Z",
"dateUpdated": "2026-06-12T10:12:10Z",
"deleted": false
}
],
"totalRecords": 2,
"page": 1,
"recordsPerPage": 50,
"sort": "dateCreated|desc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## `dose` vs `quantity`
[Section titled “dose vs quantity”](#dose-vs-quantity)
The two fields answer different questions:
* **`dose` is the clinical amount.** The exact volume or count prescribed or administered to the patient (1.5 mL, 2 tablets, 50 mg). It is a purely medical metric and belongs in medical records and discharge instructions.
* **`quantity` is the billable units.** The inventory and financial units charged on the invoice. If a clinic dispenses an entire bottle or charges a flat rate for a service, `quantity` is 1 even when the clinical dose administered was a specific fluid volume.
`quantity` is the authoritative field for billing and invoicing: it is what lands on the invoice line and what is subtracted from stock, multiplied by the unit price.
### When `dose` is null or 0
[Section titled “When dose is null or 0”](#when-dose-is-null-or-0)
A null or 0 `dose` alongside a populated `quantity` is expected behavior, not missing data. It happens whenever the line item was never run through the clinical dosage calculator:
* **Services and procedures.** Catheter placements, lab tests, imaging: no chemical dose exists, but a `quantity` of 1 is billed.
* **Flat-fee and pre-packaged medications.** Euthanasia solutions, standard vaccines, or pre-filled syringes that the clinic inventories and bills as a single flat item rather than by measured volume.
* **Medical supplies.** Consumables like bandages, syringes, or disposal fees only ever populate `quantity`.
* **Manual entry.** A clinician added the product to the plan with a billing quantity but skipped the dosage calculator.
* **Non-weight-dependent items.** Anything not dosed against the patient’s weight is frequently tracked strictly by inventory count.
### Which field to use
[Section titled “Which field to use”](#which-field-to-use)
| If you are building | Use |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Medical records, discharge instructions, client-facing summaries | `dose`, with a fallback: when `dose` is null or 0, display `quantity` plus the product’s unit of measure so the user never sees a blank. |
| Billing, invoicing, or inventory reconciliation | `quantity`, always. |
Caution
Do not treat `dose` as a substitute for `quantity` or vice versa. Integrations that read `dose` as “the amount” will show blanks for procedures, supplies, and flat-fee items; integrations that bill from `dose` will drift from the actual invoice.
## Related endpoints
[Section titled “Related endpoints”](#related-endpoints)
| Endpoint | Purpose |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `/pav2/open-api-soap-plan/treatment-note` | Notes attached to individual treatments; embed `soapTreatment` to inline the parent line item. |
| `/pav2/open-api-soap-plan/recommendation` | Recommendations recorded on the plan. |
| `/pav2/open-api-soap-plan/note` | Free-form notes on the plan section. |
## See also
[Section titled “See also”](#see-also)
* [SOAP records](/api-reference/resources/soap-records/): the parent visit record and its other sub-resources.
* [Products](/api-reference/resources/products/): the catalog items behind treatment line items, including units of measure.
* [Invoices](/api-reference/resources/invoices/): where treatment `quantity` lands as an invoice line.
* [Conventions](/api-reference/conventions/): pagination, embed, sort, and date-range rules.
* [Errors](/api-reference/errors/): HTTP status codes and the error body shapes.
# Users
> Staff identity in Shepherd. Distinct from Providers.
Users are the staff identities in Shepherd: the people who sign in, get assigned tasks, and appear as the actor on audit fields like `processedByUserId`, `completedByUserId`, or `createdByUserId`. Each user has a name, a username, a role, and a clinic association.
Users vs Providers
**Users** are the staffing and auth surface: everyone with an account at the clinic, including receptionists and technicians as well as veterinarians. **Providers** are the medical-and-billable subset: clinicians who can be assigned to appointments, attached to SOAP records, and listed as the rendering provider on invoices. A veterinarian is usually both, but the records are distinct. For booking, scheduling, or rendering-provider lookups, use [Providers](/api-reference/resources/providers/). For “who recorded this payment” or “assign this task to a user”, use Users.
## Schema
[Section titled “Schema”](#schema)
Authoritative schemas live in the [live Swagger UI](https://app.shepherd.vet/swagger/). The fields below are a representative subset for orientation.
| Field | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `id` | string | Server-assigned user identifier. The same id appears on audit fields elsewhere in the API. |
| `userId` | string | The underlying user identifier. |
| `coreUser` | object | The user’s core record: name and contact details. There are no flat `firstName` / `lastName` fields on this model. |
| `roles` | array | The user’s roles. |
| `clinicUser` | array | Per-clinic user records, for users who work across a group. |
| `prefix` | string | Name prefix (e.g. `Dr.`), when set. |
| `suffix` | string | Name suffix (e.g. `DVM`), when set. |
| `licenseNumber` | string | The user’s license number. |
| `userLicenseTypeId` | string | License type reference. `userLicenseType` expands it. |
| `dateCreated` | string | ISO 8601 UTC timestamp of creation. |
| `dateUpdated` | string | ISO 8601 UTC timestamp of last update. |
## List users
[Section titled “List users”](#list-users)
POST `/pav2/open-api-users`
Returns the users at the clinic identified by `X-Clinic-Id`. Use a search query to look up a user by name, or filter by role.
### Example
[Section titled “Example”](#example)
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-users \
-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":1,"rpp":100,"sort":"lastName|asc"}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-users",
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": 1, "rpp": 100, "sort": "lastName|asc"},
timeout=30,
)
resp.raise_for_status()
for u in resp.json()["item"]:
print(u["lastName"], u["firstName"], u.get("roleName"))
```
* C#
```csharp
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 = 1,
rpp = 100,
sort = "lastName|asc",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-users", body);
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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' => 1,
'rpp' => 100,
'sort' => 'lastName|asc',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-users', {
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: 1, rpp: 100, sort: 'lastName|asc' }),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const page = await resp.json();
for (const u of page.item) console.log(u.lastName, u.firstName, u.roleName);
```
### Response
[Section titled “Response”](#response)
```json
{
"item": [
{
"id": "bb551122-18b4-4a91-a5c9-abc123456789",
"userId": "6a5b4c3d-2e1f-0a9b-8765-4321fedcba09",
"coreUser": null,
"roles": [],
"clinicUser": [],
"prefix": "Dr.",
"suffix": "DVM",
"licenseNumber": "TX-12345",
"userLicenseTypeId": "2f4a6b8c-1d3e-5f70-9a2b-4c6d8e0f1a2b",
"userLicenseType": null,
"dateCreated": "2025-07-01T13:21:09Z",
"dateUpdated": "2026-03-04T10:00:01Z"
}
],
"totalRecords": 8,
"page": 1,
"recordsPerPage": 100,
"sort": "lastName|asc",
"searchQuery": null,
"embed": null,
"links": []
}
```
## Clinic users
[Section titled “Clinic users”](#clinic-users)
POST `/pav2/open-api-clinic-users`
Returns the clinic-membership records that join a user to a clinic, plus per-clinic settings (e.g. `isTimeClockEnabled`, license fields). Use this when you need to know *which* clinic a user belongs to in a multi-site account, or to surface clinic-scoped flags. For names, role, and approval status, the `/open-api-users` endpoint above is usually enough.
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-clinic-users \
-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":1,"rpp":100}'
```
## See also
[Section titled “See also”](#see-also)
* [Providers](/api-reference/resources/providers/) for the bookable, medical-and-billable subset of users.
* [Tasks](/api-reference/resources/tasks/) for assigning work to users by id.
* [Conventions](/api-reference/conventions/) for pagination, sorting, and date filters.
* [Groups and multi-site](/guides/groups-and-multi-site/) for how clinic-user records change in shared-data groups.
# Contact
> Reach the Shepherd developer team for API questions, access requests, partnership interest, or feedback.
Questions, access requests, partnership interest, or feedback: here’s how to reach us.
## Email us
[Section titled “Email us”](#email-us)
Pick the address that fits; it routes to the right people.
| You want to… | Contact |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Ask an API or integration question (vendors and partners) | |
| Ask about your own account’s API access or keys | |
| Explore a new integration partnership | [Vendor integration form](https://meowing-player-54b.notion.site/230ae122a6b680939e27fe513dc6d6c0) |
| Get help using the Shepherd app (reports, exports, settings, backups) | [Shepherd Help Center](https://help.shepherd.vet/) |
Running a clinic and new to the Open API? Start with [Open API 101](/getting-started/openapi-101/). New integration partner? Start with [Integration onboarding](/getting-started/integration-onboarding/) for the full process.
# FAQ
> Quick answers to common questions about building on the Shepherd API.
Short answers to the questions we hear most, each linking to the page with the full story. This list grows as patterns emerge from developer questions.
## I run a clinic and I’m not technical. Where do I start?
[Section titled “I run a clinic and I’m not technical. Where do I start?”](#i-run-a-clinic-and-im-not-technical-where-do-i-start)
With [Open API 101](/getting-started/openapi-101/). It explains in plain English what the Open API is, what clinics use it for, what data it covers, and who you need on your side to put it to work. For help with the Shepherd app itself, see the [Shepherd Help Center](https://help.shepherd.vet/).
## Can I use the API to back up all my clinic’s data?
[Section titled “Can I use the API to back up all my clinic’s data?”](#can-i-use-the-api-to-back-up-all-my-clinics-data)
Partly, but the Open API isn’t a complete backup: it covers much of your practice data, not all of it. Shepherd already backs up your data continuously; the Help Center’s [Data Backup & Recovery](https://help.shepherd.vet/en/articles/14183746-data-backup-recovery) article explains how, and how to ask support for an export of your practice data. See [Open API 101](/getting-started/openapi-101/#can-i-use-it-to-keep-my-own-backup) for the options.
## How do I get API keys?
[Section titled “How do I get API keys?”](#how-do-i-get-api-keys)
It depends who you are. Clinic accounts with the open API feature can generate keys themselves in Shepherd (Admin → Integrations). Integration partners get keys from the Shepherd product team during onboarding. See [Authentication](/getting-started/authentication/) and, for partners, [Integration onboarding](/getting-started/integration-onboarding/).
## How much does API access cost?
[Section titled “How much does API access cost?”](#how-much-does-api-access-cost)
Open API access is **$35 per clinic site, per month**, billed to the practice that enables it. Reading these docs is free; the fee applies once a clinic turns the feature on and starts using keys. See [Pricing & access](/getting-started/pricing/) for the full picture, including what’s required to get keys.
## I’m a new clinic still onboarding. Can I build at the same time?
[Section titled “I’m a new clinic still onboarding. Can I build at the same time?”](#im-a-new-clinic-still-onboarding-can-i-build-at-the-same-time)
Yes. You can start exploring the API while you onboard, but the integration work runs on its own track: it doesn’t pause or extend your standard onboarding timeline, and you’re still expected to go live on your normal schedule. Talk to your account manager about timing. See [Pricing & access](/getting-started/pricing/).
## Is there a sandbox?
[Section titled “Is there a sandbox?”](#is-there-a-sandbox)
Yes. Build and test against `https://demo-open-api.shepherd.vet/pav2/`. Integration partners get a demo clinic to work in; clinic accounts can request a sandbox if they want one separate from their live clinic.
## Does the API support webhooks?
[Section titled “Does the API support webhooks?”](#does-the-api-support-webhooks)
Not yet. The API is polling-based: pull changes on a schedule using date filters (see [Conventions](/api-reference/conventions/)), and mind the [rate limits](/api-reference/rate-limits/).
## How do I work with multi-location clients?
[Section titled “How do I work with multi-location clients?”](#how-do-i-work-with-multi-location-clients)
Many operators run several clinics as a group, which can share data across locations. Check whether an account is multi-site and handle shared records correctly: see [Groups and multi-site](/guides/groups-and-multi-site/).
## What are the rate limits?
[Section titled “What are the rate limits?”](#what-are-the-rate-limits)
See [Rate limits](/api-reference/rate-limits/) for the current per-minute and per-hour ceilings and how throttling is signaled.
## How do I report a bug or request a feature?
[Section titled “How do I report a bug or request a feature?”](#how-do-i-report-a-bug-or-request-a-feature)
Use the [Contact](/contact/) page: it has the right email for your question.
# Authentication
> How to obtain credentials and authenticate requests to the Shepherd API.
The Shepherd API authenticates with **two API keys plus a clinic identifier**, all sent as request headers on every call. There is no OAuth flow and no Bearer token. This page orients you; the [full authentication reference](/api-reference/authentication/) has the header table, key rotation, the per-clinic scope model, and a working “hello world” in all five supported languages.
## How you get keys
[Section titled “How you get keys”](#how-you-get-keys)
It depends who you are:
* **Clinic accounts building on their own data** self-serve keys from inside Shepherd (Admin → Integrations), once the open API feature is enabled. Don’t see the option? Ask your account manager to turn it on.
* **Integration partners building for other clinics** get keys from the Shepherd product team during [onboarding](/getting-started/integration-onboarding/): sandbox credentials first, then production once your integration is reviewed and a clinic agrees to enable it.
Either way, read keys from environment variables or a secrets manager; never hard-code them or ship them in mobile or browser code. If a key is exposed, your account manager can rotate it.
Note
Open API access is a paid add-on, **$35 per site / month**, billed to the practice that enables it. Reading the docs is free; the fee applies once the feature is on. See [Pricing & access](/getting-started/pricing/).
`X-Clinic-Id` is a header, not a body field
The most common first-integration error is leaving out the clinic id. It is a request **header**, like your two keys; a `clinicId` in the JSON body is ignored and the call still fails with `401 Missing X-Clinic-Id header`. Set the header on every clinic-scoped request. See [Errors](/api-reference/errors/) for the full list of failure states.
## Next
[Section titled “Next”](#next)
* [Authentication reference](/api-reference/authentication/): the header table, rotation, the per-clinic scope model, and a five-language “hello world”.
* [Integration onboarding](/getting-started/integration-onboarding/): the partner journey, start to finish.
* [First integration tutorial](/tutorials/first-integration/): pull today’s appointments end to end.
# Integration onboarding
> The end-to-end process for partners building an integration that Shepherd clinics will enable.
This is the path for **integration partners**: teams building a product that Shepherd clinics turn on. If you’re a clinic building on your own data, you don’t need this; you can self-serve keys (see [Authentication](/getting-started/authentication/)).
Here’s what to expect, start to finish.
## 1. NDA
[Section titled “1. NDA”](#1-nda)
Before any sandbox access or detailed API material is shared, we sign a mutual non-disclosure agreement. Share your company name and a contact email to get started; see [Contact](/contact/).
## 2. Kickoff
[Section titled “2. Kickoff”](#2-kickoff)
The Shepherd product team reviews the integration and gets you set up. This is a good time to tell us your target start date and the milestones you’re working toward, so we can schedule check-ins.
## 3. Sandbox access
[Section titled “3. Sandbox access”](#3-sandbox-access)
You’ll receive everything you need to build against a safe, production-like environment:
* **Integration keys**: a public and a private key.
* **A demo clinic** to build against, with login details and its clinic id.
* **Documentation links**, including this site and the live API reference.
Build and test against the sandbox base URL `https://demo-open-api.shepherd.vet/pav2/`. In the demo clinic you can explore settings and add sample clients, patients, and inventory, then validate your integration against realistic workflows.
Note
The Shepherd API is **polling-based**; webhooks are not available yet. Pull changes on a schedule using the date filters described in [Conventions](/api-reference/conventions/). Integrations are enabled per clinic, so each clinic turns your integration on from their own settings.
## 4. Build and test
[Section titled “4. Build and test”](#4-build-and-test)
Implement against the sandbox. If a multi-location operator might enable your integration, read [Groups and multi-site](/guides/groups-and-multi-site/) early; group data sharing changes what your queries return.
## 5. Verification
[Section titled “5. Verification”](#5-verification)
When your integration is working, show us. A short demo or screen recording of the key flows lets the team confirm it behaves as expected before it touches real clinic data.
## 6. Help content
[Section titled “6. Help content”](#6-help-content)
Partner integrations include user-facing help content, so clinics know how to use your integration. You’ll work with Shepherd’s product operations team to put this together. Completed help content is required; a specific named clinic is not, since you build against the demo clinic.
## 7. API Service Agreement
[Section titled “7. API Service Agreement”](#7-api-service-agreement)
Once your integration is verified, we send the API Service Agreement. It’s signed before moving to production.
## 8. Production
[Section titled “8. Production”](#8-production)
The Shepherd team issues production keys, and clinics can then enable your integration on their accounts. Read production keys from environment variables or a secrets manager, the same as in the sandbox.
## 9. Beta, then general availability
[Section titled “9. Beta, then general availability”](#9-beta-then-general-availability)
New integrations go through a beta period (around 30 days) before general availability, which lets early clinics give feedback. When an integration reaches general availability, it’s announced in the Shepherd product update newsletter.
## Questions?
[Section titled “Questions?”](#questions)
Start anything integration-related from the [Contact](/contact/) page.
# Introduction
> What the Shepherd Developer Portal offers and how to get going.
Shepherd is a cloud-based practice-management platform for veterinary clinics. The Shepherd API exposes almost all the same data and workflows that power the Shepherd web app, so you can build integrations against appointments, patients (pets), clients (pet owners), SOAP notes, invoices, prescriptions, inventory, and more.
Not a developer?
Clinic owners and managers: start with [Open API 101](/getting-started/openapi-101/), a plain-English guide to what the Open API is and what it can do for your clinic. For help with the Shepherd app itself, see the [Shepherd Help Center](https://help.shepherd.vet/).
## Who this is for
[Section titled “Who this is for”](#who-this-is-for)
* **Clinic-side integrators** wiring Shepherd into lab systems, imaging, payment processors, or other clinical tooling.
* **Partner platforms** that want to surface Shepherd data inside their own product.
## What’s here
[Section titled “What’s here”](#whats-here)
| Section | What you’ll find |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| Getting Started | Account setup, authentication, your first request. |
| Tutorials | Task-focused walkthroughs (booking sync, lab-result ingestion, etc.). |
| API Reference | Concepts, conventions, and code samples in five languages, anchored on the live Swagger UI for full schemas. |
| Guides | Deeper background: data model, multi-tenancy, rate limits, errors. |
| Blog | Release notes, engineering posts, deprecation announcements. |
## Next steps
[Section titled “Next steps”](#next-steps)
1. [Authenticate](/getting-started/authentication/) and grab a token.
2. Try the [first integration tutorial](/tutorials/first-integration/).
3. Bookmark the [API reference](/api-reference/).
# Open API 101: a guide for clinics
> A plain-English introduction to the Shepherd Open API for clinic owners and managers. What it is, what it's good for, what data it covers, and what you need to get started.
New to APIs? Start here. This page explains the Shepherd Open API in everyday terms: what it is, what clinics use it for, what it can and can’t do, and who you need on your side to put it to work. No technical background needed.
You may also see it written as “OpenAPI” (one word). We mean the same thing: the Shepherd Open API.
## What the Open API is
[Section titled “What the Open API is”](#what-the-open-api-is)
Shepherd is where your clinic’s records live. The Shepherd Open API is a secure, controlled way for **other software** to read and update some of those records, with your permission.
Think of it as a staff entrance to your clinic’s records that only approved software can use. That software shows a pair of keys you create, asks for one specific thing (“today’s appointments”, “invoices from last week”, “this patient’s weight history”), and gets back just that. Shepherd checks the keys on every request, and keeps each clinic’s data separate from every other clinic’s.
Two things are worth knowing up front:
* **It isn’t an app or a button.** There’s nothing to click in Shepherd that “runs” the Open API. It’s used by software that someone writes or buys: a vendor’s product, a script your IT person builds, or a tool a developer creates with an AI coding assistant.
* **It works one request at a time.** Software asks for a small, specific slice of data, then the next slice, and so on. That’s what makes it good at keeping two systems in step, and less suited to copying everything at once.
## What clinics use it for
[Section titled “What clinics use it for”](#what-clinics-use-it-for)
Most clinics that use the Open API do one of these:
* **Reporting and dashboards.** Pull appointments, invoices, and payments into a spreadsheet, dashboard, or accounting tool on a schedule.
* **Keeping the schedule in step.** Connect an online booking tool or reminder service so appointments show up in both places.
* **Client outreach.** Send client contact details to a marketing or email tool you already use.
* **Connecting partners.** Many lab, pharmacy, and specialty partners connect to Shepherd this way. If one of your vendors offers a Shepherd integration, it very likely runs on the Open API.
For more examples, see [What you can build](/getting-started/use-cases/).
## What data it covers
[Section titled “What data it covers”](#what-data-it-covers)
The Open API covers a lot of what your clinic does day to day, but not everything in Shepherd. Here’s the picture in plain terms.
**What software can read through the Open API:**
| Area | What’s included |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Clients | Pet owners, phone numbers and contact details, co-owners, client notes, discounts, and referral sources. |
| Patients | Pets, patient notes, weight history, chronic conditions, vaccine records, and files attached to the patient’s record. |
| Medical records | Visit (SOAP) records: history, physical exam, vitals, assessments and diagnoses, plan notes, treatments, and discharge instruction text. |
| Prescriptions | Prescriptions and refills. |
| Appointments | Appointments, appointment notes, and clinician schedules and availability. |
| Billing | Invoices, invoice line items, payments, and client balances. |
| Products and inventory | Your product and service catalog, stock levels by location, vendors, and inventory activity. |
| Reminders | Reminders and the notifications sent for them. |
| Messaging | Text conversations and messages, plus message templates. |
| Staff and tasks | Staff members, roles, teams, and tasks. |
Some of these can also be **updated** through the Open API (clients, patients, appointments, tasks, and a few others), which is how booking and partner integrations keep both systems in step. Billing, inventory, and products are read-only.
**What the Open API doesn’t cover today** (a few examples, not a complete list):
* Lab results and lab orders from your lab partners, and imaging results.
* Some documents and files: visit summaries and addenda, forms and questionnaires, estimates and treatment plans, signed consent documents, and rabies certificates.
* Boarding, wellness and recurring plans, whiteboard, and patient insurance details.
* Change history (who changed what, and when), most clinic settings, and most of Shepherd’s built-in reports.
The Open API grows over time, so this list will shrink. For the full technical list, a developer can check the [API reference](/api-reference/).
## Can I use it to keep my own backup?
[Section titled “Can I use it to keep my own backup?”](#can-i-use-it-to-keep-my-own-backup)
It’s a fair question, and the short answer is: **partly, but it isn’t a complete backup, and you may not need one.**
**Shepherd already backs up your data.** Your practice data is backed up continuously and encrypted, and can be recovered to within minutes of any point in the last 30 days. Uploaded files such as radiographs, lab PDFs, and consent forms are kept with every earlier version preserved. The Shepherd Help Center explains it in detail: [Data Backup & Recovery](https://help.shepherd.vet/en/articles/14183746-data-backup-recovery).
**If you want a copy of your records in your own hands,** there are simpler routes than the Open API:
* **Ask Shepherd support.** A full export of your practice data is a separate process from our system backups, and support will walk you through your options. See the Help Center’s [Data Backup & Recovery](https://help.shepherd.vet/en/articles/14183746-data-backup-recovery) FAQ.
* **Export medical records from Shepherd.** You can export a patient’s medical history (SOAP notes, lab results, and documents) as PDFs from the patient’s profile. See [Exporting Medical Records](https://help.shepherd.vet/en/articles/4603379-exporting-medical-records).
* **Download reports.** Many Shepherd reports can be downloaded as CSV or PDF for your own records.
**If you still want an Open API copy,** that’s a real software project, and it’s worth going in with clear expectations:
* It will copy the parts of your records the Open API covers (see the section above), not everything in Shepherd. It’s a useful extra layer, not a replacement for an export from support.
* It should be built to copy **only what changed** since the last run, after one careful first pass. Copying your whole history over and over is slow and uses up your request allowance.
* It should run outside clinic hours, and it needs somewhere safe to keep the copy (see [Keeping keys and data safe](#keeping-keys-and-data-safe)).
## What you need to get started
[Section titled “What you need to get started”](#what-you-need-to-get-started)
1. **The Open API feature on your account.** It’s a paid add-on per clinic location. See [Pricing & access](/getting-started/pricing/), and ask your Shepherd account manager to turn it on.
2. **API keys.** Once the feature is on, an admin can create keys in Shepherd under **Admin → Integrations**. See [Authentication](/getting-started/authentication/).
3. **Someone technical, or a vendor.** Someone has to build or run the software that uses the keys. That can be:
* **A vendor** whose product already connects to Shepherd. Often the easiest route: they do the technical work.
* **Your IT person or a local developer** who builds something for you.
* **A developer using an AI coding assistant.** If they use a tool like Claude Code, ask them to install our free [AI agent skill](/tools/agent-skill/) first. It teaches the assistant how the Shepherd Open API works and checks its work, so what it builds is correct and gentle on the system every clinic shares.
4. **A place to test.** We have a practice (“sandbox”) environment so software can be tried out without touching your live records. Ask us about it through [Contact](/contact/).
## Questions to ask a vendor or developer
[Section titled “Questions to ask a vendor or developer”](#questions-to-ask-a-vendor-or-developer)
Before you hand over keys, it’s reasonable to ask:
* **What exactly will it read or change?** Get a plain list: appointments, invoices, client contact details, and so on.
* **Does it copy only what changed,** or does it re-download everything every time?
* **When does it run?** Scheduled jobs belong outside clinic hours.
* **Where will our data be stored, and who can see it?** A copy of client and patient records needs the same care as the originals.
* **How will you keep our keys safe?** They should live in a password manager or secrets store, never in an email, a spreadsheet, or a shared document.
* **Have you read the Shepherd Developer Portal** at developer.shepherd.vet? If they’re using an AI assistant, **are they using the Shepherd agent skill?**
## Keeping keys and data safe
[Section titled “Keeping keys and data safe”](#keeping-keys-and-data-safe)
* **Treat your API keys like the keys to the clinic.** Anyone holding them can reach your records through the Open API. Share them only with the person or vendor who needs them.
* **If a key may have leaked,** ask your account manager to rotate it (replace it with a new one).
* **Any copy of your data outside Shepherd is yours to protect.** Full medical histories and client contact details on an office computer or server need a password, restricted access, encryption, and a backup of their own.
## Where to go next
[Section titled “Where to go next”](#where-to-go-next)
* **Using Shepherd day to day?** The [Shepherd Help Center](https://help.shepherd.vet/) covers the app itself: reports, exports, settings, and integrations.
* **Ready to talk specifics?** [Contact us](/contact/) about access, keys, or a sandbox.
* **Handing this to a developer?** Point them at the [Introduction](/getting-started/introduction/), then the [API reference](/api-reference/) and the [AI agent skill](/tools/agent-skill/).
# Pricing & access
> What Shepherd API access costs and what's required to get keys.
Reading these docs is free and open: explore the reference, tutorials, and guides without an account or an agreement. The pricing and access steps below apply once you’re ready to get keys and start building.
## What it costs
[Section titled “What it costs”](#what-it-costs)
Open API access is **$35 per clinic site, per month**, billed to the practice that turns it on. The fee starts when a clinic enables the feature and begins using keys; there’s no charge for browsing the documentation.
For groups and multi-location operators, the per-site fee applies to each location with access enabled. Questions about your specific account or a larger rollout? Talk to your Shepherd account manager.
## Who pays
[Section titled “Who pays”](#who-pays)
The practice using the API is the paying party. If a clinic enables a partner’s integration, the clinic carries API access on its own account; the cost isn’t billed to the integration partner.
## What’s required to get keys
[Section titled “What’s required to get keys”](#whats-required-to-get-keys)
| You are… | What you need |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| A Shepherd clinic building on your own data | The open API feature enabled on your account (ask your account manager). Then self-serve keys in Shepherd, Admin → Integrations. |
| An integration partner building for other clinics | A signed NDA and, before production, the API Service Agreement. See [Integration onboarding](/getting-started/integration-onboarding/). |
See [Authentication](/getting-started/authentication/) for how keys work once you have access.
## Already onboarding to Shepherd?
[Section titled “Already onboarding to Shepherd?”](#already-onboarding-to-shepherd)
If you’re a new clinic still in onboarding, you can start exploring the API at the same time, but building an integration runs on its own track: it doesn’t pause or extend your standard onboarding timeline, and you’re still expected to complete onboarding and go live on your normal schedule. Talk to your account manager about timing.
Questions about access or pricing go to your Shepherd account manager; general API questions follow your normal [support path](/contact/).
# What you can build
> Common integrations clinics and partners build on the Shepherd API.
Most projects on the Shepherd API come down to moving data in or out of a clinic’s records, then acting on it in another system. Here are the patterns we see most often.
## Reporting and analytics
[Section titled “Reporting and analytics”](#reporting-and-analytics)
The most common use. Pull appointments, invoices, payments, patients, and clients out of Shepherd on a schedule to build custom dashboards, financial reports, or a data feed your own tools read. See [Invoices](/api-reference/resources/invoices/), [Payments](/api-reference/resources/payments/), and [Appointments](/api-reference/resources/appointments/).
## Appointment sync
[Section titled “Appointment sync”](#appointment-sync)
Keep a clinic’s schedule in step with an external booking tool, a reminder service, or your own product. Appointments are one of the most-integrated resources, on both the clinic side and the partner side. See [Appointments](/api-reference/resources/appointments/).
## Client outreach
[Section titled “Client outreach”](#client-outreach)
Export client (pet-owner) and contact data into a marketing or CRM tool to run outreach outside the platform: sync your client list into a campaign tool, then send reminders or follow-ups from there. See [Clients](/api-reference/resources/clients/).
## Inventory and prescriptions
[Section titled “Inventory and prescriptions”](#inventory-and-prescriptions)
Read and write inventory levels, or wire prescription workflows into a pharmacy or fulfillment partner. See [Inventory](/api-reference/resources/inventory/), [Products](/api-reference/resources/products/), and [Prescriptions](/api-reference/resources/prescriptions/).
## Multi-location reporting
[Section titled “Multi-location reporting”](#multi-location-reporting)
Operators running several clinics as a group can roll data up across locations: check whether an account is multi-site, then read shared records once rather than per clinic. See [Groups and multi-site](/guides/groups-and-multi-site/).
Note
A one-time bulk data migration (moving a clinic’s history in or out wholesale) is possible but not the typical path. Talk to your Shepherd contact first so we can point you at the right approach. Looking to keep your own copy of your clinic’s records? See [Open API 101](/getting-started/openapi-101/#can-i-use-it-to-keep-my-own-backup) first.
## Where to go next
[Section titled “Where to go next”](#where-to-go-next)
* New to the API? Start with the [Introduction](/getting-started/introduction/) and [Authentication](/getting-started/authentication/).
* Wondering about cost and access? See [Pricing & access](/getting-started/pricing/).
* Building a product other clinics will enable? See [Integration onboarding](/getting-started/integration-onboarding/).
# Brand guidelines
> Using the Shepherd name, logo, and brand assets in partner-led materials.
If you’re a partner working with us and you’d like to use the Shepherd logo, name, or other brand assets in your own materials, everything you need to get started is linked below.
## Where to start
[Section titled “Where to start”](#where-to-start)
* **[Brand guidelines for partner-led initiatives](https://www.shepherd.vet/pdf/brand-guidelines-partner-led-initiatives.pdf)** (PDF): how to represent Shepherd in co-branded and partner-led materials, including naming, tone, and the rules around logo usage.
* **[Logos and graphic assets](https://www.shepherd.vet/logos/)**: download the Shepherd logo and related graphics in the formats we support.
## Using the assets
[Section titled “Using the assets”](#using-the-assets)
Please do your best to follow the guidance in the PDF. It covers the things that most often need a second look: clear space around the logo, which colour variants to use on which backgrounds, and how to refer to Shepherd in writing.
A few points worth knowing up front:
* Use the supplied logo files rather than recreating, redrawing, or exporting the mark from a screenshot.
* Don’t alter the logo’s colours, proportions, or orientation, and don’t add effects to it.
* Don’t imply a partnership, endorsement, or certification that isn’t in place.
## Questions
[Section titled “Questions”](#questions)
If something isn’t covered, or you’re unsure whether a particular use is in bounds, please reach out before you publish. We’re happy to take a look, and it’s much easier to answer a question early than to revise materials that have already shipped.
See [Contact](/contact/) for the right person to ask.
# Data model
> The core entities exposed by the Shepherd API and how they relate.
A 5-minute mental model of the Shepherd domain. Useful before you read the API reference.
## Core entities
[Section titled “Core entities”](#core-entities)
* **Clinic** : a veterinary practice; the tenancy boundary for most data.
* **Client** : a pet owner.
* **Patient** : a pet (dog, cat, exotic, etc.) belonging to one or more clients.
* **Appointment** : a scheduled visit for a patient with a provider at a clinic.
* **SOAP** : the clinical note (Subjective, Objective, Assessment, Plan) recorded during a visit.
* **Invoice** : billing artifact for a visit or set of items.
* **Prescription** : a dispensed or prescribed medication tied to a patient.
## Tenancy
[Section titled “Tenancy”](#tenancy)
Every resource is scoped to a clinic. Clinics roll up into clinic *groups* for multi-location operators. Integrations authenticate with a dual-key pair plus an `X-Clinic-Id` header that selects the active clinic per request; see [Authentication](/getting-started/authentication/).
## Sharding
[Section titled “Sharding”](#sharding)
Shepherd shards clinic data across physical PostgreSQL clusters. The API hides this from callers, but a few endpoints (bulk export, reporting) accept a clinic ID and route accordingly: expect a small per-clinic latency variance, not a global one.
# Groups and multi-site
> How clinic groups and multi-site data sharing change what your Shepherd integration sees.
Many Shepherd customers run more than one location as a clinic *group*. If you only ever target one clinic you can skim this, but any integration that a multi-location operator might enable should understand how groups change what your queries return. A common surprise is duplicate or “missing” records that are really just shared across a group.
Note
For the operator’s view of how group sharing is configured in Shepherd itself, see [Group multi-location access](https://help.shepherd.vet/en/collections/6447605-group-multi-location-access) in the Shepherd Help Center. Useful context for what your customer is enabling on their end.
## Clinic id vs group id
[Section titled “Clinic id vs group id”](#clinic-id-vs-group-id)
Every request targets exactly one clinic through the `X-Clinic-Id` header (see [Authentication](/getting-started/authentication/)). Clinics run by the same operator roll up under a single **group**, identified by a group id. Clinic records returned by the API carry the id of the group they belong to; a standalone clinic has no group.
So there are two identifiers in play:
* **Clinic id** : the tenancy boundary you pass in `X-Clinic-Id`. One request, one clinic.
* **Group id** : the operator the clinic rolls up to. You don’t send it as a header; you read it off clinic and group records.
## Check whether an account is multi-site
[Section titled “Check whether an account is multi-site”](#check-whether-an-account-is-multi-site)
Check this even for accounts you assume are single-location: an operator can add locations later, and the answer changes how you read results. Call the groups endpoint with the clinic you’re working in; it returns the group that clinic belongs to, including whether the operator is multi-site and what they share.
* curl
```sh
curl -X POST https://open-api.shepherd.vet/pav2/open-api-groups \
-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 '{}'
```
* Python
```python
import os, requests
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-groups",
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={},
timeout=30,
)
resp.raise_for_status()
group = resp.json()
print(group)
```
* C#
```csharp
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 resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-groups",
JsonContent.Create(new { }));
resp.EnsureSuccessStatusCode();
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```
* PHP
```php
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 => '{}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response, "\n";
```
* JavaScript
```js
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-groups', {
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: '{}',
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
console.log(await resp.json());
```
The response tells you two things that shape the rest of your integration:
* **`isMultiSite`** : whether this operator runs as a multi-location group.
* **A set of sharing flags** : whether clients and patients, products, pricing, and other data are shared across the group’s clinics (for example `shareClientsAndPatients`, `shareProducts`, `shareProductPricing`). The live [Swagger reference](https://app.shepherd.vet/swagger/) has the full field list and types.
## What sharing changes
[Section titled “What sharing changes”](#what-sharing-changes)
When an operator shares a dataset across the group, a record’s *home* clinic can differ from the clinic you queried. With client and patient sharing enabled, for example, a client created at one location is visible from the others; each record still carries the id of the clinic it belongs to, so you can tell where it lives.
Two practical consequences:
* **The same record can appear under more than one clinic.** If you pull a list for each clinic in a group and concatenate, you’ll get duplicates for shared data. De-duplicate on the record id, and use each record’s home clinic id when you need to attribute it.
* **Cross-clinic filtering only works where sharing is on.** Endpoints accept a `clinicIds` filter to scope a query to specific clinics in the group, but it’s honored only when the relevant data is shared; otherwise a request is limited to the single clinic in `X-Clinic-Id`. To cover an entire group, either iterate `X-Clinic-Id` across its clinics or, where sharing is enabled, pass `clinicIds`.
## Pulling multiple locations
[Section titled “Pulling multiple locations”](#pulling-multiple-locations)
Set the expectation up front: **there is no single call that returns every location’s data at once.** Each request is scoped to the one clinic in `X-Clinic-Id`. To cover a group you have two patterns:
1. **Iterate `X-Clinic-Id`.** List the clinics in the group, then make the same call once per clinic, changing the header each time. This always works, regardless of sharing settings, and is the right default.
2. **Filter with `clinicIds` where the data is shared.** On endpoints that support it, a `clinicIds` body field scopes one query to several clinics at once:
```json
{ "page": 1, "rpp": 100, "clinicIds": "a1b2...,c3d4..." }
```
This is honored **only** when the relevant dataset is shared across the group (the `share*` flags above). If it isn’t, the filter is ignored and you get just the clinic in `X-Clinic-Id`, so don’t rely on it without checking the flags first.
Whichever pattern you use, remember that shared records can surface under more than one clinic; de-duplicate on the record id and attribute each record by its home clinic id.
## Putting it together
[Section titled “Putting it together”](#putting-it-together)
A robust multi-site integration usually:
1. Resolves the group for the clinic it’s enabling, and records `isMultiSite` and the sharing flags.
2. Lists the clinics in that group (clinic records carry the group id) so it knows the full set of locations.
3. Decides, per dataset, whether to iterate per clinic or rely on group sharing, based on the flags.
4. De-duplicates shared records by id and attributes them by home clinic id.
If `isMultiSite` is false, treat the account as a single clinic: no sharing, one location, nothing extra to do.
# Skill for AI coding agents
> Download the Shepherd OpenAPI skill so AI coding assistants build Shepherd integrations that are correct, tested, and within the API's limits.
If you use an AI coding assistant such as Claude Code to build your application that’s integrated with Shepherd, install this skill first. It gives the agent the Shepherd API’s endpoints, schemas, and rules, plus a tool that checks every request before your code sends it, so the code it writes is correct the first time and easy on the servers every clinic shares.
Shepherd OpenAPI skill
* Version 1.1.1
* 268 KB zip, 42 files
* MIT license
[ Download the skill](/downloads/shepherd-openapi-skill.zip)
SHA-256 `ad9dee360a2e88c987747cd39e44705af61277780942d98c408cfaaa1855929f`
The skill is free and MIT licensed: use it, change it, and ship code written with it. It follows the open [Agent Skills](https://agentskills.io/) format, so it is plain Markdown, JSON, and one Python script that you can read before you install it.
## Why use it
[Section titled “Why use it”](#why-use-it)
AI assistants write API clients quickly, and they fill gaps in what they know with confident guesses. Against the Shepherd API, the usual guesses go wrong in the same few ways:
* **The wrong host or header.** Calls go to a host that does not serve the API, or the clinic id goes in the JSON body instead of the `X-Clinic-Id` header.
* **Unbounded reads.** A sync asks for a clinic’s entire history in one query, or a misspelled filter is silently ignored and the query runs unfiltered.
* **Retry loops.** A slow request times out and the code sends it again, and again, multiplying the work on the server; or a rejected request is retried until the rate limit locks the integration out.
* **Destructive updates.** An update sends only the changed field, and the API, which treats updates as full replacements, clears everything else on the record.
* **Duplicate records.** A create is retried after a timeout and the clinic gets two appointments.
Each of these fails, loses clinic data, or slows the API for other clinics. With the skill installed, the agent knows the rules behind them and checks its requests against them before anything is sent.
## What the agent gets
[Section titled “What the agent gets”](#what-the-agent-gets)
* **The endpoint reference, offline.** Every public endpoint, with its request fields, required fields, and response shape, generated from the live API description. The agent looks endpoints up instead of guessing, and does not need to browse.
* **The rules the schema cannot express.** Which lists need a date window, page-size and embed limits, which filter fields an endpoint accepts but never applies, how rate limits are counted, which failures to retry and which never to retry, and exactly which fields each update keeps or clears. These rules are checked against the live API with a test harness, not only read from the schema; see [How we verify](/api-reference/how-we-verify/).
* **A request linter.** `scripts/shepherd_api.py lint` checks a request against those rules and the schema before any code sends it: host, verb, route, field names, fields the endpoint does not apply, sort fields, id and date formats, date windows, page sizes, embeds, and update completeness.
* **A budgeted development runner.** `scripts/shepherd_api.py call` sends one request at a time for exploration, against the sandbox by default, under a local rate budget and circuit breaker.
* **Starter clients and tests** in Python, TypeScript, C#, and PHP that already handle timeouts, rate limits, paging, error bodies, and safe updates.
- shepherd-openapi/
* SKILL.md the rules and workflow the agent follows
* LICENSE.txt
* references/
* api-essentials.md hosts, headers, paging, filters, embeds
* limits-and-sync.md rate limits, retries, incremental sync
* writes.md creates, updates, read-merge-write
* errors.md status codes, error bodies, fixes
* resources.md, client-patterns.md, testing.md, production-checklist.md
* endpoints/ per-area endpoint reference
* …
* assets/
* openapi.json machine-readable endpoint description, with request rules
* templates/ starter clients and tests for four languages
* …
* scripts/
* shepherd\_api.py endpoint lookup, linter, and development runner
## Install
[Section titled “Install”](#install)
* Claude Code
Claude Code loads skills from a folder on disk and uses them automatically when a task involves the Shepherd API.
1. Download the zip above.
2. Unzip it into one of the skills folders:
```sh
# For you, in every project
unzip shepherd-openapi-skill.zip -d ~/.claude/skills/
# Or for one repository, shared with everyone who clones it
unzip shepherd-openapi-skill.zip -d .claude/skills/
```
Either way you end up with `skills/shepherd-openapi/SKILL.md`. Committing the project copy gives your whole team the same rules.
3. Start a new Claude Code session. Ask it to work on your integration, or invoke the skill directly with `/shepherd-openapi`.
* Claude apps
In Claude on the web or desktop, custom skills are uploaded as a zip. They require code execution to be enabled, and each person uploads their own copy.
1. Download the zip above. Don’t unzip it.
2. In Claude, open **Customize**, then **Skills**, and choose **Upload a skill**.
3. Upload `shepherd-openapi-skill.zip`.
Menu names change from time to time; Anthropic’s [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude) article has the current steps. Network access for skills in the Claude apps depends on your plan and admin settings, so live calls through the runner may be blocked; the reference, rules, and linter work without it.
* Claude API
Upload the skill once through the [Skills API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) and attach it to requests that use the code execution tool. Skills on the API run in a container with no network access, so the agent can use the reference, rules, linter, and templates to write and review code, but cannot make live calls to Shepherd.
* Other agents
The skill follows the open [Agent Skills](https://agentskills.io/) format, which a growing number of coding agents support. Unzip it into the skills folder your agent reads, keeping the `shepherd-openapi/` folder name, and check your agent’s documentation for where that is. The helper script needs Python 3.11 or newer.
## Set up credentials
[Section titled “Set up credentials”](#set-up-credentials)
The agent never needs your keys in the conversation. Set them in the environment the agent runs in, and use **sandbox keys** while you develop:
```sh
export SHEPHERD_ENV=sandbox # or production
export SHEPHERD_PUBLIC_KEY=...
export SHEPHERD_PRIVATE_KEY=...
export SHEPHERD_CLINIC_ID=...
export SHEPHERD_APP_NAME=acme-lab-sync # optional: identifies your integration
```
Sandbox keys work against `https://demo-open-api.shepherd.vet/pav2/`. If you don’t have them yet, see [Authentication](/api-reference/authentication/#how-keys-are-issued).
Never paste keys into a prompt
Anything you type into a conversation can end up in logs and transcripts. Keep keys in environment variables or a secrets manager, and rotate a key that has been pasted anywhere.
## Try it
[Section titled “Try it”](#try-it)
Ask your agent for real work. For example:
* “Write a job that syncs appointments changed since the last run into our database.”
* “Add a function that updates a patient’s alerts.”
* “Our appointment import keeps timing out in production. Fix it.”
* “Add tests for our Shepherd client that cover rate limits and timeouts.”
* “Show me the first page of sandbox clients created last month.”
## The helper script
[Section titled “The helper script”](#the-helper-script)
The agent runs `scripts/shepherd_api.py` from the skill folder, and you can too. It uses only the Python standard library.
```sh
python3 scripts/shepherd_api.py endpoints --search invoice
python3 scripts/shepherd_api.py schema "POST /pav2/open-api-invoices"
python3 scripts/shepherd_api.py lint "POST /pav2/open-api-appointments" --body '{"rpp":100,"dateFrom":"2026-05-01T00:00:00Z","dateTo":"2026-06-01T00:00:00Z"}'
python3 scripts/shepherd_api.py call "POST /pav2/open-api-clinics" --body '{"page":1,"rpp":1}'
python3 scripts/shepherd_api.py status
```
Here is the linter reviewing a request an agent might write from memory:
```text
$ python3 scripts/shepherd_api.py lint "POST /pav2/open-api-appointments" \
--body '{"page":1,"rpp":1000,"dateCreatedFrom":"2026-01-01T00:00:00Z","embed":"appointmentPatients.patient","clinicId":"9890662f-52db-4a41-a5c1-b2e300d400b4"}'
ERROR [clinic-in-body] The clinic id is the X-Clinic-Id HEADER. A clinicId in the body is ignored.
ERROR [date-pair] `dateCreatedFrom` without `dateCreatedTo` spans from then until now. Send both ends, one month at most.
ERROR [unbounded] This list has no bound: add a date window (one month at most) or an id filter (`appointmentStatusIds`, `cancellationReasonIds`, `clientIds`, `patientIds`, `providerIds`, `ids`). Enumerating a whole collection is not a supported access pattern.
WARN [embed-rpp] `rpp` 1000 with embeds multiplies the response size. Keep embedded pages at 250 or fewer.
INFO [is-deleted] Deleted records are included unless you send `isDeleted: false`. Either filter them out or handle the soft-delete flag.
ERROR [heavy-embed] Embedding `appointmentPatients.patient` is expensive on large pages. Use `rpp` of 50 or less with it, and an id filter.
```
For updates, pass the current record with `--current` and the linter lists every field the update would clear.
The `call` runner is for exploration during development, not for production traffic. It is deliberately conservative:
* It targets the **sandbox** unless `SHEPHERD_ENV=production` is set, and refuses creates and updates against production without `--allow-production-write`.
* It lints first and does not send a request with errors.
* It sends one request at a time, within a local budget of 30 requests a minute and 600 an hour per key.
* It never retries a timeout or a create. After a `429` it refuses further requests until the next UTC minute; after repeated timeouts or server errors it stops sending for five minutes.
* `--dry-run` prints the equivalent `curl` command, with keys left as environment variables, instead of sending.
## Starter clients and tests
[Section titled “Starter clients and tests”](#starter-clients-and-tests)
The templates in `assets/templates/` are starting points to copy into your project and own, not published packages. Each client implements the same behaviors, and each test suite exercises them against a mocked transport, so the tests run offline and instantly.
| Language | Client | Tests | Runtime |
| ---------- | ------------------------ | ------------------------------------------- | ---------------------------- |
| Python | `shepherd_client.py` | `test_shepherd_client.py` (pytest) | Python 3.11+, httpx |
| TypeScript | `shepherd-client.ts` | `shepherd-client.test.ts` (`node:test`) | Node.js 24+, no dependencies |
| C# | `ShepherdClient.cs` | `ShepherdClientTests.cs` (xUnit v3) | .NET 10 |
| PHP | `src/ShepherdClient.php` | `tests/ShepherdClientTest.php` (PHPUnit 13) | PHP 8.4+, Guzzle 8 |
The tests cover the cases that matter in production: `429` handling, `502` and `503` backoff, timeouts, `500`s, and creates that are never retried, malformed clinic ids refused before sending, the circuit breaker, JSON string, JSON object, and plain-text error bodies, refusing unbounded lists, and read-merge-write updates that keep untouched fields.
## What the skill asks of the agent
[Section titled “What the skill asks of the agent”](#what-the-skill-asks-of-the-agent)
The rules in `SKILL.md` match the API reference on this site. In short, the agent will:
* **Use the right environment.** The sandbox for development and tests, `https` only, the three headers with `X-Clinic-Id` as a header. See [Authentication](/api-reference/authentication/).
* **Bound every read.** A date window of one calendar month or less, or an id filter; explicit page sizes; shallow embeds. See [Conventions](/api-reference/conventions/).
* **Respect the limits.** One shared budget per key, sequential requests by default, a wait for the next UTC minute after a `429`, and no retries of timeouts, `4xx` responses, `500`s, or creates. See [Rate limits](/api-reference/rate-limits/) and [Errors](/api-reference/errors/).
* **Write safely.** Read, merge, and write every update; look for an existing record before creating one after an ambiguous failure; get a human’s approval before the first production write. See [Updating records](/api-reference/conventions/#updating-records-is-a-full-replacement).
* **Test.** Unit tests for the failure cases above, and a few opt-in contract tests against the sandbox.
## Privacy and security
[Section titled “Privacy and security”](#privacy-and-security)
* The skill runs entirely inside your agent. It has no telemetry and sends nothing to Shepherd or anyone else; the only network requests are the API calls you or your agent run with `call`.
* Keys are read from environment variables and are never written to disk or printed. The runner keeps its budget and breaker state in `~/.cache/shepherd-openapi-skill/`, under a hash of the public key.
* Requests sent by the runner carry a `User-Agent` naming the skill version and your `SHEPHERD_APP_NAME`, so Shepherd can tell development traffic apart if you ask for help.
* As with any skill, review what you install. Everything in the zip is readable text, and the SHA-256 above lets you confirm you have the file published here.
## Versions and updates
[Section titled “Versions and updates”](#versions-and-updates)
This is version 1.1.1, built from the public API as of September 2026 (API version 2.246.0.33). When the API changes in a way that affects integrations, a new version is published here. Download it again and replace the `shepherd-openapi` folder (or upload it again in the Claude apps).
| Version | Date | Changes |
| ------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.1.1 | October 2026 | Scheduling guidance: the API’s nightly peak (about 00:00 to 04:30 UTC) and the recommended window for nightly syncs and backfills (05:00 to 22:00 UTC, quietest 09:00 to 12:00 UTC). The gateway’s 120-second cutoff, which returns an HTML page instead of JSON, is documented and treated as a timeout. |
| 1.1.0 | September 2026 | Rules corrected and extended from live test-harness evidence: filter fields an endpoint accepts but does not apply are flagged, unknown sort fields are errors, `rpp` and `page` below 1 or `null` are rejected, smaller pages on large-record endpoints, a bound required on breeds, a date window required on every patient-notes read, `401` (not `403`) for an unlinked clinic, and `500`s are never retried. The starter clients refuse a malformed clinic id and no longer retry a `500`. |
| 1.0.0 | September 2026 | First release. |
## Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
**The agent isn’t using the skill.** Mention the Shepherd API in your request, or in Claude Code invoke it with `/shepherd-openapi`. Check that the folder is named `shepherd-openapi` and contains `SKILL.md` directly.
**The helper script won’t run.** It needs Python 3.11 or newer on the path as `python3`. Without it, the agent still has the reference and rules, but cannot lint or make live calls.
**Live calls fail with a network error.** Your agent’s environment may block outbound requests; the Claude API always does, and the Claude apps can, depending on settings. Run the calls from your own machine instead.
**Something in the skill is wrong or missing.** [Tell us](/contact/). Include the skill version, the endpoint, and what you expected.
# Your first integration
> A 10-minute walkthrough that pulls today's appointments from a clinic.
By the end of this tutorial you’ll have made an authenticated request to the Shepherd API and listed today’s appointments for a single clinic. Plan on about ten minutes.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* A runtime for one of curl, Python 3.11+, .NET 10, PHP 8.3+, or Node.js 24+.
* Sandbox or production credentials from your Shepherd account manager. If you don’t have them, see [Authentication](/getting-started/authentication/).
* A clinic UUID your integration has been granted access to.
## 1. Set environment variables
[Section titled “1. Set environment variables”](#1-set-environment-variables)
The examples below read three environment variables:
```sh
export SHEPHERD_PUBLIC_KEY="pk_..."
export SHEPHERD_PRIVATE_KEY="sk_..."
export SHEPHERD_CLINIC_ID="00000000-0000-0000-0000-000000000000"
```
Use sandbox keys with `https://demo-open-api.shepherd.vet/pav2/`, or production keys with `https://open-api.shepherd.vet/pav2/`. Develop against the sandbox. The examples below point at production; change the base URL if you are on sandbox, and never mix keys and hosts from different environments.
## 2. Build the request
[Section titled “2. Build the request”](#2-build-the-request)
You’ll call `POST /pav2/open-api-appointments` and filter on a one-day window using `dateFrom` and `dateTo`, which match appointments by their **scheduled** time. (The similar-looking `dateCreatedFrom` and `dateCreatedTo` match when the booking was made, which is a different question.) Reads in the Shepherd API are `POST`s; the filter goes in the JSON body.
For “today” in UTC, the window runs from `00:00:00Z` to `23:59:59Z`. If your clinic operates in a different timezone, adjust the bounds; the API stores timestamps in UTC. Keep date windows to one calendar month or less (see [Conventions](/api-reference/conventions/)); one day is well inside that.
## 3. Call the API
[Section titled “3. Call the API”](#3-call-the-api)
* curl
```sh
TODAY=$(date -u +%Y-%m-%d)
curl -X POST https://open-api.shepherd.vet/pav2/open-api-appointments \
-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\": 1,
\"rpp\": 100,
\"dateFrom\": \"${TODAY}T00:00:00Z\",
\"dateTo\": \"${TODAY}T23:59:59Z\",
\"sort\": \"startDate|asc\"
}"
```
* Python
```python
import os, requests
from datetime import datetime, timezone
today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
resp = requests.post(
"https://open-api.shepherd.vet/pav2/open-api-appointments",
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": 1,
"rpp": 100,
"dateFrom": f"{today}T00:00:00Z",
"dateTo": f"{today}T23:59:59Z",
"sort": "startDate|asc",
},
timeout=30,
)
if not resp.ok:
raise RuntimeError(f"Shepherd {resp.status_code}: {resp.text}")
data = resp.json()
print(f"{data['totalRecords']} appointment(s) today")
for appt in data["item"]:
print(appt.get("startDate"), appt.get("id"))
```
* C#
```csharp
using System.Net.Http.Json;
using System.Text.Json;
var publicKey = Environment.GetEnvironmentVariable("SHEPHERD_PUBLIC_KEY")!;
var privateKey = Environment.GetEnvironmentVariable("SHEPHERD_PRIVATE_KEY")!;
var clinicId = Environment.GetEnvironmentVariable("SHEPHERD_CLINIC_ID")!;
var today = DateTime.UtcNow.ToString("yyyy-MM-dd");
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
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 = 1,
rpp = 100,
dateFrom = $"{today}T00:00:00Z",
dateTo = $"{today}T23:59:59Z",
sort = "startDate|asc",
});
var resp = await http.PostAsync(
"https://open-api.shepherd.vet/pav2/open-api-appointments", body);
var text = await resp.Content.ReadAsStringAsync();
if (!resp.IsSuccessStatusCode)
throw new HttpRequestException($"Shepherd {(int)resp.StatusCode}: {text}");
using var doc = JsonDocument.Parse(text);
var root = doc.RootElement;
Console.WriteLine($"{root.GetProperty("totalRecords").GetInt32()} appointment(s) today");
foreach (var appt in root.GetProperty("item").EnumerateArray())
{
Console.WriteLine($"{appt.GetProperty("startDate")} {appt.GetProperty("id")}");
}
```
* PHP
```php
true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
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' => 1,
'rpp' => 100,
'dateFrom' => "{$today}T00:00:00Z",
'dateTo' => "{$today}T23:59:59Z",
'sort' => 'startDate|asc',
]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status < 200 || $status >= 300) {
throw new RuntimeException("Shepherd $status: $response");
}
$data = json_decode($response, true);
echo $data['totalRecords'] . " appointment(s) today\n";
foreach ($data['item'] as $appt) {
echo $appt['startDate'] . "\t" . $appt['id'] . "\n";
}
```
* JavaScript
```js
const today = new Date().toISOString().slice(0, 10);
const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-appointments', {
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: 1,
rpp: 100,
dateFrom: `${today}T00:00:00Z`,
dateTo: `${today}T23:59:59Z`,
sort: 'startDate|asc',
}),
signal: AbortSignal.timeout(30_000),
});
if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
console.log(`${data.totalRecords} appointment(s) today`);
for (const appt of data.item) {
console.log(appt.startDate, appt.id);
}
```
## 4. Read the response
[Section titled “4. Read the response”](#4-read-the-response)
The response is a collection envelope (see [Conventions](/api-reference/conventions/)):
```json
{
"item": [ /* appointment records */ ],
"totalRecords": 17,
"page": 1,
"recordsPerPage": 100,
"sort": "startDate|asc",
"searchQuery": null,
"embed": null,
"links": []
}
```
Iterate `item[]` to process each appointment. If `totalRecords` is larger than `page * recordsPerPage`, increment `page` and call again; stop when you have read `totalRecords` records or a page comes back empty. Appointments that were deleted are included; send `"isDeleted": false` if you only want live ones.
## What to try next
[Section titled “What to try next”](#what-to-try-next)
* Inline related records (clients, patients, providers) with `embed`. See [Conventions](/api-reference/conventions/).
* Read the [Appointments resource reference](/api-reference/resources/appointments/) for the full request and response shape.
* When something goes wrong, the error body is not always the same shape, and not every failure should be retried. See [Errors](/api-reference/errors/).