Tasks

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

Authoritative schemas live in the live Swagger UI. 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.
taskEntryStatusId	UUID	Status (pending / in progress / completed). See 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

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.

Example

curl

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

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,
    },
    timeout=30,
)
resp.raise_for_status()
for t in resp.json()["item"]:
    print(t["dateDue"], t["name"], t["taskEntryStatus"]["name"])

C#

using System.Net.Http.Json;

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

var body = JsonContent.Create(new {
    page = 1,
    rpp = 50,
    sort = "dateDue|asc",
    embed = "taskEntryPriorityStatus,taskEntryStatus",
    isDeleted = false,
});
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
$ch = curl_init('https://open-api.shepherd.vet/pav2/open-api-task-entries');
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' => 50,
        'sort' => 'dateDue|asc',
        'embed' => 'taskEntryPriorityStatus,taskEntryStatus',
        'isDeleted' => false,
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

JavaScript

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,
    }),
  },
);
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

{
  "item": [
    {
      "id": "e8a1d2c3-...",
      "clinicId": "f2a4c6e8-...",
      "name": "Call owner about lab results",
      "description": "<p>Follow up on the CBC from yesterday's visit.</p>",
      "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

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.

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": "<p>Follow up on the CBC from yesterday's visit.</p>",
    "dateDue": "2026-05-29T17:00:00Z",
    "taskEntryPriorityStatusId": "<PRIORITY_GUID>",
    "clientId": "<CLIENT_GUID>",
    "patientId": "<PATIENT_GUID>",
    "assignedToUsersIds": ["<USER_GUID>"]
  }'

The server returns the created task as the response body, with id populated.

Update a task

PUT /pav2/open-api-task-entries/update/{id}

Patches the task with the supplied fields. Omitted fields are left as-is. To mark a task complete, send the appropriate taskEntryStatusId from the status lookup. The same assignment rule applies on update: users or teams, not both.

curl -X PUT https://open-api.shepherd.vet/pav2/open-api-task-entries/update/<TASK_GUID> \
  -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 '{ "taskEntryStatusId": "<COMPLETED_STATUS_GUID>" }'

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.

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.

See also

• Users for the assignee ids that go into assignedToUsersIds.
• Clients and Patients for the context ids on a task.
• Conventions for pagination, embedding, sorting, and date filters.
• Errors for the two JSON error body shapes.