This is the full developer documentation for Shepherd API # Build on Shepherd > One REST API for modern veterinary clinics: appointments, patients, records, invoices, and payments. ## Announcements [See all posts →](/blog/) * [Sep 16](/blog/shepherd-openapi-skill-for-ai-agents/) ### [A Shepherd skill for your AI coding agent](/blog/shepherd-openapi-skill-for-ai-agents/) [The new Shepherd OpenAPI skill gives AI coding assistants everything they need to build on the Shepherd API correctly, safely, and fast.](/blog/shepherd-openapi-skill-for-ai-agents/) [Read more →](/blog/shepherd-openapi-skill-for-ai-agents/) * [Aug 20](/blog/sheppy-and-a-docs-accuracy-pass/) ### [Sheppy gets an upgrade, and so do the docs](/blog/sheppy-and-a-docs-accuracy-pass/) [A new look for our mascot, and a full accuracy pass over the API reference checked line by line against the live schema.](/blog/sheppy-and-a-docs-accuracy-pass/) [Read more →](/blog/sheppy-and-a-docs-accuracy-pass/) Getting started Set up API credentials, make your first authenticated request, and understand the multi-tenant clinic model. [Start here](/getting-started/introduction/). Running a clinic and new to APIs? Read [Open API 101](/getting-started/openapi-101/). API reference Authentication, conventions, and code samples for every major resource, with the live Swagger UI for full schemas. [Browse the reference](/api-reference/). Build with AI agents Using Claude Code or another AI coding assistant? Install the Shepherd agent skill so it builds your integration correctly and within the API’s limits. [Get the skill](/tools/agent-skill/). Tutorials End-to-end walkthroughs: booking integrations, lab result ingestion, and more. [See tutorials](/tutorials/first-integration/). About the platform Scale, architecture, and security: the numbers, the AWS diagram, and our SOC 2 Type II. [Inside Shepherd](/about/shepherd-technology/). Brand guidelines Working with us as a partner and want to use the Shepherd logo or name? [Brand guidelines and assets](/guides/brand-guidelines/) to get you started. Get in touch Questions, API access, partnership interest, or feature requests? [Reach the developer team](/contact/): the right contact for your question. ![](/img/peeking-cat.webp) ![](/img/peeking-cat-static.webp) # Production architecture > How Shepherd's production environment on AWS fits together, from the edge to disaster recovery. Shepherd runs entirely on Amazon Web Services. Production lives in the **US East (Ohio)** region, spread across multiple availability zones, with a disaster-recovery copy in **US West (Oregon)**. The diagram below follows a request from a clinic or a partner integration through to the data it touches. [Shepherd production architecture on AWS](/diagrams/shepherd-aws-architecture.html?embed=1) [Open the diagram full screen](/diagrams/shepherd-aws-architecture.html) Pan, zoom, trace routes, and export it as an image. ## Reading the diagram [Section titled “Reading the diagram”](#reading-the-diagram) ### Two front doors [Section titled “Two front doors”](#two-front-doors) * **Clinic teams and pet owners** reach the web apps through **Amazon CloudFront and AWS WAF**. CloudFront terminates TLS at the edge; WAF filters traffic before it reaches an application server. * **Partner integrations** use the [Open API](/api-reference/) at `open-api.shepherd.vet`, which has its own load balancer, its own WAF rules, and its own server fleet. Every request carries an integration key and names one clinic; see [Authentication](/api-reference/authentication/). ### Application tier [Section titled “Application tier”](#application-tier) * **Web app and API servers** run .NET on Amazon EC2. Releases are **blue/green**: the new version is brought up beside the old one and takes traffic only once it is healthy. Load balancers route around any unhealthy server, and the fleet scales out and in automatically. * **AI services** run as containers on **Amazon ECS (Fargate)** and call AI model providers for transcription and summarization. They run beside the request path, so AI work doesn’t hold up ordinary clinic requests. * **Background services** handle queued and scheduled work: reports and messaging events arrive through **Amazon SQS**, integration syncs exchange results with labs and other partners, and a real-time push hub keeps open screens current. ### Data tier [Section titled “Data tier”](#data-tier) * **PostgreSQL 16 on Amazon RDS** holds clinical and business records. Clinic data is sharded across database clusters, each a **Multi-AZ** primary with read replicas. Production databases accept encrypted connections only and have no public endpoint. * **Amazon ElastiCache (Valkey)** holds sessions and fans out real-time updates, encrypted in transit and at rest. * **Amazon S3** stores attachments and documents, encrypted at rest. * An **analytics warehouse** in a separate AWS account receives a copy of the data, so large analytical queries run against the copy rather than the production databases. ### Recovery [Section titled “Recovery”](#recovery) * Databases are backed up continuously and can be restored to any point in the **last 30 days**. * Every production database has a **cross-region replica** in Oregon, and production files are **replicated** there as they are written. * If the primary application is unavailable, clinics can keep working from a **read-only fallback environment**; see the Help Center’s [Read-Only Mode and Emergency Kit](https://help.shepherd.vet/en/articles/9142634-read-only-mode-and-emergency-kit). ## What the diagram leaves out [Section titled “What the diagram leaves out”](#what-the-diagram-leaves-out) This is a simplified view for developers and evaluators. It deliberately omits non-production environments, internal tooling, network addresses and segmentation, and smaller supporting services (DNS, certificates, monitoring, and the serverless functions that render PDFs and images). For security questions the diagram doesn’t answer, see [Security & trust](/about/security/). # Security & trust > Shepherd's SOC 2 Type II report, backups, and access controls, with links to the Help Center articles that cover each in detail. Clinics trust Shepherd with their medical records, client details, and payments. This page collects what we can tell you publicly about how that data is protected, and how to get the rest. ## SOC 2 Type II [Section titled “SOC 2 Type II”](#soc-2-type-ii) Shepherd has completed a **SOC 2 Type II** examination by an independent CPA firm, covering the **Security** trust services criteria for the period **April 11, 2025 to April 11, 2026**. A Type II report tests whether our controls operated effectively across the whole period, not only whether they were designed well on one day. The report is confidential, so we share it directly rather than posting it here. To request it, along with our bridge letter covering the time since the period ended, email **** with your name, organization, and your relationship to Shepherd (customer, prospective customer, or integration partner). ## Backups and recovery [Section titled “Backups and recovery”](#backups-and-recovery) > Your data is backed up continuously, encrypted at all times, and recoverable to within minutes of any point in the last 30 days. Production runs across multiple AWS availability zones in the US East (Ohio) region, with a disaster-recovery copy of every production database and of production files in a second region. The [Architecture](/about/architecture/) page shows how the pieces fit together. ## Help Center articles [Section titled “Help Center articles”](#help-center-articles) The [Shepherd Help Center](https://help.shepherd.vet/en/) covers each of these topics in more depth. ### Platform security [Section titled “Platform security”](#platform-security) * [Shepherd Security Overview](https://help.shepherd.vet/en/articles/5666219-shepherd-security-overview): hosting, encryption in transit, access to data, caching, and redundancy. * [Data Backup & Recovery](https://help.shepherd.vet/en/articles/14183746-data-backup-recovery): how backups work and how data is restored. * [Read-Only Mode and Emergency Kit](https://help.shepherd.vet/en/articles/9142634-read-only-mode-and-emergency-kit): how a clinic keeps working if the main application is unavailable. ### Accounts and access control [Section titled “Accounts and access control”](#accounts-and-access-control) * [Clinic Login and Users](https://help.shepherd.vet/en/articles/8430172-clinic-login-and-users): how clinic users and logins are managed. * [User Role Permissions](https://help.shepherd.vet/en/articles/5539233-user-role-permissions): limiting what each role can see and do. * [PINs and Passwords in Shepherd](https://help.shepherd.vet/en/articles/4603290-pins-and-passwords-in-shepherd): password and PIN rules. * [Clinic Login IP Restrictions](https://help.shepherd.vet/en/articles/11931456-clinic-login-ip-restrictions): allowing sign-in only from your clinic’s networks. * [Remote Users](https://help.shepherd.vet/en/articles/4516256-remote-users): giving staff access from outside the clinic. * [Unlocking a Locked User Account](https://help.shepherd.vet/en/articles/8252451-unlocking-a-locked-user-account): what happens after repeated failed sign-ins. ### Your data [Section titled “Your data”](#your-data) * [Exporting Medical Records](https://help.shepherd.vet/en/articles/4603379-exporting-medical-records): getting records out of Shepherd. * [Open API 101](/getting-started/openapi-101/): what the Open API can and can’t do for keeping your own copy of clinic data. ## For developers [Section titled “For developers”](#for-developers) * Integration keys are granted to specific clinics, and every request names one clinic. See [Authentication](/api-reference/authentication/) for how keys work and how to keep them out of client-side code. * The Open API sits behind its own firewall and enforces [rate limits](/api-reference/rate-limits/) per integration key. * If you build with an AI coding assistant, the [Shepherd OpenAPI agent skill](/tools/agent-skill/) keeps generated code inside safe request patterns. ## Reporting a security issue [Section titled “Reporting a security issue”](#reporting-a-security-issue) If you believe you’ve found a security vulnerability in Shepherd, email . Please include enough detail for us to reproduce it, and give us a chance to fix it before sharing it publicly. # About Shepherd Technology > The codebase and platform behind the Shepherd veterinary practice-management system, in numbers. Shepherd is a cloud-native veterinary practice-management platform: the clinic web app, a pet owner portal, payments, AI-assisted medical records, a public API, and integrations with the labs, imaging, pharmacy, and communications vendors clinics already use. It runs entirely on AWS, and we ship a new platform release every few weeks. ## The platform in numbers [Section titled “The platform in numbers”](#the-platform-in-numbers) * 1.4M+ API requests a day Open API average, September 2026 * 2.1M+ lines of C# Backend, API, background services, tests * 1.1M+ lines of JS / TS Across 9 web applications * 18 platform releases In the last 12 months, plus patches * 60+ integration partners Labs, imaging, pharmacy, comms * SOC 2 Type II Independently examined Line counts are code lines only: blanks, comments, generated code, and vendored libraries are excluded. ## Platform overview [Section titled “Platform overview”](#platform-overview) The [Architecture](/about/architecture/) page has the full diagram. In short: ### Applications [Section titled “Applications”](#applications) Nine web applications share one backend: the clinic app, the multi-location group platform, online forms, the pet owner portal, Shepherd Pay, the insurance and wellness marketplace, and supporting apps. Clinic teams reach them at `app.shepherd.vet` and related subdomains, through Amazon CloudFront and AWS WAF. ### Compute [Section titled “Compute”](#compute) * **Web app and API servers**: .NET on Amazon EC2, released blue/green so a new version takes traffic only once it is healthy, with automatic scale-out and scale-in. * **Open API servers**: a separate fleet behind its own load balancer and firewall, serving partner integrations at `open-api.shepherd.vet/pav2/`. Partner traffic runs on its own servers, so it doesn’t compete with clinic teams for web capacity. * **Background services**: background job runners, the report runner, and the real-time push hub that keeps open screens up to date. * **AI services**: containerized services on Amazon ECS (Fargate) for the AI scribe, transcription, and assistant features, kept off the request path. * **Serverless functions**: AWS Lambda for PDF and image rendering, file archiving, and fleet scaling. ### Data [Section titled “Data”](#data) * **PostgreSQL 16 on Amazon RDS**, in Multi-AZ deployments with read replicas. Clinic data is **sharded** across database clusters; the API hides this from callers. See [Data model](/guides/data-model/). * **Amazon ElastiCache (Valkey)** for sessions, real-time fan-out, and hot-path caching. * **Amazon S3** for attachments and documents: lab reports, imaging, PDFs, recordings. * **Amazon SQS** queues move reports, AI summaries, and messaging events off the request path. * **Disaster recovery** in a second AWS region: every production database has a cross-region replica, and production files are replicated continuously. ### Integrations [Section titled “Integrations”](#integrations) Shepherd exchanges data with 60+ partners, including: * **Labs**: IDEXX, Antech, Zoetis, Heska, Moichor, and others. * **Imaging**: Asteris Keystone, Sound SmartPACS, SignalPET, Radimal, and others. * **Pharmacy and inventory**: Vetsource, Covetrus, MWI Animal Health, Vetcove, Cubex, and others. * **Communications**: PetDesk, Weave, Otto, AllyDVM, and others. * **Payments and financing**: Shepherd Pay, CareCredit, Sunbit. The full list, with setup guides, is in the Help Center’s [Integrations & Data Connections](https://help.shepherd.vet/en/collections/3426100-integrations-data-connections) collection. Building a new one? Start with the [API Reference](/api-reference/) and the [first integration tutorial](/tutorials/first-integration/). ## Engineering principles [Section titled “Engineering principles”](#engineering-principles) * **Single source of truth for schemas.** The live Swagger UI is the authoritative schema reference. This site adds the concepts, tutorials, and code samples around it, and we [test what we publish](/api-reference/how-we-verify/) against the live API. * **Tenancy isolation by default.** Every integration key is granted to specific clinics, and every request names exactly one clinic. See [Authentication](/api-reference/authentication/). * **Backwards compatibility on the public API.** Breaking changes ride a new major version; deprecations are announced on the [blog](/blog/) before removal. * **Security is audited, not assumed.** See [Security & trust](/about/security/) for our SOC 2 Type II report, backups, and access controls. # API Reference > REST API for the Shepherd veterinary practice-management platform. The Shepherd API is a JSON REST API for building integrations on top of the Shepherd practice-management platform: labs, imaging, pharmacy, fintech, AI, and anything else a modern clinic plugs into. Live API reference Authoritative request and response schemas for every endpoint are published in the **live Swagger UI** at [app.shepherd.vet/swagger/](https://app.shepherd.vet/swagger/). This site complements the Swagger with concepts, conventions, end-to-end tutorials, and code samples in curl, Python, C#, PHP, and JavaScript. The behavior it describes is [tested against the live API](/api-reference/how-we-verify/), not only read from the schema. ## At a glance [Section titled “At a glance”](#at-a-glance) * **Production:** `https://open-api.shepherd.vet/pav2/` * **Sandbox:** `https://demo-open-api.shepherd.vet/pav2/` * **Transport:** `POST` with `Content-Type: application/json` for reads, searches, and creates; `PUT` for the five update endpoints. * **Auth:** dual API-key headers (`X-Integration-Public-Key`, `X-Integration-Private-Key`) plus a per-clinic `X-Clinic-Id` (every endpoint except the clinic lookup). ## Where to next [Section titled “Where to next”](#where-to-next) * [Overview](/api-reference/overview/): environments, transport, and HTTP-client guidance. * [Authentication](/api-reference/authentication/): API keys, the per-clinic scope model, and a working “hello world”. * [Conventions](/api-reference/conventions/): pagination, embedding, sorting, date filters, and the collection envelope. * [Errors](/api-reference/errors/): status codes and the error body shapes. * [Rate limits](/api-reference/rate-limits/): per-key limits, how requests are counted, querying remaining usage, and retry guidance. * [How we verify](/api-reference/how-we-verify/): how we test this reference against the live API with a purpose-built test harness, and what the latest run changed. New to the platform? Start with the [first-integration tutorial](/tutorials/first-integration/) and you’ll be reading live data in about ten minutes. # Generated reference (placeholder) > Replace this stub once the OpenAPI generator is wired up. The API reference will be regenerated here from the live OpenAPI spec. # Authentication > API-key headers and the per-clinic scope model for the Shepherd API. The Shepherd API uses two API keys plus a clinic identifier, all sent as request headers. There is no OAuth flow, no Bearer token, and no token-refresh dance for the primary integration path. ## The three headers [Section titled “The three headers”](#the-three-headers) Every request includes the following headers: | Header | Required | Purpose | | --------------------------- | ------------------------------------------- | ---------------------------------------------------------------- | | `X-Integration-Public-Key` | Yes | Identifies your integration. | | `X-Integration-Private-Key` | Yes | Proves ownership of the integration. Treat this like a password. | | `X-Clinic-Id` | On every endpoint except `open-api-clinics` | The clinic UUID this request operates against. | Both keys must be sent on every call. The public key is not a “client ID”; both values are secret, and the private key in particular must never be embedded in mobile apps, browser code, or anywhere a third party can read it. Send each key exactly as issued: the public key is a lowercase UUID and the comparison is case-sensitive, so an upper-cased key is rejected as `Incorrect API keys provided`. Send each header once. `X-Clinic-Id` is a header, not a body field The clinic id travels as a request **header**, the same as your two keys. Putting a `clinicId` in the JSON body does nothing: the request is still rejected with `401 Missing X-Clinic-Id header`. Set the `X-Clinic-Id` header on every call. The only endpoint that accepts a call without it is the clinic lookup, `POST /pav2/open-api-clinics` (covered below), which lets you discover a clinic’s UUID before you have one to send. The group lookup, `open-api-groups`, does need it: it returns the group of the clinic you name. ## How keys are issued [Section titled “How keys are issued”](#how-keys-are-issued) How you get keys depends on who you are. **Clinic accounts building on their own data.** If your Shepherd account has the open API feature enabled, you can generate and manage integration keys yourself from inside Shepherd (Admin → Integrations). These are self-service. You’ll normally build against your live clinic; ask your account manager if you’d like a separate sandbox first. **Integration partners building for other clinics.** The Shepherd product team issues your keys as part of integration onboarding: 1. You’ll get sandbox credentials first, scoped to a demo clinic, so you can build and test against `https://demo-open-api.shepherd.vet/pav2/`. 2. Production credentials are issued once your integration is reviewed and the partner clinic agrees to enable it. Either way, read the keys from environment variables or a secrets manager; never hard-code them. ## Key rotation [Section titled “Key rotation”](#key-rotation) Rotate the private key any time you suspect exposure. Because both keys are checked on every request, the safest pattern is: 1. Request a second active key from the Shepherd team. 2. Deploy the new key alongside the old one (most clients can hot-swap an environment variable). 3. Confirm traffic is flowing under the new key. 4. Ask the Shepherd team to revoke the old key. Build your integration so the keys are read from environment variables or a secrets manager, never hard-coded. ## The per-clinic scope model [Section titled “The per-clinic scope model”](#the-per-clinic-scope-model) The Shepherd API is multi-tenant. A single integration key can be granted access to one clinic or many, but every request operates against exactly one clinic at a time, named by `X-Clinic-Id`. There is no single call that returns data across every clinic at once. To cover a clinic group, change `X-Clinic-Id` between requests; or, where the relevant data is shared across the group, scope a query with a `clinicIds` filter. See [Groups and multi-site](/guides/groups-and-multi-site/) for how that works, and the [Clinics](/api-reference/resources/clinics/) endpoint for discovering the clinic UUIDs your keys can reach. The clinic id must be a UUID your keys are linked to. A malformed value fails with a `500` on every endpoint. A well-formed id your keys are not linked to (a typo, or an id from the other environment) returns `401 Integration not enabled for the provided clinic`, the same response as a clinic that has not yet enabled your integration, so check the id against the clinic lookup before you look anywhere else. ## Hello world [Section titled “Hello world”](#hello-world) The shortest end-to-end check is to fetch one clinic record. If the credentials are valid for at least one clinic, this returns a collection envelope with a single item. If the keys are wrong, you’ll get an HTTP 401 whose body is a JSON string explaining why. This is the one call where `X-Clinic-Id` is optional. The samples send it because every later call needs it; if you don’t have a clinic id yet, leave that header out entirely rather than sending an empty or placeholder value, and read the `id` of each returned clinic. * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-clinics \ -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":1}' ``` * Python ```python import os, requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-clinics", 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": 1}, timeout=30, ) resp.raise_for_status() data = resp.json() print(f"Total clinics visible: {data['totalRecords']}") ``` * 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 = 1 }); var resp = await http.PostAsync( "https://open-api.shepherd.vet/pav2/open-api-clinics", body); resp.EnsureSuccessStatusCode(); var json = await resp.Content.ReadAsStringAsync(); Console.WriteLine(json); ``` * 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' => 1]), ]); $response = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch); echo "HTTP $status\n$response\n"; ``` * JavaScript ```js const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-clinics', { 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: 1 }), }); if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`); const data = await resp.json(); console.log(`Total clinics visible: ${data.totalRecords}`); ``` If that returns `200 OK` with a JSON body, you are authenticated. From here, read [Conventions](/api-reference/conventions/) to learn pagination, embedding, and date filtering, then jump into the resource pages. # Conventions > Request and response conventions used across the Shepherd API. The Shepherd API is consistent across resources. Once you know the conventions on this page, every endpoint reads about the same. ## POST almost everywhere [Section titled “POST almost everywhere”](#post-almost-everywhere) Reads, searches, creates, and actions accept `POST` with `Content-Type: application/json` and a JSON object body, distinguished by the URL path. Send `{}` when there are no filters: an empty body or a JSON `null` fails with a `500`, not a `400`. There are no `GET`, `PATCH`, or `DELETE` verbs. See [Overview](/api-reference/overview/) for the reasoning. The exception is updating an existing record. Five endpoints use `PUT`: | Resource | Update endpoint | | ------------ | --------------------------------------------- | | Clients | `PUT /pav2/open-api-clients/{id}/update` | | Patients | `PUT /pav2/open-api-patients/{id}/update` | | Appointments | `PUT /pav2/open-api-appointments/{id}/update` | | Task entries | `PUT /pav2/open-api-task-entries/update/{id}` | | Task notes | `PUT /pav2/open-api-task-notes/update/{id}` | Note that the two task routes put `update` before the id. A wrong verb, or a path that does not start with `/pav2/open-api-`, returns `405`. Always use `https`. Plain `http` is redirected, and most HTTP clients turn a redirected `POST` into a `GET`, which then fails in confusing ways. ## Updating records is a full replacement [Section titled “Updating records is a full replacement”](#updating-records-is-a-full-replacement) Update endpoints are `PUT`, and they mean it. A `PUT` submits the **complete** representation of the record, so **any editable field you omit is interpreted as an intentional change and is cleared**: set to null, empty, or its default. It is not a partial update, and there is no `PATCH`. This catches integrators out most often on collections and links. Omit `patientIds` on an appointment update and every patient is removed from the appointment; omit `preferredProviderIds` on a patient, or the assignments on a task, and those links are gone. If you send a client update whose `clientCoOwner` block has no `clientCoOwnerPhones` array, you are telling the API the co-owner has no phone numbers, and the existing ones are removed. A partial body is a destructive body Never build an update payload from just the fields you want to change. On a `PUT` endpoint that is a delete instruction for everything else. ### Read, merge, write [Section titled “Read, merge, write”](#read-merge-write) The safe pattern, and the one we recommend for any synchronisation logic, is three steps: 1. **Read** the current record by id, embedding every nested collection you are about to send back. 2. **Merge** your changes into that full representation in memory. 3. **Write** the merged whole back to the update endpoint. ```text POST read by id ──► apply your changes ──► PUT the complete object (with embeds) (in memory) (nothing omitted) ``` Step 1 is where most data loss originates: if the read did not include a nested collection, the merged object will not contain it either, and the write will clear it. Embed defensively. Some update fields have a different name, or a different shape, from the record you read. Map them in step 2: | Update field | Take it from the record you read | | ------------------------------ | ---------------------------------------------------------------------------- | | appointment `patientIds` | `appointmentPatients[].patientId` | | patient `preferredProviderIds` | `patientPreferredProviders[].providerId` (embed `patientPreferredProviders`) | | patient `referralSourceIds` | `patientReferralSources[].referralSourceId` (embed `patientReferralSources`) | | task `assignedToUsersIds` | `taskAssignedToUsers[].user.id` (embed `taskAssignedToUsers`) | | task `assignedToTeamsIds` | `taskAssignedToTeams[].team.id` (embed `taskAssignedToTeams`) | There is no optimistic concurrency: the last write wins. If staff edit the record between your read and your write, your write overwrites their change, so read immediately before writing. ### Fields that survive omission [Section titled “Fields that survive omission”](#fields-that-survive-omission) A few fields are deliberately exempt from the full-replace rule, either because they are immutable or because they are managed elsewhere: | Resource | Preserved when omitted | Behaves differently | | ----------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Client | `clientStatusId`, the `clientInfo` contact block | `authorizedAgents` is an edit list (below). Home clinic, system identifiers, and deleted status cannot be changed here. | | Patient | (none) | The client association and weight cannot be changed here; add weight entries instead. | | Appointment | (none) | An omitted `appointmentStatusId` **resets the status to upcoming**. | | Task entry | `taskEntryPriorityStatusId`, `taskEntryStatusId`, `dateDue` | Omitted `name`, `description`, `clientId`, `patientId`, and assignments are cleared. | | Task note | everything except `note` | Only `note` can change. | `authorizedAgents` on a client update is a further exception: it is an explicit edit list rather than a replacement. Each entry adds an agent (omit `id`), edits one in place (include `id`), or removes one (set `authorizedAgentIdForRemove` with a `removalNote`). Agents you do not reference are left untouched. Everything not listed above follows the full-replace rule. ### Responses [Section titled “Responses”](#responses) Update success codes differ by resource. Treat any `2xx` as success and don’t require a body. | Update | Success response | | ------------------------ | -------------------------------- | | Clients, patients | `200 OK` with the updated record | | Task entries | `200 OK` with no body | | Appointments, task notes | `204 No Content` | A `404` means the `{id}` in the path does not resolve within the clinic named by `X-Clinic-Id`. ## The collection envelope [Section titled “The collection envelope”](#the-collection-envelope) List endpoints return a wrapper, not a bare array. The shape is: ```json { "item": [ /* the records on this page */ ], "totalRecords": 1432, "page": 1, "recordsPerPage": 10, "sort": "dateCreated|desc", "searchQuery": null, "embed": "clients,clientPhones.phoneType", "links": [] } ``` A few things worth noting: * `item` is always an array, even when there is one record. * `totalRecords` is the total across all pages, not just this page. * `recordsPerPage` is the page size the API actually used, which can be smaller than the `rpp` you asked for. * `links` is currently always empty. Do not depend on it. * `sort`, `searchQuery`, and `embed` echo what you sent in the request, not what the API applied. An echoed `sort` does not mean the sort was used (see [Sorting](#sorting)). Creates and updates return the record itself (or nothing), not the envelope. ## Pagination [Section titled “Pagination”](#pagination) Pagination is driven by two body fields: | Field | Default | Valid values | Notes | | ------ | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- | | `page` | 1 | 1 or more | 1-indexed. | | `rpp` | 10 | 1 to 1000 | Records per page. 100 or less on teams, the schedule-template endpoints, physical exams, and SOAP discharge instructions. | * **`rpp` and `page` below 1, or `null`, are rejected** with `400` `The request is invalid.` * **Some records are large.** Physical exams and SOAP discharge instructions run about 12 KB to 20 KB per record, so a 1000-record page is over 10 MB. Keep `rpp` at 100 or less on those two. * **An `rpp` above 1000 is not rejected; it is silently reduced to 1000.** Compare `recordsPerPage` in the response to what you sent, and page on the value the API used. * **Keep `page * rpp` at or below 10,000.** Patient notes reject deeper pages with `HTTP 400`; on other endpoints deep pages are not rejected but get slower with every page. Either way, the fix for a large result set is a narrower filter (typically a shorter date window), not deeper paging. Stop paging when `page * rpp` reaches `totalRecords` or a page comes back empty. When paging a date window, fix both ends of the window before the first page, so records changing mid-run do not shift between pages. ## Filtering [Section titled “Filtering”](#filtering) * **Id filters** such as `ids`, `clientIds`, and `patientIds` are comma-separated strings of UUIDs, not JSON arrays. Every value must be a valid UUID: a malformed id produces a `500`, not a `400`. Keep lists to about 100 ids per request and batch the rest. * **`searchQuery`** is free text; what it matches depends on the endpoint. At most 500 characters and 10 words. * **Unknown fields are ignored, not rejected.** A misspelled filter name is silently dropped, so the request runs without that filter. Copy field names from the [schema](https://app.shepherd.vet/swagger/) exactly. * **A few endpoints ignore fields their schema lists.** See [Fields an endpoint does not apply](#fields-an-endpoint-does-not-apply). ### Fields an endpoint does not apply [Section titled “Fields an endpoint does not apply”](#fields-an-endpoint-does-not-apply) The schema for most list endpoints includes the standard date pairs and id filters. On the endpoints below, some of those fields are accepted without an error but are **not applied**, so they do not narrow the result. A request bounded only by one of them returns the endpoint’s full, unfiltered set. | Endpoint | Accepted but not applied | Filter with | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `POST /pav2/open-api-inventory/transaction-journals` | `dateCreatedFrom`/`To`, `dateUpdatedFrom`/`To`, `ids`, `excludeIds`, `productIds` | `dateFrom`/`dateTo` (the transaction date, one month at most), `inventoryProductSettingIds`, `userIds` | | `POST /pav2/open-api-client-balances/balances` | `dateCreatedFrom`/`To`, `ids`, `excludeIds`, `embed` | `dateUpdatedFrom`/`To`, `clientIds`, `clientClinicAccountIds` | | `POST /pav2/open-api-provider-schedule-templates` | `dateCreatedFrom`/`To`, `dateUpdatedFrom`/`To`, `excludeIds`, `isDeleted` | `startDate`/`endDate`, `providerIds` | | `POST /pav2/open-api-schedule-template-appointments` | `dateCreatedFrom`/`To`, `dateUpdatedFrom`/`To`, `excludeIds` | `startDate`/`endDate`, `scheduleTemplateIds` | | `POST /pav2/open-api-schedule-templates` | `dateCreatedFrom`/`To`, `dateUpdatedFrom`/`To`, `excludeIds` | `ids` (there is no date filter) | | `POST /pav2/open-api-inventory-status` | `dateCreatedFrom`/`To`, `dateUpdatedFrom`/`To` | `ids`, `searchQuery` | | `POST /pav2/open-api-physical-exams` | `creationDateFrom`/`creationDateTo` | `dateCreatedFrom`/`To` | A few small reference endpoints also ignore a field: `excludeIds` on clinics and the credit-balance aging report, `ids` on groups (the response is always the group of the clinic in `X-Clinic-Id`), `isDeleted` on locations, and `embed`, `ids`, and `excludeIds` on messaging settings. ## Embedding related entities [Section titled “Embedding related entities”](#embedding-related-entities) Most endpoints accept an `embed` field with comma-separated dot-paths. The API inlines the named relations into the response instead of returning only their IDs. ```json { "page": 1, "rpp": 50, "embed": "clients,clientPhones.phoneType" } ``` Dot-paths walk relationships. `clientPhones.phoneType` inlines the phones on each client and the phone-type lookup record for each phone. Without an embed, related objects come back `null` or `[]`, while the `...Id` fields are always present. Unknown embed names are ignored. Embeds multiply the work the API does per record, so be deliberate: * Embed only what your code reads, one or two levels deep. * Keep `rpp` at 250 or less when embedding. * Keep `rpp` at 50 or less with these embeds: `appointmentPatients.patient` on appointments, `soapTreatmentSchedulers` on treatments, and `clinics` or `clinicBodyMaps` on groups. * For stable reference data (breeds, statuses, phone types), read the lookup once, cache it, and join in memory instead of embedding it on every request. ## Sorting [Section titled “Sorting”](#sorting) Sort with the `sort` field. The format is `field|direction`, where direction is `asc` or `desc`: ```json { "sort": "dateCreated|desc" } ``` Only one sort key at a time is honored. Sort on top-level fields of the returned record. **Most endpoints do not reject a sort they cannot apply.** A field that doesn’t exist, or a direction other than `asc` or `desc`, returns `200` with the records in the endpoint’s default order, and the envelope’s `sort` still shows what you sent. In a paged sync, a misspelled sort quietly changes which records land on which page, so check sort field names against the schema. A few endpoints do reject: some with `400`, and two with `501`: * `client-balances/balances`: sorting by `dateCreated`, or by any field whose name contains `id`. * `inventory-status`: sorting by `dateCreated` or `dateUpdated`. ## Date-range filtering [Section titled “Date-range filtering”](#date-range-filtering) Most list endpoints accept date pairs: * `dateCreatedFrom` / `dateCreatedTo` * `dateUpdatedFrom` / `dateUpdatedTo` Some resources add their own, such as `dateFrom` / `dateTo` for an appointment’s scheduled time (on appointments, `dateCreatedFrom` / `dateCreatedTo` filter when the booking was made, not when the visit is). A few endpoints use only their own pair and ignore the standard ones; see [Fields an endpoint does not apply](#fields-an-endpoint-does-not-apply). **Send both ends of a pair, and keep each window to one calendar month or less.** To pull a longer span, sweep month by month. Patient notes enforce this: they reject a request with no date pair, with only one end of a pair, or with a window wider than one month, even when the request also filters by `ids` or `patientIds`. A window that ends before it starts is rejected with a `400` (except on the endpoints that do not apply that pair, where it is ignored like the rest of the pair). Other endpoints accept wider or open-ended windows, but those are the requests that get slow on large clinics, so treat the same rule as required everywhere you list clinical or financial data. Timestamps are ISO 8601 in UTC, for example `2026-04-01T00:00:00Z`. Convert clinic-local days to UTC bounds yourself. ## Soft deletes [Section titled “Soft deletes”](#soft-deletes) Deleted records are usually soft-deleted, and **list endpoints return them by default**. On clients, patients, appointments, invoices, and the other resources whose filter has an `isDeleted` field, omitting it includes deleted records. Send `"isDeleted": false` for a live view; a sync that must propagate deletions should read them and apply the flag. The flag on the returned record is `deleted` on some resources (clients, patients, SOAP records, treatments) and `isDeleted` on others (appointments, invoices, payments, products, inventory, reminders, tasks). Check the schema for the resource you read. ## Timestamps [Section titled “Timestamps”](#timestamps) Every record includes: * `dateCreated`: when the record was first created, ISO 8601 UTC. * `dateUpdated`: when the record was last modified, ISO 8601 UTC. Use `dateUpdated` for incremental syncs (paired with `dateUpdatedFrom`/`dateUpdatedTo`). ## Example: paginating patients [Section titled “Example: paginating patients”](#example-paginating-patients) The following pulls the second page of 100 patients updated in May 2026, sorted by most-recent update, with each patient’s breed inlined: * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients \ -H "Content-Type: application/json" \ -H "X-Integration-Public-Key: $SHEPHERD_PUBLIC_KEY" \ -H "X-Integration-Private-Key: $SHEPHERD_PRIVATE_KEY" \ -H "X-Clinic-Id: $SHEPHERD_CLINIC_ID" \ -d '{"page":2,"rpp":100,"sort":"dateUpdated|desc","embed":"breed","dateUpdatedFrom":"2026-05-01T00:00:00Z","dateUpdatedTo":"2026-06-01T00:00:00Z"}' ``` * Python ```python import os, requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-patients", headers={ "Content-Type": "application/json", "X-Integration-Public-Key": os.environ["SHEPHERD_PUBLIC_KEY"], "X-Integration-Private-Key": os.environ["SHEPHERD_PRIVATE_KEY"], "X-Clinic-Id": os.environ["SHEPHERD_CLINIC_ID"], }, json={ "page": 2, "rpp": 100, "sort": "dateUpdated|desc", "embed": "breed", "dateUpdatedFrom": "2026-05-01T00:00:00Z", "dateUpdatedTo": "2026-06-01T00:00:00Z", }, timeout=30, ) resp.raise_for_status() data = resp.json() print(f"Page {data['page']} of {-(-data['totalRecords'] // data['recordsPerPage'])}") for patient in data["item"]: print(patient["id"], (patient.get("breed") or {}).get("name")) ``` * C# ```csharp using System.Net.Http.Json; 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 = 2, rpp = 100, sort = "dateUpdated|desc", embed = "breed", dateUpdatedFrom = "2026-05-01T00:00:00Z", dateUpdatedTo = "2026-06-01T00:00:00Z", }); var resp = await http.PostAsync( "https://open-api.shepherd.vet/pav2/open-api-patients", body); resp.EnsureSuccessStatusCode(); var json = await resp.Content.ReadAsStringAsync(); Console.WriteLine(json); ``` * PHP ```php 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' => 2, 'rpp' => 100, 'sort' => 'dateUpdated|desc', 'embed' => 'breed', 'dateUpdatedFrom' => '2026-05-01T00:00:00Z', 'dateUpdatedTo' => '2026-06-01T00:00:00Z', ]), ]); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); foreach ($data['item'] as $patient) { echo $patient['id'] . "\t" . ($patient['breed']['name'] ?? '') . "\n"; } ``` * JavaScript ```js const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-patients', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Integration-Public-Key': process.env.SHEPHERD_PUBLIC_KEY, 'X-Integration-Private-Key': process.env.SHEPHERD_PRIVATE_KEY, 'X-Clinic-Id': process.env.SHEPHERD_CLINIC_ID, }, body: JSON.stringify({ page: 2, rpp: 100, sort: 'dateUpdated|desc', embed: 'breed', dateUpdatedFrom: '2026-05-01T00:00:00Z', dateUpdatedTo: '2026-06-01T00:00:00Z', }), signal: AbortSignal.timeout(30_000), }); if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`); const data = await resp.json(); console.log(`Page ${data.page} of ${Math.ceil(data.totalRecords / data.recordsPerPage)}`); for (const patient of data.item) { console.log(patient.id, patient.breed?.name); } ``` ## Next [Section titled “Next”](#next) * [Errors](/api-reference/errors/) for the error body shapes and status codes. * [Rate limits](/api-reference/rate-limits/) for how aggressive you can be with paging loops. # Errors > HTTP status codes, the error body shapes returned by the Shepherd API, and which failures to retry. When a request fails you get a non-2xx HTTP status and, usually, a body explaining why. There is no single error envelope: depending on where the request was rejected, the body is a JSON string, a JSON object, plain text, empty, or (when a request runs too long) an HTML page. Build your client to read the response body as text on every failure and to tolerate all five. ## Status codes [Section titled “Status codes”](#status-codes) | Status | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 200, 201, 204 | Success. Creates usually return `201`; updates return `200` or `204` depending on the resource, sometimes with no body. Treat any `2xx` as success and don’t require a body. | | 400 | Bad request. Validation failed, a business rule rejected the call, or a limit was exceeded (for example the patient-notes date window or paging ceiling). See “Handled exceptions” below. | | 401 | Unauthorized. A required auth header is missing (including `X-Clinic-Id`), the API keys are missing or mismatched, or the integration is not enabled for the clinic. A clinic id your keys are not linked to also returns `401`, not `403`. See “Common failure states” below. | | 403 | Forbidden. The keys are valid, but the key’s permissions do not cover the requested endpoint or record. | | 404 | Not found. The id does not exist within the clinic named by `X-Clinic-Id`, or the `open-api-` route does not exist. On client creates, a validation failure can also come back as `404`. | | 405 | Method not allowed. The wrong HTTP verb, or a path that does not start with `/pav2/open-api-`. | | 409 | Conflict. The record is locked by a clinical workflow (for example a locked visit record), the patient is flagged for merge, or the value is a duplicate. | | 429 | Too many requests. You exceeded a [rate limit](/api-reference/rate-limits/). | | 500 | Server error. On this API a `500` is almost always caused by the request: an empty or `null` body, or a malformed UUID in `X-Clinic-Id` or a comma-separated id filter (such as `ids` or `clientIds`). Check those before anything else. | | 501 | Not implemented. The endpoint does not support the `sort` you sent. Only two endpoints do this; most ignore an unsupported sort instead (see [Sorting](/api-reference/conventions/#sorting)). | | 502, 503 | Temporarily unavailable. A `503` whose body is `"ERRORS.MAINTENANCE_MODE"` means planned maintenance. | Every authenticated request counts against your rate limit, including every rejected one in this table. ## Error body shapes [Section titled “Error body shapes”](#error-body-shapes) Which shape you get depends on how far the request travelled before it was rejected. ### 1. A bare JSON string [Section titled “1. A bare JSON string”](#1-a-bare-json-string) Rules enforced inside the endpoint (business rules, limits, authentication failures, and the API’s own `429`) return the message as a **JSON-encoded string**: the body is a quoted string, not an object. Many messages are translation keys rather than sentences. ```http HTTP/1.1 400 Bad Request Content-Type: application/json; charset=utf-8 "Difference of DateCreated filter 'From' and 'To' can't be more than 1 month. Refer to 'bulk-export' endpoint for requested resource." ``` ```http HTTP/1.1 400 Bad Request Content-Type: application/json; charset=utf-8 "PATIENT.ERRORS.PATIENT_NOT_BELONG_TO_CLIENT" ``` Parsing this yields a plain string, so `JSON.parse(body)` gives you the message directly. Note the surrounding quotes are part of the body; if you print the raw text without parsing, they will show up in your logs. ### 2. A validation envelope [Section titled “2. A validation envelope”](#2-a-validation-envelope) Requests rejected before the endpoint runs return an **object**. That covers a missing required field, a value that cannot be bound to its type, `rpp` or `page` below 1 or `null`, and a date window that ends before it starts. The message is always `The request is invalid.`; the other fields vary by case: ```http HTTP/1.1 400 Bad Request Content-Type: application/json { "message": "The request is invalid.", "statusCode": 400, "details": null, "error": null, "modelState": null } ``` This shape does not currently name the failing field `modelState` is where per-field detail would appear, but on the public API surface it commonly comes back `null`, leaving only the generic “The request is invalid.” message. When you hit this, the request was rejected for a **structural** reason: a required field missing, or a value that could not be bound to its type (a malformed GUID or an unparseable date in the request body). Check the required-field list for the endpoint you are calling before looking for anything subtler. Improving this response is on the backlog. ### 3. Plain text [Section titled “3. Plain text”](#3-plain-text) The rate-limiting layer in front of the API rejects excess traffic before it reaches the API, with the same message as the API’s own `429` but as plain text: ```http HTTP/1.1 429 Too Many Requests Content-Type: text/plain Request rate limit exceeded. Please wait before making further requests. ``` ### 4. An empty body [Section titled “4. An empty body”](#4-an-empty-body) Some `400`, `403`, `404`, and `409` responses carry no body at all. Fall back to the status code. ### 5. An HTML error page [Section titled “5. An HTML error page”](#5-an-html-error-page) A gateway in front of the API cuts off any request that runs longer than about 120 seconds and returns an HTML error page instead of JSON. This is not an API error message; it means the request took too long. Do not show or log the HTML as the error message, and do not send the same request again unchanged. Requests are most likely to hit this limit during the nightly peak, 00:00 to 04:30 UTC. See [When to schedule nightly syncs](/api-reference/rate-limits/#when-to-schedule-nightly-syncs). A safe reader handles all five: read the body as text; if it is empty, use the status; otherwise try to parse it as JSON, use the result if it is a string, read `.message` if it is an object, and fall back to the status and a short excerpt of the raw text if it is not JSON (that covers plain text and HTML). ## Handled exceptions [Section titled “Handled exceptions”](#handled-exceptions) The API distinguishes between two flavors of `400`: * **Validation errors:** the request shape is wrong or a required field is missing (shape 2), or a limit was exceeded, such as the patient-notes date window or paging ceiling (shape 1). * **Handled exceptions:** the request was well-formed but a business rule rejected it (for example, booking an appointment into a provider’s break, or linking a task to a patient who does not belong to the task’s client). These return `400` with the business message in shape 1. They are not transient; retrying without changes will fail again. Treat 400 as “fix the request, then send it again”; do not put a retry loop around it. ## Common failure states [Section titled “Common failure states”](#common-failure-states) Most support requests come down to a handful of conditions. Unless noted, the messages below arrive as bare JSON strings (shape 1 above). The fix is almost always client-side. | Response body | Status | What it means | How to fix | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Missing X-Clinic-Id header` | 401 | The clinic identifier was not sent. It is an HTTP **header**, not a body field; a `clinicId` placed in the JSON body is ignored. | Send `X-Clinic-Id` with the clinic’s UUID on every call except `open-api-clinics`. See [Authentication](/api-reference/authentication/). | | `Missing X-Integration-Public-Key header` / `Missing X-Integration-Private-Key header` | 401 | One of the two key headers is absent. | Send both key headers on every request. | | `Incorrect API keys provided` | 401 | The public/private pair does not match a known integration, a key was revoked, the keys belong to the other environment (sandbox versus production), or the public key’s casing was changed. | Recheck the pair and the base URL, and send the public key in lowercase exactly as issued; rotate the key if you suspect exposure. | | `Integration not enabled for the provided clinic` | 401 | The keys are valid, but this integration has not been turned on for that clinic, **or your keys are not linked to that clinic at all**: a mistyped clinic id, or one from the other environment, gets this same response. | Check the id against `POST /pav2/open-api-clinics`, which lists the clinics your keys can reach. If it is listed, the clinic enables your integration on their side; partners confirm this during onboarding. Skip that clinic until then. | | `You don't have sufficient permissions to access the requested resource, please contact the support` | 403 | The keys are valid, but the key’s permissions do not include this endpoint or record. | Do not retry. Contact your Shepherd account manager about the key’s access. | | `Request must contain either DateCreated or DateUpdated filter parameters. Refer to 'bulk-export' endpoint for requested resource.` | 400 | Patient notes were listed without a date window. | Send a `dateCreatedFrom` / `dateCreatedTo` or `dateUpdatedFrom` / `dateUpdatedTo` pair. | | `DateCreated filter must define values for both 'From' and 'To'. Refer to 'bulk-export' endpoint for requested resource.` (or `DateUpdated`) | 400 | Only one end of a patient-notes date pair was sent. | Send both ends. | | `Difference of DateCreated filter 'From' and 'To' can't be more than 1 month. Refer to 'bulk-export' endpoint for requested resource.` (or `DateUpdated`) | 400 | The patient-notes date window is wider than one calendar month. | Keep each window to one calendar month; sweep month by month for longer spans. | | `Unable to read more than 10000 through this endpoint. Refer to 'bulk-export' endpoint for requested resource.` | 400 | `page * rpp` exceeded the 10,000-item ceiling on patient notes. | Narrow the date window, then page again. See [Conventions](/api-reference/conventions/). | | `ERROR_MESSAGES.SEARCH_PHRASE.TOO_LONG` / `ERROR_MESSAGES.SEARCH_PHRASE.TOO_MANY_PHRASES` | 400 | `searchQuery` is longer than 500 characters or has more than 10 words. | Shorten the search. | | `{"message":"The request is invalid."}` | 400 | A required field was missing, a value in the body could not be bound to its type (malformed GUID, unparseable date), `rpp` or `page` was below 1 or `null`, or a date window ended before it started. No field-level detail is returned. | Recheck the endpoint’s required fields and the format of every ID and date you sent. For patient writes see [Troubleshooting a rejected write](/api-reference/resources/patients/#troubleshooting-a-rejected-write). | | `PRESCRIPTION.ERROR.SOAP_LOCKED` / `PATIENT.EDIT.WARNING_MERGE_PATIENT` | 409 | The visit record is locked, or the patient is flagged for merge. | Do not retry; the clinic has to resolve it. | | `Unhandled error occurred, please contact support team.` | 500 | Almost always the request: an empty or `null` body, or a malformed UUID in `X-Clinic-Id` or an id filter. | Send `{}` as the minimum body and check every id. Do not retry; the same request fails the same way. | | `Request rate limit exceeded. Please wait before making further requests.` | 429 | You crossed a [rate limit](/api-reference/rate-limits/). From the API this is a JSON string; from the rate-limiting layer in front of it, the same text as plain text. | Wait until the start of the next UTC minute before sending anything else, then lower your steady-state rate. | | (no response, `504`, or an HTML error page) | | The request took too long. Requests running longer than about 120 seconds are cut off by the gateway, which returns an HTML page instead of JSON. | Do not send it again unchanged; make it cheaper (a shorter date window, a smaller `rpp`, fewer embeds), and keep scheduled syncs out of the nightly peak (00:00 to 04:30 UTC). See “Retrying” below. | The clinic id is a header, not a body field By far the most common error in the inbox is omitting `X-Clinic-Id`. It travels as a request header alongside your two integration keys, the same on every call. Putting a `clinicId` in the JSON body does nothing; the request is still rejected with `401 Missing X-Clinic-Id header`. The only endpoint that accepts calls without it is the clinic lookup, `open-api-clinics`, which exists precisely so you can discover a clinic’s UUID before you have one to send. ## Retrying [Section titled “Retrying”](#retrying) A simple, robust strategy: * **Do not retry:** `400`, `401`, `403`, `404`, `405`, `409`, `500`, `501`. These are caused by the request or its configuration, they count against your rate limit, and a retry just burns budget. A `500` belongs here too: on this API it is almost always caused by the request, so a retry fails the same way. * **Wait, then retry:** `429`. Wait until the start of the next UTC minute (or the next UTC hour if your hourly budget is spent). See [Rate limits](/api-reference/rate-limits/). * **Retry with exponential backoff and jitter:** `502` and `503`, for reads and updates, with a capped number of attempts. For a `503` maintenance response, back off for minutes, not seconds. * **Do not retry timeouts**, including a gateway cutoff (an HTML error page after about 120 seconds). A request that timed out may still be running on the server, and sending it again starts the same work alongside it. Make the request cheaper instead, or run it outside the nightly peak. * **Never retry a create automatically** (any `.../write`), whatever the failure: the first attempt may have succeeded, and a retry makes a duplicate. Check whether the record exists first. ## Reading the error body [Section titled “Reading the error body”](#reading-the-error-body) The pattern below works for any endpoint. On failure, read the raw body as text first, since that works whichever shape came back, then pull out the message: * curl ```sh # -w prints the HTTP status on a final line, -s silences the progress bar, # --max-time sets a timeout curl -sS --max-time 30 -X POST https://open-api.shepherd.vet/pav2/open-api-clients \ -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":10,"dateUpdatedFrom":"2026-05-01T00:00:00Z","dateUpdatedTo":"2026-06-01T00:00:00Z"}' \ -w "\nHTTP %{http_code}\n" ``` * Python ```python import json, os, requests def error_message(resp): text = resp.text.strip() if not text: return f"HTTP {resp.status_code}" try: parsed = json.loads(text) except ValueError: return text # plain text, for example a 429 from the rate-limiting layer if isinstance(parsed, str): return parsed if isinstance(parsed, dict) and parsed.get("message"): return parsed["message"] return text resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-clients", 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": 10, "dateUpdatedFrom": "2026-05-01T00:00:00Z", "dateUpdatedTo": "2026-06-01T00:00:00Z", }, timeout=30, ) if not resp.ok: raise RuntimeError(f"Shepherd {resp.status_code}: {error_message(resp)}") data = resp.json() ``` * C# ```csharp using System.Net.Http.Json; using System.Text.Json; static string ErrorMessage(int status, string text) { if (string.IsNullOrWhiteSpace(text)) return $"HTTP {status}"; try { using var doc = JsonDocument.Parse(text); if (doc.RootElement.ValueKind == JsonValueKind.String) return doc.RootElement.GetString()!; if (doc.RootElement.ValueKind == JsonValueKind.Object && doc.RootElement.TryGetProperty("message", out var m) && m.ValueKind == JsonValueKind.String) return m.GetString()!; } catch (JsonException) { // plain text, for example a 429 from the rate-limiting layer } return text; } 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 = 10, dateUpdatedFrom = "2026-05-01T00:00:00Z", dateUpdatedTo = "2026-06-01T00:00:00Z", }); var resp = await http.PostAsync( "https://open-api.shepherd.vet/pav2/open-api-clients", body); var text = await resp.Content.ReadAsStringAsync(); if (!resp.IsSuccessStatusCode) { throw new HttpRequestException( $"Shepherd {(int)resp.StatusCode}: {ErrorMessage((int)resp.StatusCode, text)}"); } ``` * 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' => 10, 'dateUpdatedFrom' => '2026-05-01T00:00:00Z', 'dateUpdatedTo' => '2026-06-01T00:00:00Z', ]), ]); $response = curl_exec($ch); if ($response === false) { throw new RuntimeException('Shepherd request failed: ' . curl_error($ch)); } $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch); if ($status < 200 || $status >= 300) { throw new RuntimeException("Shepherd $status: " . shepherd_error_message($status, $response)); } $data = json_decode($response, true); ``` * JavaScript ```js function errorMessage(status, text) { if (!text.trim()) return `HTTP ${status}`; try { const parsed = JSON.parse(text); if (typeof parsed === 'string') return parsed; if (parsed && typeof parsed.message === 'string') return parsed.message; } catch { // plain text, for example a 429 from the rate-limiting layer } return text; } const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-clients', { 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: 10, dateUpdatedFrom: '2026-05-01T00:00:00Z', dateUpdatedTo: '2026-06-01T00:00:00Z', }), signal: AbortSignal.timeout(30_000), }); if (!resp.ok) { const text = await resp.text(); throw new Error(`Shepherd ${resp.status}: ${errorMessage(resp.status, text)}`); } const data = await resp.json(); ``` ## Next [Section titled “Next”](#next) * [Authentication](/api-reference/authentication/) for the three headers, including the `X-Clinic-Id` header behind most `401`s. * [Rate limits](/api-reference/rate-limits/) for the specifics of 429 handling and backoff. * [Conventions](/api-reference/conventions/) for paging, date windows, and the patient-notes limits that produce a 400. * [Groups and multi-site](/guides/groups-and-multi-site/) for how clinic scoping works when data is shared across a group. # How we verify this reference > The Swagger describes the API's shape. We test its behavior against the live API with a purpose-built test harness, and correct these pages when the evidence disagrees. We publish the [Swagger UI](https://app.shepherd.vet/swagger/), and it is generated from the API’s own code, so it is the authority on the shape of every request and response: routes, fields, and types. What a schema cannot tell you is how the API behaves at the edges. Which values are rejected and which are quietly adjusted, which filters an endpoint actually applies, what a mistake costs, and which failures are worth retrying. That behavior is what breaks integrations in production, so we don’t document it from the schema alone. We test it against the real API and write down what we observe. ## The test harness [Section titled “The test harness”](#the-test-harness) We built a test harness, written in Python, that exercises the Shepherd API the way real integrations do, including the ways they commonly go wrong. It runs against the live production API, inside a dedicated test clinic that holds no real client or patient data. Each run: * **Calls every public read endpoint** with a minimal valid request and records the shape of the response. * **Probes the edges of every request convention.** Page sizes and page numbers at and past their limits, sort fields and directions that don’t exist, date windows that are malformed or run backwards, unknown fields and embeds, and request bodies that are empty, `null`, or not valid JSON. * **Tests authentication and clinic scoping.** Missing, wrong, and swapped keys; missing, malformed, and unlinked clinic ids; and whether any request can return records from a clinic other than the one it names. * **Creates and updates clearly marked test records** through the write endpoints that are safe to exercise, then reads each record back. Writes that could reach a real person, such as messages or appointment notifications, are never sent. * **Watches its own impact.** Requests are spaced out and stay far below the rate limit, and the run stops itself at the first sign of strain on the API. The harness records only the shape of each response (status, timing, size, field names and types), never the field values, so results can be kept and compared from one API release to the next. Every claim on these pages, and every rule in the [AI agent skill](/tools/agent-skill/), is checked against those results and against the API’s source code. ## What the evidence changed [Section titled “What the evidence changed”](#what-the-evidence-changed) The September 2026 runs covered API version 2.246.0.33 with about 4,500 requests. Where the results disagreed with what we had written, we corrected the pages: * **`rpp` and `page` below 1 are rejected** with a `400`, as is a date window that ends before it starts. We had said they were not rejected. * **A clinic your keys are not linked to returns `401`** (`Integration not enabled for the provided clinic`), not `403`. A `403` means the key’s permissions don’t cover that endpoint or record. See [Errors](/api-reference/errors/). * **An unsupported sort is usually ignored, not rejected.** Most endpoints return `200` in their default order; only a few return `400`, and two return `501`. See [Sorting](/api-reference/conventions/#sorting). * **Some endpoints accept filters they never apply.** For example, the inventory transaction journal filters on `dateFrom` / `dateTo` and ignores the standard `dateCreated` pair. See [Fields an endpoint does not apply](/api-reference/conventions/#fields-an-endpoint-does-not-apply). * **A `500` is almost always caused by the request,** typically an empty or `null` body or a malformed id. We now advise against retrying it at all. * **A few endpoints return very large records,** so we now recommend pages of 100 or less on them. * **The unfiltered breed list is far larger than a lookup should be,** so always filter it to the clinic. See [Lookups](/api-reference/resources/lookups/). The runs also confirmed much of what these pages already said: unknown fields and embeds are ignored rather than rejected, an `rpp` above 1000 is reduced to 1000, rejected requests count against your rate limit while the usage endpoint does not, a malformed clinic id fails with a `500`, and no request returned another clinic’s records. ## When we run it [Section titled “When we run it”](#when-we-run-it) We run the harness after API releases and before we publish changes to the API reference or the agent skill. Findings that are defects in the API, rather than in these pages, go to the engineering team; until a fix ships, these pages describe the API as it behaves today. If you see the API behave differently from what these pages say, [tell us](/contact/). Include the endpoint, the request body with credentials and clinic data removed, the status you got, and the time in UTC. # Overview > Environments, transport, and HTTP client guidance for the Shepherd API. The Shepherd API is a JSON REST API. Two environments are available: a sandbox for development and a production environment for live clinic data. ## Environments [Section titled “Environments”](#environments) | Environment | Base URL | | ----------- | ------------------------------------------ | | Production | `https://open-api.shepherd.vet/pav2/` | | Sandbox | `https://demo-open-api.shepherd.vet/pav2/` | Both environments speak the same protocol; switch by changing the base URL. Sandbox credentials and production credentials are issued separately. If you don’t have sandbox keys yet, contact your Shepherd account manager. ## Content type [Section titled “Content type”](#content-type) All requests and responses use `application/json`. Always send `Content-Type: application/json` on the request, and send a JSON body even when you have no filters to apply (an empty object `{}` is fine). ## Almost every endpoint is POST [Section titled “Almost every endpoint is POST”](#almost-every-endpoint-is-post) Every endpoint except the five updates below, including reads, accepts `POST` with a JSON request body. There are no `GET`, `PATCH`, or `DELETE` verbs in the public surface. Filters, pagination, embedding, and sort options all travel in the request body. For consistency, the API uses POST across the board so request shape is uniform regardless of the operation. If you are used to REST APIs that mix verbs, this trips up many developers on day one; the cure is to never reach for `GET` here. If a call returns `405 Method Not Allowed`, you almost certainly used the wrong verb. Always use `https`: plain `http` is redirected, and most HTTP clients turn a redirected `POST` into a `GET`. The one exception is updating an existing record. A handful of resources expose a `PUT` update endpoint alongside their POST create endpoint: | Update endpoint | Resource | | --------------------------------------------- | ------------------------------------------------------ | | `PUT /pav2/open-api-clients/{id}/update` | [Clients](/api-reference/resources/clients/) | | `PUT /pav2/open-api-patients/{id}/update` | [Patients](/api-reference/resources/patients/) | | `PUT /pav2/open-api-appointments/{id}/update` | [Appointments](/api-reference/resources/appointments/) | | `PUT /pav2/open-api-task-entries/update/{id}` | [Tasks](/api-reference/resources/tasks/) | | `PUT /pav2/open-api-task-notes/update/{id}` | [Tasks](/api-reference/resources/tasks/) | These are true `PUT` operations, which means they are **full replacements**: any editable field you leave out of the body is cleared, not left alone (a few fields per resource are the exception). Note that the task routes put `update` before the id. Read [Updating records](/api-reference/conventions/#updating-records-is-a-full-replacement) before you call one; sending a partial body is the single most common cause of accidental data loss against the Shepherd API. ## HTTP client recommendations [Section titled “HTTP client recommendations”](#http-client-recommendations) Any HTTP client that can send a JSON body with custom headers will work. A few notes from clinics shipping in production: * **Always set an explicit timeout.** 30 seconds is a reasonable upper bound for most endpoints. If a request needs longer, make it cheaper (a shorter date window, a smaller page, fewer embeds) rather than raising the timeout. * **Reuse a single client instance.** Most languages benefit from keep-alive connection pooling; cold sockets dominate latency on chatty integrations. Accept gzip (`Accept-Encoding: gzip`); JSON responses compress well. * **Read the response body on every status.** Error bodies are not a single consistent envelope (a JSON string, a JSON object, plain text, empty, or an HTML page from the gateway when a request runs longer than about 120 seconds); see [Errors](/api-reference/errors/) for how to read them. * **Retry selectively.** After a `429`, wait until the next UTC minute; retry `502` and `503` with capped exponential backoff and jitter. Do not retry timeouts, `4xx` responses, or creates. See [Rate limits](/api-reference/rate-limits/#retries-and-backoff). * **Schedule nightly jobs between 05:00 and 22:00 UTC.** The API is under its heaviest load from about 00:00 to 04:30 UTC, when many integrations sync at once. See [When to schedule nightly syncs](/api-reference/rate-limits/#when-to-schedule-nightly-syncs). ## Next [Section titled “Next”](#next) * [Authentication](/api-reference/authentication/) for the header model and a working “hello world”. * [Conventions](/api-reference/conventions/) for pagination, embedding, sorting, and date filtering. # Rate limits > Per-key minute and hour limits, how requests are counted, querying remaining usage, and retry guidance. Rate limits apply **per integration key**, not per clinic: a key used for 40 clinics shares one budget across all 40. | Window | Default limit | | -------- | --------------- | | 1 minute | 800 requests | | 1 hour | 12,000 requests | Both apply simultaneously: you can use up to 800 requests in a minute, but you cannot sustain that past the hourly cap (12,000 per hour is 200 per minute sustained). These are the defaults; the limits for your integration can differ, so read them from the [usage endpoint](#querying-current-usage) rather than hard-coding them. ## How requests are counted [Section titled “How requests are counted”](#how-requests-are-counted) * **Fixed UTC windows.** The minute counter resets at the start of each UTC minute and the hour counter at the start of each UTC hour. They are not sliding windows. * **Every authenticated request counts, including rejected ones.** A `401 Missing X-Clinic-Id header`, a `400`, a `429`, and a `500` all use quota; only the usage endpoint below is free. A loop that resends a failing request burns the budget and keeps you locked out. * **There is a second limit in front of the API.** It also limits each key, over windows of a few minutes, independently of the API’s own counters. Traffic sustained near the per-minute limit, or an integration with a raised API limit, can still be rejected there. Spread requests out instead of firing them all at the top of the minute. ## What 429 looks like [Section titled “What 429 looks like”](#what-429-looks-like) When the API rejects a request for exceeding a limit, the body is a JSON-encoded string: ```http HTTP/1.1 429 Too Many Requests Content-Type: application/json; charset=utf-8 "Request rate limit exceeded. Please wait before making further requests." ``` When the limit in front of the API rejects it, you get the same message as plain text: ```http HTTP/1.1 429 Too Many Requests Content-Type: text/plain Request rate limit exceeded. Please wait before making further requests. ``` Handle both: read the body as text, and parse it as JSON only if it parses. See [Errors](/api-reference/errors/). No `Retry-After` or rate-limit headers are sent. After a `429`, wait until the start of the next UTC minute before sending anything else; if the hourly budget is spent, wait until the next UTC hour. ## Querying current usage [Section titled “Querying current usage”](#querying-current-usage) You can ask the API where you stand at any time: ```http POST /pav2/open-api-rate-limits ``` Send the usual three headers, including `X-Clinic-Id`, and an empty JSON object. The call does not count against your budget. The response carries your integration’s actual limits and what is **left** in the current windows: ```json { "remainingRequestsThisHour": 11650, "remainingRequestsThisMinute": 790, "requestsPerHour": 12000, "requestsPerMinute": 800 } ``` Call it at the start of a batch job to size the run, and after a `429` to decide whether to wait for the next minute or the next hour. * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-rate-limits \ -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-rate-limits", 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() 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 { }); var resp = await http.PostAsync( "https://open-api.shepherd.vet/pav2/open-api-rate-limits", 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((object)[]), ]); $response = curl_exec($ch); curl_close($ch); echo $response; ``` * JavaScript ```js const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-rate-limits', { 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({}), }); if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`); console.log(await resp.json()); ``` ## Retries and backoff [Section titled “Retries and backoff”](#retries-and-backoff) | Outcome | Retry? | How | | ---------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `429` | Yes | Wait until the next UTC minute (next UTC hour if the hourly budget is spent), plus a little random jitter. | | `502`, `503` | Yes, for reads and updates | Exponential backoff with jitter: `min(60s, 1s * 2^(attempt-1))` plus up to 1 second, giving up after 4 attempts. A `503` maintenance response means back off for minutes. | | Timeout, no response, `504` | **No** | Make the request cheaper (shorter date window, smaller `rpp`, fewer embeds) or stop. | | `400`, `401`, `403`, `404`, `409`, `501` | **No** | Fix the request or configuration. | | `500` | **No** | On this API a `500` is almost always caused by the request (an empty or `null` body, a malformed id), so a retry fails the same way. Fix the request. | | Any failure on a create (`.../write`) | **No automatic retry** | Check whether the record was created before trying again. | Why timeouts are not retried: a request that timed out on your side may still be running on the server. Sending it again starts the same work again alongside the first copy, and an integration that retries timeouts in a loop turns one slow request into many. Add a circuit breaker on top: after a few consecutive timeouts or `5xx`/`429` responses, stop calling the API for about a minute, then allow a single trial request. ## Request shape matters more than request count [Section titled “Request shape matters more than request count”](#request-shape-matters-more-than-request-count) The rate limit caps how many requests you send, not how much work each one causes. A request for a whole clinic’s history, a deep embed over a large page, or a filter the API ignores (misspelled, or one the endpoint [does not apply](/api-reference/conventions/#fields-an-endpoint-does-not-apply)) can cost orders of magnitude more than a normal request while counting as one. * **Bound every list.** Use a date window of one calendar month or less, or an id filter, on clinical and financial data. * **Use moderate page sizes.** 100 to 500 records per page without embeds; 250 or less with embeds; 100 or less on physical exams and SOAP discharge instructions, whose records are large. See [Conventions](/api-reference/conventions/). * **Cache lookups.** Reference data (species, breeds, phone types) changes rarely; cache it instead of re-embedding on every request. * **Sync incrementally.** Poll on `dateUpdatedFrom` / `dateUpdatedTo` every 5 to 15 minutes, not every few seconds. * **Share the budget across workers.** Every process using a key draws on the same limit. Default to sequential requests; if you need concurrency, keep it small and fixed (4 at most) behind one shared limiter. * **Schedule batch jobs outside the nightly peak.** Run nightly syncs and backfills between 05:00 and 22:00 UTC, not around midnight UTC. See [When to schedule nightly syncs](#when-to-schedule-nightly-syncs). * **Resume, don’t restart.** If a backfill fails halfway through, resume from the last completed page or month. ## When to schedule nightly syncs [Section titled “When to schedule nightly syncs”](#when-to-schedule-nightly-syncs) The API is under its heaviest load of the day every night between about **00:00 and 04:30 UTC**, when many integrations run their nightly syncs at the same time. Responses are much slower in that window: a request that takes under a second the rest of the day can take tens of seconds, and larger requests (invoice items, for example) can take several minutes. | Time (UTC) | Load | Recommendation | | -------------- | --------------------------- | ----------------------------------- | | 00:00 to 04:30 | Nightly peak | Avoid scheduled syncs and backfills | | 05:00 to 22:00 | Normal | Run nightly and batch jobs here | | 09:00 to 12:00 | Quietest stretch of the day | Best slot for large pulls | * **Schedule in UTC.** For US clinics the peak falls in the evening (about 8:00 pm to 12:30 am Eastern, 5:00 pm to 9:30 pm Pacific, while daylight saving time is in effect), so a job set for “midnight local” can land in or near it. A UTC schedule also does not move when the clocks change. * **Add a little random offset.** Starting every clinic’s job exactly on the hour stacks requests on top of each other; spread start times across your window. * **Keep requests small even off-peak.** The window reduces contention; it does not make an unbounded request safe. The [request shape](#request-shape-matters-more-than-request-count) rules still apply. ### The 120-second gateway limit [Section titled “The 120-second gateway limit”](#the-120-second-gateway-limit) A gateway in front of the API cuts off any request that runs longer than about **120 seconds**. When that happens you receive an **HTML error page instead of JSON**, so a client that parses every response as JSON fails with a parse error rather than a clear timeout. Read error bodies as text first (see [Errors](/api-reference/errors/#5-an-html-error-page)). Treat a gateway cutoff like a timeout: do not send the same request again unchanged. A request that takes more than a minute during the peak is close to the limit and will fail on a busier night; move it out of the peak window and make it cheaper (a shorter date window, a smaller `rpp`, fewer embeds). ## Need a higher limit [Section titled “Need a higher limit”](#need-a-higher-limit) If your integration legitimately needs more headroom, talk to your Shepherd account manager. Larger limits are negotiated per integration rather than self-service. # Appointments > Scheduled visits that bind a patient, a provider, and a clinic on the calendar. An **appointment** is a scheduled visit: a slot on the clinic calendar that ties a patient to a provider for a particular reason (wellness exam, dental, recheck, surgery, etc.). Appointments are the typical entry point for day-of workflows, and they’re the parent record that most SOAP notes are written against. Appointment listings are heavily date-filtered in practice. Scope every list with a date window of one calendar month or less, or with an id filter; see [Conventions](/api-reference/conventions/) for paging and date-window rules. ## 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 appointment. | | `clientId` | string | The owning client (paying customer). | | `appointmentPatients` | array | The patients on the appointment. An appointment can cover more than one pet for the same client, so there is no single `patientId`. | | `providerId` | string | The veterinarian or staff member assigned. | | `startDate` | string | ISO 8601 UTC scheduled start. | | `endDate` | string | ISO 8601 UTC scheduled end. | | `appointmentTypeId` | string | Reference to the appointment-type taxonomy. A null type means the slot is blocked off rather than booked. | | `appointmentStatusId` | string | Reference to the current status. Defaults to upcoming. | | `appointmentCancellationReasonId` | string | Set when the appointment was cancelled. | | `visitReason` | string | Free-text reason for visit. Becomes the initial complaint on the SOAP. | | `schedulingMethod` | string | How the appointment was booked. | | `clinicId` | string | The owning clinic. | | `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` here, not `deleted`. | ## List / search [Section titled “List / search”](#list--search) POST `/pav2/open-api-appointments` Returns a paginated collection of appointments for the clinic. The most common pattern is a date-range query for “today” or “this week”; the example below shows the exact ISO 8601 timestamps to send. Appointments have two kinds of date filter, and they answer different questions: * `dateFrom` / `dateTo` match appointments whose **scheduled time** overlaps the range. Use these for “today’s schedule” or “next week’s bookings”. * `dateCreatedFrom` / `dateCreatedTo` (and `dateUpdatedFrom` / `dateUpdatedTo`) match when the appointment **record** was created or last changed, not when the visit happens. Use `dateUpdatedFrom` / `dateUpdatedTo` for incremental sync. Send both ends of whichever pair you use and keep the window to one calendar month or less. Keep `page * rpp` at or below 10,000; if a clinic’s volume risks exceeding that, use shorter windows. Deleted appointments are included unless you send `"isDeleted": false`. Embedding `appointmentPatients.patient` is expensive: keep `rpp` at 50 or less when you use it. ### Example: today’s appointments [Section titled “Example: today’s appointments”](#example-todays-appointments) For a clinic local to UTC, “today” (2026-05-22) is `2026-05-22T00:00:00Z` through `2026-05-23T00:00:00Z`. Adjust the bounds to your clinic’s local timezone as needed. * curl ```sh 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, "sort": "startDate|asc", "dateFrom": "2026-05-22T00:00:00Z", "dateTo": "2026-05-23T00:00:00Z", "embed": "appointmentPatients,client,provider" }' ``` * Python ```python import os from datetime import datetime, timedelta, timezone import requests start = datetime.now(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0) end = start + timedelta(days=1) 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, "sort": "startDate|asc", "dateFrom": start.strftime("%Y-%m-%dT%H:%M:%SZ"), "dateTo": end.strftime("%Y-%m-%dT%H:%M:%SZ"), "embed": "appointmentPatients,client,provider", }, timeout=30, ) resp.raise_for_status() for appt in resp.json()["item"]: print(appt["startDate"], appt["clientId"], appt.get("visitReason")) ``` * C# ```csharp using System.Net.Http; using System.Net.Http.Json; var start = DateTime.UtcNow.Date; var end = start.AddDays(1); 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-appointments", new { page = 1, rpp = 100, sort = "startDate|asc", dateFrom = start.ToString("yyyy-MM-ddTHH:mm:ssZ"), dateTo = end.ToString("yyyy-MM-ddTHH:mm:ssZ"), embed = "appointmentPatients,client,provider", }); response.EnsureSuccessStatusCode(); ``` * PHP ```php format('Y-m-d\TH:i:s\Z'); $end = (new DateTimeImmutable('tomorrow', new DateTimeZone('UTC')))->format('Y-m-d\TH:i:s\Z'); $ch = curl_init('https://open-api.shepherd.vet/pav2/open-api-appointments'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-Integration-Public-Key: ' . getenv('SHEPHERD_PUBLIC_KEY'), 'X-Integration-Private-Key: ' . getenv('SHEPHERD_PRIVATE_KEY'), 'X-Clinic-Id: ' . getenv('SHEPHERD_CLINIC_ID'), ], CURLOPT_POSTFIELDS => json_encode([ 'page' => 1, 'rpp' => 100, 'sort' => 'startDate|asc', 'dateFrom' => $start, 'dateTo' => $end, 'embed' => 'appointmentPatients,client,provider', ]), ]); $payload = json_decode(curl_exec($ch), true); curl_close($ch); ``` * JavaScript ```js const start = new Date(); start.setUTCHours(0, 0, 0, 0); const end = new Date(start); end.setUTCDate(end.getUTCDate() + 1); const response = 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, sort: 'startDate|asc', dateFrom: start.toISOString().replace(/\.\d{3}Z$/, 'Z'), dateTo: end.toISOString().replace(/\.\d{3}Z$/, 'Z'), embed: 'appointmentPatients,client,provider', }), }); 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": "b96d21ae-435f-4ef1-8cf7-3efbc3a3649a", "clientId": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "appointmentPatients": [ { "patientId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789" } ], "providerId": "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", "startDate": "2026-05-22T14:30:00Z", "endDate": "2026-05-22T15:00:00Z", "appointmentTypeId": "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", "appointmentStatusId": "9f8e7d6c-5b4a-3210-a9f8-fedcba098765", "appointmentCancellationReasonId": null, "visitReason": "Annual wellness exam", "clinicId": "9890662f-52db-4a41-a5c1-b2e300d400b4", "dateCreated": "2026-05-22T09:11:00Z", "dateUpdated": "2026-05-22T09:11:00Z", "isDeleted": false } ], "totalRecords": 27, "page": 1, "recordsPerPage": 100, "sort": "startDate|asc", "searchQuery": null, "embed": "appointmentPatients,client,provider", "links": [] } ``` ## Create [Section titled “Create”](#create) POST `/pav2/open-api-appointments/write` Creates a new appointment on the clinic calendar. **Required:** `startDate`, `endDate`, and `providerId`. Everything else is optional, but the optional fields interact: * `appointmentTypeId` controls the rest. Leave it null and the call blocks off time for the provider rather than booking a visit; `clientId` and `patientIds` can only be set when a type is present. * `patientIds` is an array and requires `clientId`. An appointment belongs to a client and can cover several of that client’s pets, so there is no single `patientId`. * `startDate` and `endDate` must fall on 5-minute boundaries (for example `14:30:00`, not `14:32:00`), the end must be after the start, and the appointment can span at most 24 hours. * `appointmentStatusId` defaults to upcoming when omitted. The pending status is rejected on create. * `visitReason` becomes the initial complaint on the resulting SOAP record. * `sendEmailNotification`, `sendSmsNotification`, and `sendFormEmailNotification` all default to false. Leave them false unless the clinic wants your integration to message its clients. Overlapping bookings are not rejected The API does not stop you from booking a provider into a slot that is already taken. Check the provider’s availability (`POST /pav2/open-api-provider-availabilities/timeslots`, with `providerIds` and a short date range) before you create the appointment. A slot inside a provider’s break or a clinic closure is rejected with `400`. The response is the created appointment, or a collection envelope if you sent `embed`. A create is not idempotent: every successful call books a new appointment, so never retry it automatically after a timeout or a `5xx`. Search for the appointment first. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-appointments/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 '{ "startDate": "2026-05-22T14:30:00Z", "endDate": "2026-05-22T15:00:00Z", "providerId": "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", "appointmentTypeId": "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", "clientId": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "patientIds": ["a1b2c3d4-e5f6-7890-abcd-ef0123456789"], "visitReason": "Annual wellness exam" }' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-appointments/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={ "startDate": "2026-05-22T14:30:00Z", "endDate": "2026-05-22T15:00:00Z", "providerId": "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", "appointmentTypeId": "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", "clientId": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "patientIds": ["a1b2c3d4-e5f6-7890-abcd-ef0123456789"], "visitReason": "Annual wellness exam", }, timeout=30, ) resp.raise_for_status() appointment = resp.json() ``` * 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-appointments/write", new { startDate = "2026-05-22T14:30:00Z", endDate = "2026-05-22T15:00:00Z", providerId = "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", appointmentTypeId = "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", clientId = "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", patientIds = new[] { "a1b2c3d4-e5f6-7890-abcd-ef0123456789" }, visitReason = "Annual wellness exam", }); 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([ 'startDate' => '2026-05-22T14:30:00Z', 'endDate' => '2026-05-22T15:00:00Z', 'providerId' => '5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219', 'appointmentTypeId' => '8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4', 'clientId' => 'e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6', 'patientIds' => ['a1b2c3d4-e5f6-7890-abcd-ef0123456789'], 'visitReason' => 'Annual wellness exam', ]), ]); $appointment = json_decode(curl_exec($ch), true); curl_close($ch); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-appointments/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({ startDate: '2026-05-22T14:30:00Z', endDate: '2026-05-22T15:00:00Z', providerId: '5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219', appointmentTypeId: '8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4', clientId: 'e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6', patientIds: ['a1b2c3d4-e5f6-7890-abcd-ef0123456789'], visitReason: 'Annual wellness exam', }), }); if (!response.ok) { throw new Error(`Shepherd API ${response.status}: ${await response.text()}`); } const appointment = await response.json(); ``` ## Update [Section titled “Update”](#update) PUT `/pav2/open-api-appointments/{id}/update` Updates an existing appointment. This is a `PUT`, so it is a **full replacement**: send the complete appointment representation, not just the fields you changed. Any editable field omitted from the body is cleared. See [Updating records](/api-reference/conventions/#updating-records-is-a-full-replacement) for the general rule and the read-merge-write pattern that keeps it safe. **Required on update:** `startDate`, `endDate`, and `providerId`. The remaining editable fields are `clientId`, `patientIds`, `appointmentTypeId`, `appointmentStatusId`, `visitReason`, `appointmentCancellationReasonId`, `cancellationNote`, `sendEmailNotification`, and `sendSmsNotification`. The same time rules as create apply: 5-minute boundaries, end after start, 24 hours at most. What omission does on this endpoint: * **`patientIds` omitted removes every patient from the appointment.** The record you read has no `patientIds` field; build it from `appointmentPatients[].patientId` and resend it even when the patients have not changed. * **`appointmentStatusId` omitted resets the status to upcoming.** An appointment that was checked in or completed goes back to upcoming. Resend the current status. * `appointmentTypeId`, `clientId`, `visitReason`, `cancellationNote`, and `appointmentCancellationReasonId` omitted become null. To change one thing, read the appointment with `{"ids": "", "rpp": 1}`, copy every editable field from it (mapping `patientIds` as above), apply your change, and send the whole body. Returns `204 No Content` with an empty body on success. Treat any `2xx` as success and don’t try to parse a body. A `404` means the id does not resolve within the clinic named by `X-Clinic-Id`. ## Sub-resources [Section titled “Sub-resources”](#sub-resources) Appointment-adjacent data lives on its own endpoints, each following the same list / write conventions as the parent resource. | Endpoint | Purpose | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `/pav2/open-api-appointment-notes/write` | Free-form notes attached to an appointment. Write only; there is no list endpoint for appointment notes. | | `/pav2/open-api-appointment-statuses` | Status taxonomy (scheduled, checked-in, in-room, completed, no-show). | | `/pav2/open-api-appointment-types` | Type taxonomy (wellness, dental, surgery, recheck, etc.). | | `/pav2/open-api-appointment-cancellation-reasons` | Cancellation reason taxonomy used when an appointment is cancelled. | ## See also [Section titled “See also”](#see-also) * [Conventions](/api-reference/conventions/): pagination, embed, sort, and date-window rules. * [Patients](/api-reference/resources/patients/): the pet the appointment is scheduled for. * [SOAP records](/api-reference/resources/soap-records/): clinical notes written against an appointment. * [Errors](/api-reference/errors/): HTTP status codes and the error body shapes. # Clients > Clients are the pet owners; the human paying customers attached to one or more patients. A **client** represents a pet owner: the human responsible for one or more patients (pets) at a clinic. Clients carry the billing relationship, the contact details, and the household-level preferences. Every patient in the Shepherd API is linked to at least one client, and most clinical and financial workflows start from a client lookup. Clients have several related sub-resources (phones, notes, info, discount) that are managed through their own endpoints rather than as deep writes on the client object itself. ## 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 client. | | `identifier` | string | Short human-facing identifier shown in the Shepherd UI. | | `firstName` / `middleName` / `lastName` | string | Name parts. | | `email` | string | Primary email address. | | `dateOfBirth` | string | Client’s date of birth. | | `clientPhones` | array | Phone numbers. Populated with `embed=clientPhones`. | | `clientInfo` | object | The contact block, including the postal address. Populated with `embed=clientInfo`; there are no address fields on the client itself. | | `clientCoOwner` | object | Co-owner, with their own phone list. Populated with `embed=clientCoOwner`. | | `clientStatusId` / `clientTypeId` / `genderId` | string | Lookup references. | | `clientDiscountId` | string | Discount program applied to this client. | | `authorizedAgents` | array | People authorised to act for the client. | | `isTaxExempt` | boolean | Whether the client is exempt from taxes. | | `clinicId` | string | The owning clinic. | | `legacyId` | string | Identifier carried over from a previous practice-management system. Read-only: create and update do not accept it. | | `dateCreated` | string | ISO 8601 UTC timestamp of creation. | | `dateUpdated` | string | ISO 8601 UTC timestamp of last update. | | `deleted` | boolean | Soft-delete flag; filter on this in queries. | ## List / search [Section titled “List / search”](#list--search) POST `/pav2/open-api-clients` Returns a paginated collection of clients for the clinic identified by `X-Clinic-Id`. Accepts the standard collection parameters: `page`, `rpp`, `sort`, `searchQuery`, `embed`, and the `dateCreatedFrom` / `dateCreatedTo` date-range pair. See [Conventions](/api-reference/conventions/) for the full parameter rules. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-clients \ -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": "lastName|asc", "searchQuery": "smith", "embed": "clientPhones" }' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-clients", 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": "lastName|asc", "searchQuery": "smith", "embed": "clientPhones", }, timeout=30, ) resp.raise_for_status() payload = resp.json() for client in payload["item"]: print(client["id"], client["firstName"], client["lastName"]) ``` * 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-clients", new { page = 1, rpp = 25, sort = "lastName|asc", searchQuery = "smith", embed = "clientPhones", }); response.EnsureSuccessStatusCode(); var payload = await response.Content.ReadFromJsonAsync(); ``` * 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' => 'lastName|asc', 'searchQuery' => 'smith', 'embed' => 'clientPhones', ]), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status >= 400) { throw new RuntimeException("Shepherd API $status: $body"); } $payload = json_decode($body, true); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-clients', { 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: 'lastName|asc', searchQuery: 'smith', embed: 'clientPhones', }), }); 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": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@example.com", "clientPhones": [ { "id": "7d7ea1ee-3329-4b06-9966-b2f800c16f53", "countryId": "158d44c8-d163-4c27-8e77-b2b300f2522f", "phoneNumber": "5555550123", "phoneTypeId": "534494bb-d287-eb09-e90b-8a2b4e5b9398", "isPrimary": true } ], "dateCreated": "2026-03-14T18:22:11Z", "dateUpdated": "2026-05-01T09:14:00Z", "deleted": false } ], "totalRecords": 184, "page": 1, "recordsPerPage": 25, "sort": "lastName|asc", "searchQuery": "smith", "embed": "clientPhones", "links": [] } ``` ## Create [Section titled “Create”](#create) POST `/pav2/open-api-clients/write` Creates a new client record for the clinic. **Required:** `firstName`, `lastName`, and `clientPhones`. The phone array is required by the model, so send it even if the client has no number on file; pass `[]` in that case. Each entry in `clientPhones` requires `countryId`, `phoneNumber`, and `phoneTypeId`, all resolved from [Lookups](/api-reference/resources/lookups/) (`open-api-countries` and `open-api-phone-types`). `isPrimary` and `phoneNumberName` are optional. A co-owner, the contact block, and authorized agents can be created in the same call via the `clientCoOwner`, `clientInfo`, and `authorizedAgents` objects. Notes and discounts are separate sub-resources. ### Example [Section titled “Example”](#example-1) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-clients/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 '{ "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@example.com", "clientPhones": [ { "countryId": "158d44c8-d163-4c27-8e77-b2b300f2522f", "phoneNumber": "5555550123", "phoneTypeId": "534494bb-d287-eb09-e90b-8a2b4e5b9398", "isPrimary": true } ] }' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-clients/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={ "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@example.com", "clientPhones": [ { "countryId": "158d44c8-d163-4c27-8e77-b2b300f2522f", "phoneNumber": "5555550123", "phoneTypeId": "534494bb-d287-eb09-e90b-8a2b4e5b9398", "isPrimary": True, } ], }, timeout=30, ) resp.raise_for_status() client = resp.json() ``` * 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-clients/write", new { firstName = "Jane", lastName = "Smith", email = "jane.smith@example.com", clientPhones = new[] { new { countryId = "158d44c8-d163-4c27-8e77-b2b300f2522f", phoneNumber = "5555550123", phoneTypeId = "534494bb-d287-eb09-e90b-8a2b4e5b9398", isPrimary = true, }, }, }); 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([ 'firstName' => 'Jane', 'lastName' => 'Smith', 'email' => 'jane.smith@example.com', 'clientPhones' => [[ 'countryId' => '158d44c8-d163-4c27-8e77-b2b300f2522f', 'phoneNumber' => '5555550123', 'phoneTypeId' => '534494bb-d287-eb09-e90b-8a2b4e5b9398', 'isPrimary' => true, ]], ]), ]); $body = curl_exec($ch); curl_close($ch); $client = json_decode($body, true); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-clients/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({ firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com', clientPhones: [ { countryId: '158d44c8-d163-4c27-8e77-b2b300f2522f', phoneNumber: '5555550123', phoneTypeId: '534494bb-d287-eb09-e90b-8a2b4e5b9398', isPrimary: true, }, ], }), }); if (!response.ok) { throw new Error(`Shepherd API ${response.status}: ${await response.text()}`); } const client = await response.json(); ``` ## Update [Section titled “Update”](#update) PUT `/pav2/open-api-clients/{id}/update` Updates an existing client. This is a `PUT`, so it is a **full replacement**: send the complete client representation, not just the fields you changed. Any editable field omitted from the body is cleared. See [Updating records](/api-reference/conventions/#updating-records-is-a-full-replacement) for the general rule. Required on every update: `firstName`, `lastName`, and `clientPhones`. Omitting any of them is rejected. What happens to each field you leave out of the body: | Kept when omitted | Cleared or reset when omitted | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientStatusId`, the `clientInfo` contact block, `authorizedAgents` (an edit list, below) | `middleName`, `email`, `dateOfBirth`, `clientTypeId`, `genderId`, `clientDiscountId`, `alerts`, `additionalText`, `referralSourceIds`, `clientCoOwner` (and its phones), `isTaxExempt` (resets to false, so the client is charged tax), and every notification preference | The home clinic, system identifiers, and deleted status cannot be changed here. `authorizedAgents` is an edit list rather than a replacement: each entry adds an agent (omit `id`), edits one in place (include `id`), or removes one (set `authorizedAgentIdForRemove` with a `removalNote`); agents you do not reference are left alone. Two update fields are spelled differently from the record The mass-communication preferences are `emailMassCommunicationNotification` and `smsMassCommunicationNotification` on the client you read, but the update model spells them `emailMassCommuncationNotification` and `smsMassCommuncationNotification` (no second “i”). Send the update spelling. The correctly spelled name is not recognized on update and is silently ignored, so the preference is cleared. Returns `200 OK` with the updated client. A `404` means the `{id}` does not resolve within the clinic named by `X-Clinic-Id`. ### Preserving co-owners and their phone numbers [Section titled “Preserving co-owners and their phone numbers”](#preserving-co-owners-and-their-phone-numbers) The most common data-loss report against this endpoint involves co-owners. `clientCoOwner` is a nested object that carries its own `clientCoOwnerPhones` array, so a body that includes the co-owner but not their phones removes those phone numbers. Fetch the full co-owner record before you merge. There are two ways to get it: **Embed it in the client read.** Ask for the co-owner and their phones by name, using the dot notation described in [Embedding related entities](/api-reference/conventions/#embedding-related-entities): ```json { "ids": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "embed": "clientCoOwner,clientCoOwner.clientCoOwnerPhones" } ``` **Or query the co-owner endpoint directly.** `POST /pav2/open-api-client-co-owners` returns co-owner records with their phone information attached. Co-owners are keyed by the owning client’s ID, so passing that ID in `ids` returns the co-owner for that client: ```json { "ids": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "embed": "client" } ``` Either way you end up with the complete co-owner object to resubmit. An empty phone list is a real instruction Sending `clientCoOwner` with `clientCoOwnerPhones: []`, or with the array missing entirely, deletes the co-owner’s existing phone numbers. If the co-owner has no phones and `smsDirectMessagingNotification` is set, the API also turns that flag back off, because there is no number left to message. ### Example: read, merge, write [Section titled “Example: read, merge, write”](#example-read-merge-write) The example changes one field, the email address, and carries every other editable field through from the current record. `clientInfo` and `clientStatusId` are left out because they are kept when omitted. * curl ```sh # 1. Read the current client, embedding the nested collections you will resend. curl -X POST https://open-api.shepherd.vet/pav2/open-api-clients \ -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 '{ "ids": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "rpp": 1, "embed": "clientPhones,clientCoOwner,clientCoOwner.clientCoOwnerPhones" }' > current-client.json # 2. Build merged-client.json from item[0]: every update field copied from the # record (renaming the two mass-communication flags), with your change applied. # 3. PUT the complete object back. curl -X PUT https://open-api.shepherd.vet/pav2/open-api-clients/e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6/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 @merged-client.json ``` * Python ```python import os import requests BASE = "https://open-api.shepherd.vet/pav2" 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"], } client_id = "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6" # Update fields with the same name on the record you read. SAME_NAME = ( "firstName", "middleName", "lastName", "email", "dateOfBirth", "clientTypeId", "genderId", "clientDiscountId", "isTaxExempt", "alerts", "additionalText", "referralSourceIds", "clientPhones", "clientCoOwner", "emailNotification", "smsNotification", "smsDirectMessagingNotification", "reminderEmailNotification", "reminderPostcardNotification", ) # Update field -> field on the record you read. RENAMED = { "emailMassCommuncationNotification": "emailMassCommunicationNotification", "smsMassCommuncationNotification": "smsMassCommunicationNotification", } # 1. Read, embedding every nested collection you intend to resend. read = requests.post( f"{BASE}/open-api-clients", headers=HEADERS, json={ "ids": client_id, "rpp": 1, "embed": "clientPhones,clientCoOwner,clientCoOwner.clientCoOwnerPhones", }, timeout=30, ) read.raise_for_status() current = read.json()["item"][0] # 2. Merge: copy every update field from the record, then apply the change. payload = {f: current[f] for f in SAME_NAME if f in current} payload.update({f: current[r] for f, r in RENAMED.items() if r in current}) payload["email"] = "jane.newaddress@example.com" # the actual change # 3. Write the complete object back. write = requests.put( f"{BASE}/open-api-clients/{client_id}/update", headers=HEADERS, json=payload, timeout=30, ) write.raise_for_status() updated = write.json() ``` * C# ```csharp using System.Net.Http.Json; using System.Text.Json.Nodes; const string Base = "https://open-api.shepherd.vet/pav2"; var clientId = "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6"; // Update fields with the same name on the record you read. string[] sameName = [ "firstName", "middleName", "lastName", "email", "dateOfBirth", "clientTypeId", "genderId", "clientDiscountId", "isTaxExempt", "alerts", "additionalText", "referralSourceIds", "clientPhones", "clientCoOwner", "emailNotification", "smsNotification", "smsDirectMessagingNotification", "reminderEmailNotification", "reminderPostcardNotification", ]; // Update field -> field on the record you read. var renamed = new Dictionary { ["emailMassCommuncationNotification"] = "emailMassCommunicationNotification", ["smsMassCommuncationNotification"] = "smsMassCommunicationNotification", }; using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) }; 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")); // 1. Read with embeds. var read = await http.PostAsJsonAsync($"{Base}/open-api-clients", new { ids = clientId, rpp = 1, embed = "clientPhones,clientCoOwner,clientCoOwner.clientCoOwnerPhones", }); read.EnsureSuccessStatusCode(); var current = (await read.Content.ReadFromJsonAsync())!["item"]![0]!.AsObject(); // 2. Merge: copy every update field from the record, then apply the change. var payload = new JsonObject(); foreach (var field in sameName) if (current.TryGetPropertyValue(field, out var value)) payload[field] = value?.DeepClone(); foreach (var (field, readName) in renamed) if (current.TryGetPropertyValue(readName, out var value)) payload[field] = value?.DeepClone(); payload["email"] = "jane.newaddress@example.com"; // the actual change // 3. Write it back. var write = await http.PutAsJsonAsync($"{Base}/open-api-clients/{clientId}/update", payload); write.EnsureSuccessStatusCode(); ``` * PHP ```php field on the record you read. $renamed = [ 'emailMassCommuncationNotification' => 'emailMassCommunicationNotification', 'smsMassCommuncationNotification' => 'smsMassCommunicationNotification', ]; // 1. Read with embeds. $ch = curl_init("$base/open-api-clients"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode([ 'ids' => $clientId, 'rpp' => 1, 'embed' => 'clientPhones,clientCoOwner,clientCoOwner.clientCoOwnerPhones', ]), ]); $current = json_decode(curl_exec($ch), true)['item'][0]; curl_close($ch); // 2. Merge: copy every update field from the record, then apply the change. $payload = []; foreach ($sameName as $field) { if (array_key_exists($field, $current)) { $payload[$field] = $current[$field]; } } foreach ($renamed as $field => $readName) { if (array_key_exists($readName, $current)) { $payload[$field] = $current[$readName]; } } $payload['email'] = 'jane.newaddress@example.com'; // the actual change // 3. Write it back. $ch = curl_init("$base/open-api-clients/$clientId/update"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode($payload), ]); $updated = json_decode(curl_exec($ch), true); curl_close($ch); ``` * JavaScript ```js const BASE = 'https://open-api.shepherd.vet/pav2'; const clientId = 'e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6'; const 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, }; // Update fields with the same name on the record you read. const SAME_NAME = [ 'firstName', 'middleName', 'lastName', 'email', 'dateOfBirth', 'clientTypeId', 'genderId', 'clientDiscountId', 'isTaxExempt', 'alerts', 'additionalText', 'referralSourceIds', 'clientPhones', 'clientCoOwner', 'emailNotification', 'smsNotification', 'smsDirectMessagingNotification', 'reminderEmailNotification', 'reminderPostcardNotification', ]; // Update field -> field on the record you read. const RENAMED = { emailMassCommuncationNotification: 'emailMassCommunicationNotification', smsMassCommuncationNotification: 'smsMassCommunicationNotification', }; // 1. Read, embedding every nested collection you intend to resend. const read = await fetch(`${BASE}/open-api-clients`, { method: 'POST', headers, body: JSON.stringify({ ids: clientId, rpp: 1, embed: 'clientPhones,clientCoOwner,clientCoOwner.clientCoOwnerPhones', }), signal: AbortSignal.timeout(30_000), }); if (!read.ok) throw new Error(`Shepherd API ${read.status}: ${await read.text()}`); const [current] = (await read.json()).item; // 2. Merge: copy every update field from the record, then apply the change. const payload = {}; for (const field of SAME_NAME) { if (field in current) payload[field] = current[field]; } for (const [field, readName] of Object.entries(RENAMED)) { if (readName in current) payload[field] = current[readName]; } payload.email = 'jane.newaddress@example.com'; // the actual change // 3. Write the complete object back. const write = await fetch(`${BASE}/open-api-clients/${clientId}/update`, { method: 'PUT', headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(30_000), }); if (!write.ok) throw new Error(`Shepherd API ${write.status}: ${await write.text()}`); const updated = await write.json(); ``` ## Sub-resources [Section titled “Sub-resources”](#sub-resources) Client-adjacent data lives on its own endpoints. Each follows the same list / write conventions as the parent resource. | Endpoint | Purpose | | --------------------------------- | ------------------------------------------------------------------------------------------ | | `/pav2/open-api-client-phones` | Phone numbers attached to a client (mobile, home, work). | | `/pav2/open-api-client-infos` | Extended profile fields and household metadata. | | `/pav2/open-api-client-notes` | Free-form notes recorded by clinic staff against the client. | | `/pav2/open-api-client-discounts` | Discount programs and percentage adjustments applied to the client’s invoices. | | `/pav2/open-api-client-co-owners` | Co-owners attached to a client, with their phone numbers. Keyed by the owning client’s ID. | ## See also [Section titled “See also”](#see-also) * [Conventions](/api-reference/conventions/): pagination, embed, sort, and date-range rules. * [Authentication](/api-reference/authentication/): the three required headers. * [Errors](/api-reference/errors/): HTTP status codes and the error body shapes. * [Patients](/api-reference/resources/patients/): the pets attached to each client. # Clinics > Clinics are the tenancy boundary; the endpoint that lists them is where you find the X-Clinic-Id UUID and the group each clinic belongs to. A **clinic** is the tenancy boundary of the Shepherd API. Almost every other call operates against exactly one clinic, named by the `X-Clinic-Id` header (see [Authentication](/api-reference/authentication/)). This endpoint lists the clinics your integration keys can reach, so it is usually the first call you make: it is where you discover the clinic UUID to put in `X-Clinic-Id`, and the `groupId` that ties a clinic into a [multi-site group](/guides/groups-and-multi-site/). This endpoint does not need `X-Clinic-Id` This clinic lookup is the only endpoint that accepts a call **without** `X-Clinic-Id`, precisely so you can find a clinic’s UUID before you have one to send. You still send your two integration keys. If you have no clinic id yet, leave the header out; don’t send an empty or placeholder value. On every other endpoint, `X-Clinic-Id` is a required **header**, not a body field; omitting it returns `401 Missing X-Clinic-Id header`. See [Errors](/api-reference/errors/) for the full list of failure states. ## 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 clinic. This is the value you send in `X-Clinic-Id`. | | `name` | string | Clinic display name. | | `groupId` | string | Identifier of the group the clinic belongs to, or null for a standalone clinic. See [Groups and multi-site](/guides/groups-and-multi-site/). | | `email` | string | Primary clinic email address. | | `phone` | string | Primary clinic phone number. | | `fax` | string | Clinic fax number. | | `smsNumber` | string | The clinic’s SMS number. | | `clinicAddress` | object | The clinic’s postal address. There are no flat address fields on the clinic itself. | | `clinicSetting` | object | Additional clinic configuration. | | `taxRate` | number | Tax rate applied to the clinic’s services. | | `info` | string | Free-text additional information. | | `dateCreated` | string | ISO 8601 UTC timestamp of creation. | | `dateUpdated` | string | ISO 8601 UTC timestamp of last update. | ## List / search [Section titled “List / search”](#list--search) POST `/pav2/open-api-clinics` Returns a paginated collection of the clinics your keys can access. Accepts the standard collection parameters: `page`, `rpp`, `sort`, `embed`, and a `searchQuery` that matches on clinic name and contact details. Because this endpoint is not clinic-scoped, you can call it with just your two integration keys. See [Conventions](/api-reference/conventions/) for the full parameter rules. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-clinics \ -H "Content-Type: application/json" \ -H "X-Integration-Public-Key: $SHEPHERD_PUBLIC_KEY" \ -H "X-Integration-Private-Key: $SHEPHERD_PRIVATE_KEY" \ -d '{ "page": 1, "rpp": 25, "sort": "name|asc" }' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-clinics", headers={ "Content-Type": "application/json", "X-Integration-Public-Key": os.environ["SHEPHERD_PUBLIC_KEY"], "X-Integration-Private-Key": os.environ["SHEPHERD_PRIVATE_KEY"], }, json={ "page": 1, "rpp": 25, "sort": "name|asc", }, timeout=30, ) resp.raise_for_status() payload = resp.json() for clinic in payload["item"]: print(clinic["id"], clinic["name"], clinic.get("groupId")) ``` * 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")); var response = await http.PostAsJsonAsync( "https://open-api.shepherd.vet/pav2/open-api-clinics", new { page = 1, rpp = 25, sort = "name|asc", }); response.EnsureSuccessStatusCode(); var payload = await response.Content.ReadFromJsonAsync(); ``` * 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'), ], CURLOPT_POSTFIELDS => json_encode([ 'page' => 1, 'rpp' => 25, 'sort' => 'name|asc', ]), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status >= 400) { throw new RuntimeException("Shepherd API $status: $body"); } $payload = json_decode($body, true); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-clinics', { 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, }, body: JSON.stringify({ page: 1, rpp: 25, sort: 'name|asc', }), }); 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": "9890662f-52db-4a41-a5c1-b2e300d400b4", "name": "Riverside Animal Hospital", "groupId": "3c7d1e9a-4b52-4f83-9d61-7a2b8c4e5f60", "email": "front-desk@riverside.example.com", "phone": "5555550100", "fax": "5555550101", "smsNumber": "5555550102", "clinicAddress": null, "clinicSetting": null, "taxRate": 8.25, "info": null, "dateCreated": "2025-11-02T16:40:00Z", "dateUpdated": "2026-04-18T12:05:00Z" } ], "totalRecords": 3, "page": 1, "recordsPerPage": 25, "sort": "name|asc", "links": [] } ``` ## Finding a clinic id and its group [Section titled “Finding a clinic id and its group”](#finding-a-clinic-id-and-its-group) Two fields on each clinic record drive the rest of your integration: * **`id`** is the value you put in `X-Clinic-Id` for every clinic-scoped call. * **`groupId`** tells you whether the clinic rolls up to a multi-location operator. If it is set, call [`POST /pav2/open-api-groups`](/guides/groups-and-multi-site/) with that clinic’s `id` in `X-Clinic-Id` (the group lookup requires it) to read the group’s `isMultiSite` flag and its data-sharing settings before you decide how to pull data across locations. ## See also [Section titled “See also”](#see-also) * [Authentication](/api-reference/authentication/): the three required headers and the per-clinic scope model. * [Groups and multi-site](/guides/groups-and-multi-site/): how `groupId`, sharing flags, and `clinicIds` change what you see. * [Errors](/api-reference/errors/): HTTP status codes and the common failure states, including the `X-Clinic-Id` header. * [Conventions](/api-reference/conventions/): pagination, embed, sort, and date-range rules. # Inventory > Products, locations, stock levels, vendors, and inventory movements. Inventory in the Shepherd API is split across several related endpoints rather than a single resource. The top-level model is: a clinic has one or more inventory locations (a treatment room cabinet, the main pharmacy, etc.); each location holds product records with on-hand quantities, reorder thresholds, and per-location settings; products themselves have vendor associations, units of measure, and a status flag indicating whether they are active. Every movement (receive, dispense, transfer, adjustment) is recorded in the transaction journal. Most integrations only need a subset: pharmacy partners read product settings and the journal; an ordering integration reads vendors, products, and locations; a clinic-wide dashboard reads location-product stock levels. ## Endpoints [Section titled “Endpoints”](#endpoints) | Endpoint | Purpose | | --------------------------------------------------------- | -------------------------------------------------------------- | | `POST /pav2/open-api-inventory-locations` | List inventory locations defined for a clinic. | | `POST /pav2/open-api-inventory-product-location-products` | List products with stock levels at a given location. | | `POST /pav2/open-api-inventory-product-settings` | Per-product inventory configuration (reorder points, etc.). | | `POST /pav2/open-api-inventory-vendors` | Vendors a clinic purchases inventory from. | | `POST /pav2/open-api-uom-units` | Units of measure (each, ml, tablet, gram, etc.). | | `POST /pav2/open-api-inventory-status` | Status values used to flag inventory items (active, archived). | | `POST /pav2/open-api-inventory/transaction-journals` | Audit trail of every inventory movement. | All of the above follow the standard request shape: POST, JSON body, the three auth headers, and the same pagination, sort, and date-filter conventions documented in [Conventions](/api-reference/conventions/). ## 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 that owns the location. | | `name` | string | Human-readable name (e.g. “Treatment Room”). | | `abrv` | string | Short code for the location. | | `description` | string | Free-text description. | | `isActive` | boolean | Whether the location is in use. | | `dateCreated` | ISO 8601 | Server-assigned creation timestamp (UTC). | | `dateUpdated` | ISO 8601 | Last server-side mutation (UTC). | | `isDeleted` | boolean | Soft-delete flag. Note this is `isDeleted`. | ## List inventory locations [Section titled “List inventory locations”](#list-inventory-locations) POST `/pav2/open-api-inventory-locations` Returns the inventory locations configured for the clinic identified by `X-Clinic-Id`. Most clinics have a handful of locations; this list changes rarely, so most integrations cache it client-side. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-inventory-locations \ -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}' ``` * Python ```python import os, requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-inventory-locations", 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}, timeout=30, ) resp.raise_for_status() for loc in resp.json()["item"]: print(loc["name"], loc["id"]) ``` * 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 }); var resp = await http.PostAsync( "https://open-api.shepherd.vet/pav2/open-api-inventory-locations", 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]), ]); $response = curl_exec($ch); curl_close($ch); echo $response; ``` * JavaScript ```js const resp = await fetch( 'https://open-api.shepherd.vet/pav2/open-api-inventory-locations', { 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 loc of page.item) console.log(loc.name, loc.id); ``` ### Response [Section titled “Response”](#response) ```json { "item": [ { "id": "5fc11c2e-18b4-4a91-a5c9-abc123456789", "clinicId": "9890662f-52db-4a41-a5c1-b2e300d400b4", "name": "Main Pharmacy", "abrv": "PHARM", "description": "Main dispensing pharmacy", "isActive": true, "dateCreated": "2025-08-14T09:02:11Z", "dateUpdated": "2025-12-01T11:18:44Z", "isDeleted": false } ], "totalRecords": 4, "page": 1, "recordsPerPage": 100, "sort": null, "searchQuery": null, "embed": null, "links": [] } ``` ## Other inventory endpoints [Section titled “Other inventory endpoints”](#other-inventory-endpoints) All of these follow the same request shape as the locations example above. Send a JSON body with `page`, `rpp`, and any filters you need, plus the three auth headers. ### Stock by location [Section titled “Stock by location”](#stock-by-location) `POST /pav2/open-api-inventory-product-location-products` returns per-location product records carrying on-hand quantity, reorder thresholds, and pricing overrides. Filter by location id to fetch the inventory snapshot for a single cabinet or fridge. ### Product settings [Section titled “Product settings”](#product-settings) `POST /pav2/open-api-inventory-product-settings` exposes the inventory-specific configuration attached to a catalog product: minimum/maximum thresholds, default vendor, default unit of measure, and reorder behaviour. ### Vendors [Section titled “Vendors”](#vendors) `POST /pav2/open-api-inventory-vendors` lists vendors the clinic purchases inventory from. Use this to populate vendor pickers in ordering integrations. ### Units of measure [Section titled “Units of measure”](#units-of-measure) `POST /pav2/open-api-uom-units` returns the units of measure available in the clinic (each, ml, tablet, gram, lb, etc.). Like the [lookups](/api-reference/resources/lookups/) endpoints, the response is small and stable; cache it client-side. ### Status values [Section titled “Status values”](#status-values) `POST /pav2/open-api-inventory-status` lists the status codes used to flag inventory records (active, archived, discontinued, etc.). Use this to render status filters or surface meaningful labels. It does not apply date filters; filter with `ids` or `searchQuery`. ### Transaction journal [Section titled “Transaction journal”](#transaction-journal) `POST /pav2/open-api-inventory/transaction-journals` is the append-only audit trail of every inventory movement: receive, dispense, transfer, count adjustment. Filter by transaction date with `dateFrom` and `dateTo` (one calendar month or less per request) to pull the day’s activity for reconciliation. Use `dateFrom` / `dateTo` here, not the standard date pairs The journal accepts `dateCreatedFrom` / `dateCreatedTo`, `dateUpdatedFrom` / `dateUpdatedTo`, `ids`, `excludeIds`, and `productIds` without an error but does not apply them, so a request bounded only by one of those returns the whole journal. To follow one product, filter by its `inventoryProductSettingIds`. See [Fields an endpoint does not apply](/api-reference/conventions/#fields-an-endpoint-does-not-apply). ## See also [Section titled “See also”](#see-also) * [Conventions](/api-reference/conventions/) for pagination, embedding, sorting, and date filters. * [Products](/api-reference/resources/products/) for the underlying catalog that inventory tracks stock against. * [Errors](/api-reference/errors/) for the error body shapes. # Invoices > Billing artifacts tied to a client and clinic, made up of line items. An invoice is the billing artifact for a visit or any set of line items a clinic charges to a client. Each invoice belongs to exactly one client and one clinic, and groups one or more invoice items: the individual products, services, or fees that make up the charge. To build a full picture of a visit you usually fetch the invoice, then embed or list the invoice items that hang off it. Invoices link out to several other resources: the client being billed, the patient receiving care, the products on each line, and the providers who delivered the service. Use [embedding](/api-reference/conventions/#embedding-related-entities) to pull related records back in a single round trip. ## 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. | | `invoiceNumber` | integer | The number assigned to the invoice. | | `clinicId` | string | Clinic that owns the invoice. | | `clientId` | string | Client (account holder) being billed. | | `statusId` | string | Lifecycle state reference. `invoiceStatus` expands it. | | `invoiceItems` | array | The line items on this invoice. | | `subtotal` | number | Sum of line-item amounts before tax and discount. | | `discount` | number | Discount amount applied. | | `tax` | number | Tax amount applied. | | `total` | number | Final invoice total after all calculations. | | `paid` | number | Total amount paid towards the invoice. | | `balance` | number | Remaining unpaid amount. | | `isPaid` | boolean | Whether the invoice is fully paid. | | `isReturn` | boolean | Whether this invoice is a product return. | | `isTaxExempt` | boolean | Whether the invoice is tax exempt. | | `dateIssued` | string | ISO 8601 UTC issue date. | | `dateCheckedOut` | string | ISO 8601 UTC checkout date. | | `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`. | Invoice items are read through their own endpoint and carry a much wider shape than the invoice itself: alongside `id`, `invoiceId`, `productId`, `name`, `price`, `productQuantity`, `discount`, `taxRate`, `subtotal`, and `total`, they include lot and inventory tracking (`lotNumber`, `lotExpirationDate`, `inventoryLotId`), controlled-substance and medication detail, return and refund linkage, and production attribution. Note the quantity field is `productQuantity`, not `quantity`, and the unit price is `price`, not `unitPrice`. See the [live Swagger UI](https://app.shepherd.vet/swagger/) for the full list. ## List / search [Section titled “List / search”](#list--search) POST `/pav2/open-api-invoices` Standard collection envelope, paginated and filterable. See [Conventions](/api-reference/conventions/) for the full pagination, sort, and date-range model. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-invoices \ -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, "dateCreatedFrom": "2026-04-01T00:00:00Z", "dateCreatedTo": "2026-04-30T23:59:59Z", "sort": "dateCreated|desc" }' ``` * Python ```python import os, requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-invoices", 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, "dateCreatedFrom": "2026-04-01T00:00:00Z", "dateCreatedTo": "2026-04-30T23:59:59Z", "sort": "dateCreated|desc", }, timeout=30, ) resp.raise_for_status() page = resp.json() print(f"Returned {len(page['item'])} of {page['totalRecords']} invoices") ``` * 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 = 25, dateCreatedFrom = "2026-04-01T00:00:00Z", dateCreatedTo = "2026-04-30T23:59:59Z", sort = "dateCreated|desc", }); var resp = await http.PostAsync( "https://open-api.shepherd.vet/pav2/open-api-invoices", body); resp.EnsureSuccessStatusCode(); var json = await resp.Content.ReadAsStringAsync(); Console.WriteLine(json); ``` * 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, 'dateCreatedFrom' => '2026-04-01T00:00:00Z', 'dateCreatedTo' => '2026-04-30T23:59:59Z', 'sort' => 'dateCreated|desc', ]), ]); $response = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch); echo "HTTP $status\n$response\n"; ``` * JavaScript ```js const resp = await fetch('https://open-api.shepherd.vet/pav2/open-api-invoices', { 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, dateCreatedFrom: '2026-04-01T00:00:00Z', dateCreatedTo: '2026-04-30T23:59:59Z', sort: 'dateCreated|desc', }), }); if (!resp.ok) throw new Error(`Shepherd ${resp.status}: ${await resp.text()}`); const page = await resp.json(); console.log(`Returned ${page.item.length} of ${page.totalRecords} invoices`); ``` ### Response [Section titled “Response”](#response) ```json { "item": [ { "id": "8b1f2c3d-4e5f-6789-abcd-ef0123456789", "invoiceNumber": 10428, "clinicId": "9890662f-52db-4a41-a5c1-b2e300d400b4", "clientId": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "statusId": "9f8e7d6c-5b4a-3210-a9f8-fedcba098765", "invoiceStatus": null, "invoiceItems": [], "subtotal": 124.50, "discount": 0.00, "tax": 9.96, "total": 134.46, "paid": 0.00, "balance": 134.46, "isPaid": false, "isReturn": false, "isTaxExempt": false, "dateIssued": "2026-04-28T15:42:11Z", "dateCheckedOut": null, "dateCreated": "2026-04-28T15:42:11Z", "dateUpdated": "2026-04-28T15:42:11Z", "isDeleted": false } ], "totalRecords": 1842, "page": 1, "recordsPerPage": 25, "sort": "dateCreated|desc", "searchQuery": null, "embed": null, "links": [] } ``` ## Writing invoices [Section titled “Writing invoices”](#writing-invoices) The public API surface for invoices is **read only**. There is no create, update, or delete endpoint for invoices or for invoice items; billing is driven from within the Shepherd application, and integrations consume the resulting records. If your integration needs to originate charges, the supported path is to record treatments against a SOAP plan, which the clinic then invoices in Shepherd. See [Treatments](/api-reference/resources/treatments/). If that does not cover your use case, raise it with your Shepherd contact rather than looking for an undocumented write endpoint. Invoice line items are read through their own collection endpoint, `POST /pav2/open-api-invoice-items`, using the same collection conventions as everything else. ## 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. * [Authentication](/api-reference/authentication/) for the three required headers. * [Products](/api-reference/resources/products/) for the catalog that invoice items reference. # Lookups > Enumerated values integrations need to map: breeds, species, units, statuses, and more. Most resources in the Shepherd API carry foreign keys to small enumerated sets: species, breeds, sexes, statuses, phone types, weight and temperature units, and so on. Writing a patient or a client means resolving those IDs first. Each set has **its own endpoint**. There is no single lookup endpoint and no `type` parameter; you call the endpoint for the set you want. Every one is a `POST` that takes a JSON filter body and returns the standard collection envelope, so `page`, `rpp`, `sort`, `searchQuery`, `ids`, and the date-range filters all behave exactly as they do elsewhere. See [Conventions](/api-reference/conventions/). Lookup IDs are per-environment Sandbox and production have entirely separate ID sets for nearly every lookup. An ID that works against `demo-open-api.shepherd.vet` will not validate against `open-api.shepherd.vet`, and vice versa. Resolve lookups against the environment you are calling; do not hard-code IDs harvested from the other one. This is the most common cause of a rejected write. ## Available lookups [Section titled “Available lookups”](#available-lookups) | Endpoint | Returns | | --------------------------------------------- | -------------------------------------------------------------- | | `/pav2/open-api-species` | Species (canine, feline, and so on). | | `/pav2/open-api-breeds` | Breeds. Each belongs to a species. | | `/pav2/open-api-patient-sexes` | Patient sex values (male, female, neutered, spayed, unknown). | | `/pav2/open-api-patient-statuses` | Patient status values (active, inactive, deceased, and so on). | | `/pav2/open-api-patient-cpr-statuses` | Patient CPR / resuscitation-status values. | | `/pav2/open-api-appointment-statuses` | Appointment status values. | | `/pav2/open-api-payment-statuses` | Payment status values. | | `/pav2/open-api-inventory-status` | Inventory status values. | | `/pav2/open-api-task-entry-priority-statuses` | Task priority values. | | `/pav2/open-api-phone-types` | Phone types (mobile, home, work). | | `/pav2/open-api-countries` | Countries, used by `countryId` on phone numbers. | | `/pav2/open-api-weight-units` | Weight units, used by `weightUnitId` on weight entries. | | `/pav2/open-api-temperature-units` | Temperature units. | | `/pav2/open-api-time-units` | Time units. | | `/pav2/open-api-uom-units` | Units of measure, used by inventory and products. | | `/pav2/open-api-client-discounts` | Client discount programs. | | `/pav2/open-api-referral-source` | Referral sources. | | `/pav2/open-api-client-referral-source` | Referral sources linked to a client. | New sets are added periodically; the [live Swagger UI](https://app.shepherd.vet/swagger/) has the current list and the exact response schema for each. ## Scoping and legacy entries [Section titled “Scoping and legacy entries”](#scoping-and-legacy-entries) Most lookups are global to an environment: every clinic sees the same list, and the filter body accepts only the standard collection parameters. Two are different, because clinics curate their own lists and retire old entries: | Endpoint | Extra filters | | ------------------------ | --------------------------------------------------------------------------------- | | `/pav2/open-api-breeds` | `getBreedsByClinicId`, `getBreedsByGroupId`, `speciesId`, `isLegacy`, `isDeleted` | | `/pav2/open-api-species` | `getSpeciesByClinicId`, `getSpeciesByGroupId`, `isLegacy`, `isDeleted` | When you are populating a picker for a specific clinic, ask for that clinic’s own non-legacy list: ```json { "getBreedsByClinicId": true, "isLegacy": false, "rpp": 1000 } ``` Leaving `getBreedsByClinicId` unset returns **all** breeds in the environment, including entries the clinic does not use and retired legacy rows: hundreds of thousands of rows in production, so never page through the unfiltered list. Writing a patient with one of those is a common source of rejected creates. Patient sexes and statuses have no clinic scoping and no legacy flag, so no extra filtering is needed there. ## Species and breed are one relationship [Section titled “Species and breed are one relationship”](#species-and-breed-are-one-relationship) There is no `speciesId` on a patient. Species is a property of the breed, so choosing a breed determines the species. To offer a species-then-breed picker, read `/pav2/open-api-species`, then filter breeds by the chosen `speciesId`: ```json { "speciesId": "9c1f...", "getBreedsByClinicId": true, "isLegacy": false, "rpp": 1000 } ``` ## Example: fetch a clinic’s breeds [Section titled “Example: fetch a clinic’s breeds”](#example-fetch-a-clinics-breeds) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-breeds \ -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 '{"getBreedsByClinicId":true,"isLegacy":false,"page":1,"rpp":1000}' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-breeds", 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={"getBreedsByClinicId": True, "isLegacy": False, "page": 1, "rpp": 1000}, timeout=30, ) resp.raise_for_status() breeds = {row["name"]: row["id"] for row in resp.json()["item"]} ``` * 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-breeds", new { getBreedsByClinicId = true, isLegacy = false, page = 1, rpp = 1000 }); 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([ 'getBreedsByClinicId' => true, 'isLegacy' => false, 'page' => 1, 'rpp' => 1000, ]), ]); $breeds = json_decode(curl_exec($ch), true)['item']; curl_close($ch); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-breeds', { 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({ getBreedsByClinicId: true, isLegacy: false, page: 1, rpp: 1000, }), }); if (!response.ok) { throw new Error(`Shepherd API ${response.status}: ${await response.text()}`); } const { item: breeds } = await response.json(); ``` ### Response [Section titled “Response”](#response) Lookup responses use the standard collection envelope. The fields on each row vary by set; every set carries at least `id` and `name`. ```json { "item": [ { "id": "6178ed48-7c31-282b-b87d-eccc6151437e", "name": "Labrador Retriever", "isLegacy": false }, { "id": "1a2b3c4d-5e6f-789a-bcde-0123456789ab", "name": "Border Collie", "isLegacy": false } ], "totalRecords": 412, "page": 1, "recordsPerPage": 1000, "sort": null, "searchQuery": null, "embed": null, "links": [] } ``` ## Caching guidance [Section titled “Caching guidance”](#caching-guidance) Lookup data changes rarely and is read on almost every write you make against other resources. A few patterns that work well: * Cache by `(environment, clinicId, lookup)` and refresh once a day, or on a manual “reload” hook in your admin UI. The environment belongs in the key: sandbox and production IDs are not interchangeable. * Treat the `id` values as opaque strings; do not parse them or infer meaning from their shape. * Page with a large `rpp` (the maximum is 1000) rather than many small pages. Most sets fit in one page; breeds may not. * If a foreign key in another resource doesn’t resolve against your cached set, refresh the cache before treating it as an error. A clinic may have added a breed since you last synced. ## See also [Section titled “See also”](#see-also) * [Conventions](/api-reference/conventions/) for the collection envelope and pagination. * [Patients](/api-reference/resources/patients/) for the write endpoints that consume `breedId`, `sexId`, and `statusId`. * [Clients](/api-reference/resources/clients/) for the ones that consume `countryId` and `phoneTypeId`. * [Errors](/api-reference/errors/) for the error body shapes. # Patients > Patients are the pets; dogs, cats, exotics, and everything in between, each attached to one or more clients. A **patient** is the pet: a dog, cat, rabbit, parrot, or any other animal the clinic treats. Every patient belongs to one or more clients (the pet owners), and patients are the anchor for clinical workflows: appointments, SOAP records, vitals, prescriptions, imaging, and attached files all hang off a patient ID. For file uploads, the API uses a three-step flow with an S3 presigned URL so binaries never transit the Shepherd application servers; see the [file uploads](#file-uploads) section below. ## 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 patient. | | `name` | string | Patient name (e.g. “Biscuit”). | | `identifier` | string | Short human-facing identifier shown in the Shepherd UI. | | `breedId` | string | Reference to a breed from the breeds lookup. | | `sexId` | string | Reference to a patient sex from the sexes lookup. | | `statusId` | string | Reference to a patient status from the statuses lookup. | | `color` | string | Colour or markings, free text (e.g. “Brown”). | | `dateOfBirth` | string | Date of birth. Stored as a date; any time component is ignored. | | `microchipNumber` | string | Microchip number, free text. | | `rabiesTag` | string | Rabies tag number, free text. | | `alerts` | string | Important handling notes surfaced in the chart. | | `additionalText` | string | Free-text additional information. | | `clients` | array | Owning clients. Populated with `embed=clients`. | | `breed` / `patientSex` / `patientStatus` | object | Expanded lookup records. `null` unless embedded. | | `dateDeceased` | string | Date of death, or `null`. | | `legacyId` | string | Identifier carried over from a previous practice-management system. Read-only: create and update do not accept it. | | `dateCreated` | string | ISO 8601 UTC timestamp of creation. | | `dateUpdated` | string | ISO 8601 UTC timestamp of last update. | | `deleted` | boolean | Soft-delete flag. | There is no `species` field on a patient Species is a property of the **breed**, not of the patient. Choosing a `breedId` determines the species, which is why the write models take no `speciesId`. To offer a species picker in your UI, read the species lookup, then filter breeds by `speciesId` on the breeds endpoint. See [Lookups](/api-reference/resources/lookups/). Weight is not a scalar field on the patient either. It is a separate series of weight entries; one can be created alongside the patient (see [Create](#create)) and further entries are recorded through the patient-weight endpoint. ## List / search [Section titled “List / search”](#list--search) POST `/pav2/open-api-patients` Returns a paginated collection of patients for the clinic. Use `searchQuery` for free-text matching against name, microchip number, and rabies tag, `embed` to pull related data inline (for example `embed: "clients,clients.clientPhones"`), and the standard `page`, `rpp`, `sort`, and `dateCreatedFrom` / `dateCreatedTo` parameters from [Conventions](/api-reference/conventions/). Narrow by owner with `clientIds`, by status with `patientStatusIds`, or drop deceased patients with `excludeDeceased`. Bound every list: a `searchQuery`, an id filter such as `clientIds`, or a `dateCreated` / `dateUpdated` window of one calendar month or less. Deleted patients are included unless you send `"isDeleted": false`. The example below searches by name. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients \ -H "Content-Type: application/json" \ -H "X-Integration-Public-Key: $SHEPHERD_PUBLIC_KEY" \ -H "X-Integration-Private-Key: $SHEPHERD_PRIVATE_KEY" \ -H "X-Clinic-Id: $SHEPHERD_CLINIC_ID" \ -d '{ "page": 1, "rpp": 50, "sort": "name|asc", "searchQuery": "biscuit", "embed": "clients" }' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-patients", headers={ "Content-Type": "application/json", "X-Integration-Public-Key": os.environ["SHEPHERD_PUBLIC_KEY"], "X-Integration-Private-Key": os.environ["SHEPHERD_PRIVATE_KEY"], "X-Clinic-Id": os.environ["SHEPHERD_CLINIC_ID"], }, json={"page": 1, "rpp": 50, "sort": "name|asc", "searchQuery": "biscuit", "embed": "clients"}, timeout=30, ) resp.raise_for_status() for patient in resp.json()["item"]: print(patient["id"], patient["name"], patient["breedId"]) ``` * 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-patients", new { page = 1, rpp = 50, sort = "name|asc", searchQuery = "biscuit", embed = "clients" }); 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' => 50, 'sort' => 'name|asc', 'searchQuery' => 'biscuit', 'embed' => 'clients', ]), ]); $body = curl_exec($ch); curl_close($ch); $payload = json_decode($body, true); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-patients', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Integration-Public-Key': process.env.SHEPHERD_PUBLIC_KEY, 'X-Integration-Private-Key': process.env.SHEPHERD_PRIVATE_KEY, 'X-Clinic-Id': process.env.SHEPHERD_CLINIC_ID, }, body: JSON.stringify({ page: 1, rpp: 50, sort: 'name|asc', searchQuery: 'biscuit', embed: 'clients' }), }); 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": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "name": "Biscuit", "identifier": "K2X9MV1", "breedId": "1a2b3c4d-5e6f-789a-bcde-0123456789ab", "sexId": "6a5b4c3d-2e1f-0a9b-8765-4321fedcba09", "statusId": "9f8e7d6c-5b4a-3210-a9f8-fedcba098765", "color": "Brown", "dateOfBirth": "2019-04-12T00:00:00Z", "microchipNumber": "985141001234567", "rabiesTag": "R123456", "dateDeceased": null, "clients": [], "breed": null, "patientSex": null, "patientStatus": null, "dateCreated": "2026-03-14T18:22:11Z", "dateUpdated": "2026-05-10T14:00:00Z", "deleted": false } ], "totalRecords": 421, "page": 1, "recordsPerPage": 50, "sort": "name|asc", "searchQuery": null, "embed": "clients", "links": [] } ``` `breed`, `patientSex`, and `patientStatus` are the expanded lookup records. They stay `null` until you name them in `embed`; the `*Id` fields are always present. ## Create [Section titled “Create”](#create) POST `/pav2/open-api-patients/write` Creates a new patient under an existing client. Every reference field is a lookup ID, not a name. There is no free-text `species`, `breed`, or `sex` on this endpoint; resolve each one against its lookup first (see [Resolving the lookup IDs](#resolving-the-lookup-ids) below). **Required on create:** | Field | Notes | | ------------- | --------------------------------------------------------------------------- | | `name` | The patient’s name. | | `clientId` | The owning client. Must already exist. | | `breedId` | From the breeds lookup. Determines the species. | | `sexId` | From the patient-sexes lookup. | | `statusId` | From the patient-statuses lookup. | | `dateOfBirth` | Must not be in the future. Stored as a date; any time component is ignored. | Everything else is optional: `color`, `alerts`, `additionalText`, `microchipNumber`, `rabiesTag`, `discountId`, `patientCprstatusId`, `patientCPRStatusNote`, `preferredProviderIds`, `referralSourceIds`, and `patientWeight`. `color` is optional on create, required on update Leave `color` out of a create call and the patient is stored with a color of `N/A`. The [update](#update) endpoint does require it, so a create-then-update round trip needs a real value. The Shepherd UI asks for color at intake, which is why clinic staff will describe it as required. Unless the Shepherd account is configured as a group account, you do not need to supply a home clinic; the clinic in `X-Clinic-Id` is used. Default provider (`preferredProviderIds`) and every other field not listed above are optional. ### Resolving the lookup IDs [Section titled “Resolving the lookup IDs”](#resolving-the-lookup-ids) `breedId`, `sexId`, and `statusId` must come from the lookups on the clinic’s own environment. **Lookup IDs differ between sandbox and production**, and between clinics for breeds, so IDs harvested from one environment will not validate in another. This is the most common cause of a rejected create. | Field | Source | Scoping | | ---------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `breedId` | `POST /pav2/open-api-breeds` | Clinic-scoped. Pass `getBreedsByClinicId: true` for the clinic’s own list, and `isLegacy: false` to skip retired entries. Filter by `speciesId` to offer a species-then-breed picker. | | `sexId` | `POST /pav2/open-api-patient-sexes` | Not clinic-scoped, and there is no legacy flag. The list is the same for every clinic in an environment. | | `statusId` | `POST /pav2/open-api-patient-statuses` | Not clinic-scoped, and there is no legacy flag. | Cache these; they change rarely. See [Lookups](/api-reference/resources/lookups/) for the caching guidance. ### Recording an initial weight [Section titled “Recording an initial weight”](#recording-an-initial-weight) Weight is not a field on the patient. To capture an intake weight at the same time as the record, include the nested `patientWeight` object; `weight` and `weightUnitId` are both required within it, and `date` and `note` are optional. ```json { "patientWeight": { "weight": 5.0, "weightUnitId": "a28f2c7e-5f45-4a32-ae3f-4e87c49a47a3", "date": "2026-08-20T10:12:45Z", "note": "Intake weight" } } ``` A weight of zero or less is rejected, as is a value that fails validation for the unit you named. Include `patientWeight` if a create is failing There is a known defect in how an omitted `patientWeight` is handled on create. If you are getting a rejection you cannot otherwise explain, sending a valid `patientWeight` block is a reliable workaround, and it creates the initial weight record at the same time. This note will be removed once the fix ships. ### Example [Section titled “Example”](#example-1) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients/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": "Biscuit", "clientId": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "breedId": "f2c19d83-9f87-4f6f-a290-d08e59d7d29e", "sexId": "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", "statusId": "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", "dateOfBirth": "2019-04-12T00:00:00Z", "color": "Chocolate", "patientWeight": { "weight": 5.0, "weightUnitId": "a28f2c7e-5f45-4a32-ae3f-4e87c49a47a3" } }' ``` * Python ```python import os import requests resp = requests.post( "https://open-api.shepherd.vet/pav2/open-api-patients/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={ "name": "Biscuit", "clientId": "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", "breedId": "f2c19d83-9f87-4f6f-a290-d08e59d7d29e", "sexId": "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", "statusId": "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", "dateOfBirth": "2019-04-12T00:00:00Z", "color": "Chocolate", "patientWeight": { "weight": 5.0, "weightUnitId": "a28f2c7e-5f45-4a32-ae3f-4e87c49a47a3", }, }, timeout=30, ) resp.raise_for_status() patient = resp.json() ``` * 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-patients/write", new { name = "Biscuit", clientId = "e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6", breedId = "f2c19d83-9f87-4f6f-a290-d08e59d7d29e", sexId = "5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219", statusId = "8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4", dateOfBirth = "2019-04-12T00:00:00Z", color = "Chocolate", patientWeight = new { weight = 5.0, weightUnitId = "a28f2c7e-5f45-4a32-ae3f-4e87c49a47a3", }, }); 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([ 'name' => 'Biscuit', 'clientId' => 'e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6', 'breedId' => 'f2c19d83-9f87-4f6f-a290-d08e59d7d29e', 'sexId' => '5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219', 'statusId' => '8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4', 'dateOfBirth' => '2019-04-12T00:00:00Z', 'color' => 'Chocolate', 'patientWeight' => [ 'weight' => 5.0, 'weightUnitId' => 'a28f2c7e-5f45-4a32-ae3f-4e87c49a47a3', ], ]), ]); $body = curl_exec($ch); curl_close($ch); $patient = json_decode($body, true); ``` * JavaScript ```js const response = await fetch('https://open-api.shepherd.vet/pav2/open-api-patients/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({ name: 'Biscuit', clientId: 'e45a6e12-3a1c-4e7d-9fd2-3473a4d8a7a6', breedId: 'f2c19d83-9f87-4f6f-a290-d08e59d7d29e', sexId: '5a8d0cfc-c7c4-44a0-bdab-44f4e5f6b219', statusId: '8fc9c6d1-a829-4b93-a5ea-1c83db96a1b4', dateOfBirth: '2019-04-12T00:00:00Z', color: 'Chocolate', patientWeight: { weight: 5.0, weightUnitId: 'a28f2c7e-5f45-4a32-ae3f-4e87c49a47a3', }, }), }); if (!response.ok) { throw new Error(`Shepherd API ${response.status}: ${await response.text()}`); } const patient = await response.json(); ``` ## Update [Section titled “Update”](#update) PUT `/pav2/open-api-patients/{id}/update` Updates an existing patient. This is a `PUT`, so it is a **full replacement**: send the complete patient representation, not just the fields you changed. Any editable field omitted from the body is cleared. See [Updating records](/api-reference/conventions/#updating-records-is-a-full-replacement) for the general rule and the read-merge-write pattern. **Required on update:** `name`, `breedId`, `sexId`, `statusId`, `dateOfBirth`, and `color`. Note that `color` is required here even though it is optional on create. `dateOfBirth` cannot be in the future. No field is kept when omitted. Leave out `alerts`, `additionalText`, `microchipNumber`, `rabiesTag`, `patientCprstatusId`, or `patientCPRStatusNote` and it is cleared; leave out `preferredProviderIds` or `referralSourceIds` and the patient’s preferred providers or referral sources are removed. Two of those are named differently on the patient you read, so map them when you merge: | Update field | Take it from the record you read | | ---------------------- | ---------------------------------------------------------------------------- | | `preferredProviderIds` | `patientPreferredProviders[].providerId` (embed `patientPreferredProviders`) | | `referralSourceIds` | `patientReferralSources[].referralSourceId` (embed `patientReferralSources`) | Two differences from create are worth calling out: * **`clientId` is not accepted.** The patient’s client association cannot be changed through this endpoint, along with the home clinic, system identifiers, and deleted status. * **`patientWeight` is not accepted.** Weight entries are their own series; record new ones through the patient-weight endpoint rather than through the patient update. Returns `200 OK` with the updated patient, not `201`. A `404` means the `{id}` does not resolve within the clinic named by `X-Clinic-Id`. ### Example: read, merge, write [Section titled “Example: read, merge, write”](#example-read-merge-write) The example changes one field, `alerts`, and carries every other editable field through from the current record. * curl ```sh # 1. Read the current patient, embedding the links you will resend. curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients \ -H "Content-Type: application/json" \ -H "X-Integration-Public-Key: $SHEPHERD_PUBLIC_KEY" \ -H "X-Integration-Private-Key: $SHEPHERD_PRIVATE_KEY" \ -H "X-Clinic-Id: $SHEPHERD_CLINIC_ID" \ -d '{ "ids": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "rpp": 1, "embed": "patientPreferredProviders,patientReferralSources" }' > current-patient.json # 2. Build merged-patient.json from item[0]: every update field copied from # the record (mapping the two id lists), with your change applied. # 3. PUT the complete object back. curl -X PUT https://open-api.shepherd.vet/pav2/open-api-patients/a1b2c3d4-e5f6-7890-abcd-ef0123456789/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 @merged-patient.json ``` * Python ```python import os import requests BASE = "https://open-api.shepherd.vet/pav2" 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"], } patient_id = "a1b2c3d4-e5f6-7890-abcd-ef0123456789" # Update fields with the same name on the record you read. SAME_NAME = ( "name", "breedId", "sexId", "statusId", "dateOfBirth", "color", "microchipNumber", "rabiesTag", "alerts", "additionalText", "patientCprstatusId", "patientCPRStatusNote", ) # 1. Read, embedding the links you intend to resend. read = requests.post( f"{BASE}/open-api-patients", headers=HEADERS, json={ "ids": patient_id, "rpp": 1, "embed": "patientPreferredProviders,patientReferralSources", }, timeout=30, ) read.raise_for_status() current = read.json()["item"][0] # 2. Merge: copy every update field from the record, then apply the change. payload = {f: current[f] for f in SAME_NAME if f in current} payload["preferredProviderIds"] = [ p["providerId"] for p in current.get("patientPreferredProviders") or [] ] payload["referralSourceIds"] = [ r["referralSourceId"] for r in current.get("patientReferralSources") or [] ] payload["alerts"] = "Allergic to penicillin" # the actual change # 3. Write the complete object back. write = requests.put( f"{BASE}/open-api-patients/{patient_id}/update", headers=HEADERS, json=payload, timeout=30, ) write.raise_for_status() updated = write.json() ``` * C# ```csharp using System.Net.Http.Json; using System.Text.Json.Nodes; const string Base = "https://open-api.shepherd.vet/pav2"; var patientId = "a1b2c3d4-e5f6-7890-abcd-ef0123456789"; // Update fields with the same name on the record you read. string[] sameName = [ "name", "breedId", "sexId", "statusId", "dateOfBirth", "color", "microchipNumber", "rabiesTag", "alerts", "additionalText", "patientCprstatusId", "patientCPRStatusNote", ]; using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) }; 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")); // 1. Read, embedding the links you intend to resend. var read = await http.PostAsJsonAsync($"{Base}/open-api-patients", new { ids = patientId, rpp = 1, embed = "patientPreferredProviders,patientReferralSources", }); read.EnsureSuccessStatusCode(); var current = (await read.Content.ReadFromJsonAsync())!["item"]![0]!.AsObject(); // 2. Merge: copy every update field from the record, then apply the change. var payload = new JsonObject(); foreach (var field in sameName) if (current.TryGetPropertyValue(field, out var value)) payload[field] = value?.DeepClone(); payload["preferredProviderIds"] = new JsonArray( (current["patientPreferredProviders"]?.AsArray() ?? []) .Select(p => (JsonNode?)p!["providerId"]!.DeepClone()).ToArray()); payload["referralSourceIds"] = new JsonArray( (current["patientReferralSources"]?.AsArray() ?? []) .Select(r => (JsonNode?)r!["referralSourceId"]!.DeepClone()).ToArray()); payload["alerts"] = "Allergic to penicillin"; // the actual change // 3. Write the complete object back. var write = await http.PutAsJsonAsync($"{Base}/open-api-patients/{patientId}/update", payload); write.EnsureSuccessStatusCode(); ``` * PHP ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode([ 'ids' => $patientId, 'rpp' => 1, 'embed' => 'patientPreferredProviders,patientReferralSources', ]), ]); $current = json_decode(curl_exec($ch), true)['item'][0]; curl_close($ch); // 2. Merge: copy every update field from the record, then apply the change. $payload = []; foreach ($sameName as $field) { if (array_key_exists($field, $current)) { $payload[$field] = $current[$field]; } } $payload['preferredProviderIds'] = array_column($current['patientPreferredProviders'] ?? [], 'providerId'); $payload['referralSourceIds'] = array_column($current['patientReferralSources'] ?? [], 'referralSourceId'); $payload['alerts'] = 'Allergic to penicillin'; // the actual change // 3. Write the complete object back. $ch = curl_init("$base/open-api-patients/$patientId/update"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode($payload), ]); $updated = json_decode(curl_exec($ch), true); curl_close($ch); ``` * JavaScript ```js const BASE = 'https://open-api.shepherd.vet/pav2'; const patientId = 'a1b2c3d4-e5f6-7890-abcd-ef0123456789'; const 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, }; // Update fields with the same name on the record you read. const SAME_NAME = [ 'name', 'breedId', 'sexId', 'statusId', 'dateOfBirth', 'color', 'microchipNumber', 'rabiesTag', 'alerts', 'additionalText', 'patientCprstatusId', 'patientCPRStatusNote', ]; // 1. Read, embedding the links you intend to resend. const read = await fetch(`${BASE}/open-api-patients`, { method: 'POST', headers, body: JSON.stringify({ ids: patientId, rpp: 1, embed: 'patientPreferredProviders,patientReferralSources', }), signal: AbortSignal.timeout(30_000), }); if (!read.ok) throw new Error(`Shepherd API ${read.status}: ${await read.text()}`); const [current] = (await read.json()).item; // 2. Merge: copy every update field from the record, then apply the change. const payload = {}; for (const field of SAME_NAME) { if (field in current) payload[field] = current[field]; } payload.preferredProviderIds = (current.patientPreferredProviders ?? []).map((p) => p.providerId); payload.referralSourceIds = (current.patientReferralSources ?? []).map((r) => r.referralSourceId); payload.alerts = 'Allergic to penicillin'; // the actual change // 3. Write the complete object back. const write = await fetch(`${BASE}/open-api-patients/${patientId}/update`, { method: 'PUT', headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(30_000), }); if (!write.ok) throw new Error(`Shepherd API ${write.status}: ${await write.text()}`); const updated = await write.json(); ``` ## Troubleshooting a rejected write [Section titled “Troubleshooting a rejected write”](#troubleshooting-a-rejected-write) Both write endpoints reject the whole request rather than partially applying it. When a create or update comes back `400`, work down this list: 1. **Are all the required fields present?** Create needs `name`, `clientId`, `breedId`, `sexId`, `statusId`, `dateOfBirth`. Update needs those minus `clientId`, plus `color`. A missing required field produces the generic “The request is invalid.” envelope described in [Errors](/api-reference/errors/), which does not currently name the offending field. 2. **Are the lookup IDs from the right environment?** Sandbox and production have entirely separate ID sets. An ID copied from production will not validate against sandbox, and vice versa. 3. **Is the breed from this clinic’s list and not retired?** Query breeds with `getBreedsByClinicId: true` and `isLegacy: false`. 4. **Is `dateOfBirth` in the past?** A future date of birth is rejected. 5. **Is the weight valid?** If you sent `patientWeight`, `weight` must be greater than zero and must pass validation for the `weightUnitId` you named. 6. **Still stuck on a create?** Include a valid `patientWeight` block; see the note under [Create](#recording-an-initial-weight). Note that unknown fields in the body are ignored rather than rejected, so a stray `speciesId` or a misspelled key will not itself cause a `400`; it simply will not be applied. ## File uploads [Section titled “File uploads”](#file-uploads) Patient files (lab PDFs, imaging stills, intake forms) are uploaded in three steps: 1. **Request a presigned upload URL.** `POST /pav2/open-api-patients/file-presigned-upload-url` takes `patientId` and `fileName`, and returns `url` (the short-lived S3 URL) and `path` (the key that identifies the object). 2. **PUT the binary directly to S3.** Bypasses the Shepherd application servers entirely. Send the raw file bytes with the appropriate `Content-Type` (e.g. `application/pdf`, `image/jpeg`). 3. **Register the file entry.** `POST /pav2/open-api-patients/file-entry-write` records `patientId`, `fileName`, and the `path` returned in step 1, so the file shows up in the patient chart. `fileName` is not the same in step 1 and step 3 Step 1 wants the file name **with** its extension (`lab-results.pdf`); it uses the extension to work out the content type. Step 3 wants the name **without** the extension (`lab-results`). Sending the extension in step 3 results in an entry that does not resolve correctly in the chart. Neither request takes a `contentType` field; the response from step 1 reports it back to you. For images, also send `width` and `height` on the step 3 request. They default to zero when omitted, which is rarely what you want for a stored image. ### Step 1: request a presigned upload URL [Section titled “Step 1: request a presigned upload URL”](#step-1-request-a-presigned-upload-url) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients/file-presigned-upload-url \ -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": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "fileName": "lab-results.pdf" }' ``` * Python ```python import os import requests presign = requests.post( "https://open-api.shepherd.vet/pav2/open-api-patients/file-presigned-upload-url", 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": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "fileName": "lab-results.pdf", }, timeout=30, ) presign.raise_for_status() upload = presign.json() # upload["url"] and upload["path"] are used in steps 2 and 3. ``` * 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 presign = await http.PostAsJsonAsync( "https://open-api.shepherd.vet/pav2/open-api-patients/file-presigned-upload-url", new { patientId = "a1b2c3d4-e5f6-7890-abcd-ef0123456789", fileName = "lab-results.pdf", }); presign.EnsureSuccessStatusCode(); var upload = await presign.Content.ReadFromJsonAsync(); // upload.GetProperty("url") and upload.GetProperty("path") ``` * 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' => 'a1b2c3d4-e5f6-7890-abcd-ef0123456789', 'fileName' => 'lab-results.pdf', ]), ]); $upload = json_decode(curl_exec($ch), true); curl_close($ch); // $upload['url'] and $upload['path'] ``` * JavaScript ```js const presign = await fetch( 'https://open-api.shepherd.vet/pav2/open-api-patients/file-presigned-upload-url', { 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: 'a1b2c3d4-e5f6-7890-abcd-ef0123456789', fileName: 'lab-results.pdf', }), }, ); if (!presign.ok) { throw new Error(`Shepherd API ${presign.status}: ${await presign.text()}`); } const upload = await presign.json(); // upload.url, upload.path ``` ### Step 2: PUT the binary to S3 [Section titled “Step 2: PUT the binary to S3”](#step-2-put-the-binary-to-s3) This call goes to S3, not to the Shepherd API; do **not** send the integration headers. Use the URL returned in step 1 and match the `Content-Type` you registered. * curl ```sh curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: application/pdf" \ --data-binary @lab-results.pdf ``` * Python ```python with open("lab-results.pdf", "rb") as fh: put = requests.put( upload["url"], data=fh, headers={"Content-Type": "application/pdf"}, timeout=120, ) put.raise_for_status() ``` ### Step 3: register the file entry [Section titled “Step 3: register the file entry”](#step-3-register-the-file-entry) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-patients/file-entry-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": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "path": "", "fileName": "lab-results" }' ``` * Python ```python entry = requests.post( "https://open-api.shepherd.vet/pav2/open-api-patients/file-entry-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": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "path": upload["path"], "fileName": "lab-results", # no extension here }, timeout=30, ) entry.raise_for_status() ``` * C# ```csharp var entry = await http.PostAsJsonAsync( "https://open-api.shepherd.vet/pav2/open-api-patients/file-entry-write", new { patientId = "a1b2c3d4-e5f6-7890-abcd-ef0123456789", path = upload.GetProperty("path").GetString(), fileName = "lab-results", // no extension here }); entry.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([ 'patientId' => 'a1b2c3d4-e5f6-7890-abcd-ef0123456789', 'path' => $upload['path'], 'fileName' => 'lab-results', // no extension here ]), ]); curl_exec($ch); curl_close($ch); ``` * JavaScript ```js const entry = await fetch( 'https://open-api.shepherd.vet/pav2/open-api-patients/file-entry-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: 'a1b2c3d4-e5f6-7890-abcd-ef0123456789', path: upload.path, fileName: 'lab-results', // no extension here }), }, ); if (!entry.ok) { throw new Error(`Shepherd API ${entry.status}: ${await entry.text()}`); } ``` ### Listing attachments [Section titled “Listing attachments”](#listing-attachments) `POST /pav2/open-api-patients/attachments` returns the registered files for a patient, paginated with the same conventions as every other collection endpoint. Pass a `patientId` filter to scope to a single chart. ## See also [Section titled “See also”](#see-also) * [Conventions](/api-reference/conventions/): pagination, embed, sort, and date-range rules. * [Clients](/api-reference/resources/clients/): the owners patients belong to. * [Appointments](/api-reference/resources/appointments/): scheduled visits for a patient. * [SOAP records](/api-reference/resources/soap-records/): clinical notes captured during a visit. * [Errors](/api-reference/errors/): HTTP status codes and the error body shapes. # Payments > Recording payments, payment methods, and client balances. Distinct from invoices. Payments are the money side of the invoice ledger: a payment applies a tender (cash, card, check, in-house credit) against one or more invoices for a client. The endpoints here cover three things most billing integrations need: listing payments that have already been recorded, listing the payment methods a clinic accepts, and reading client balances (current and aged). If you’re trying to *generate* a charge, that’s invoicing; see [Invoices](/api-reference/resources/invoices/). This page is about what happens after the invoice is finalized. ## 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 payment identifier. | | `clientId` | UUID | Client the payment applies to. | | `clinicId` | UUID | Clinic the payment was recorded at. | | `paymentDate` | ISO 8601 | When the payment was taken (UTC). | | `amount` | decimal | Tender amount. | | `paymentMethodId` | UUID | The tender type (cash, card brand, check, credit). See payment-methods endpoint below. | | `paymentStatusId` | UUID | Status (pending, approved, declined, voided, refunded). See [Lookups](/api-reference/resources/lookups/). | | `referenceNumber` | string | Check number, terminal reference, or similar. | | `authCode` | string | Authorization code returned by the card processor, when applicable. | | `cardType` | string | Card brand (Visa, Mastercard, etc.), when applicable. | | `lastDigits` | string | Last four digits of the card, when applicable. | | `transactionId` | string | Processor transaction identifier, when applicable. | | `payToCreditBalance` | decimal | Portion of the payment applied to the client’s in-house credit, when applicable. | | `clientBalanceAfterPayment` | decimal | Client’s outstanding balance after this payment is applied (informational). | | `refundedPaymentId` | UUID | When this record represents a refund, the id of the original payment it refunds. | | `processedByUserId` | UUID | Staff user who processed the payment. | | `note` | string | Free-text note attached to the payment. | | `isDeleted` | boolean | Soft-delete flag. | | `dateVoided` | ISO 8601 | Set when the payment has been voided. | | `dateCreated` | ISO 8601 | Server-assigned creation timestamp (UTC). | | `dateUpdated` | ISO 8601 | Last server-side mutation (UTC). | ## List payments [Section titled “List payments”](#list-payments) POST `/pav2/open-api-payments` Returns payments recorded at the clinic identified by `X-Clinic-Id`. Filter by client, status, or date range as needed. For a group with sharing enabled, `clinicIds` widens the query to other clinics in the group. ### Example [Section titled “Example”](#example) * curl ```sh curl -X POST https://open-api.shepherd.vet/pav2/open-api-payments \ -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":"paymentDate|desc","clientIds":""}' ``` * 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/).