SOAP records

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

Authoritative schemas live in the live Swagger UI. 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

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

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"
  }'

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"])

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
$ch = curl_init('https://open-api.shepherd.vet/pav2/open-api-soaps');
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' => 25,
        'sort' => 'dateCreated|desc',
        'patientIds' => 'a1b2c3d4-e5f6-7890-abcd-ef0123456789',
        'embed' => 'patient,appointment',
    ]),
]);
$payload = json_decode(curl_exec($ch), true);
curl_close($ch);

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

{
  "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

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.

Everything else in the SOAP structure (subjective, objective/physical exam, assessment, plan) is read only.

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, 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.