Your first integration

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

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.
A clinic UUID your integration has been granted access to.

1. Set environment variables

The examples below read three environment variables:

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

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 POSTs; 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); one day is well inside that.

3. Call the API

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

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

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
$today = gmdate('Y-m-d');

$ch = curl_init('https://open-api.shepherd.vet/pav2/open-api-appointments');
curl_setopt_array($ch, [
    CURLOPT_POST => 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";
}

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

The response is a collection envelope (see Conventions):

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

Inline related records (clients, patients, providers) with embed. See Conventions.
Read the Appointments resource reference 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.