Skip to main content
All CollectionsRelease Notes
Shepherd OpenAPI | Release Notes 2/5/2025
Shepherd OpenAPI | Release Notes 2/5/2025

Stay up to date with the latest improvements to the Shepherd OpenAPI.

Updated over 2 weeks ago

In this release, we’re introducing new endpoints to streamline tax rate management, improve scheduling accuracy, enhance prescription validation, support new ClinicID filtering, and enable new client balance capabilities. These updates are designed to provide more precise automation and control over clinic operations, ensuring smoother integrations for our partners.

This article outlines the new features, updated endpoints, and important changes that may require adjustments to your current integrations.

For full details, explore our updated resources below:

🔗 Swagger Documentation: Shepherd API Swagger
📖 OpenAPI Documentation: Shepherd OpenAPI Article

📌General Reminders

Shepherd offers robust group account capabilities, including support for GroupID details, ClinicID, and ClinicID filtering when data is shared at a group level. Explore our help guides to learn more about multi-location configurations!

Multi-Location Configurations

🆕 New Features & Updates

Add New Clients and Patients

Description:
An appointment can automatically create a new client/patient in Shepherd.

Endpoints:

  • Client: POST /open-api-clients/write

  • Patient: POST /open-api-patients/write

Supporting Endpoints:

  • Country: GET /open-api-countries

  • Phone Type: GET /open-api-phone-types

  • Patient Status: GET /open-api-patient-statuses

  • Patient CPR Status: GET /open-api-patient-cpr-statuses

Add Notes or Attachments to Patient Medical Record

Description:
Allows clinics to add communication history, diagnostic results, completed forms, or survey responses to the medical record.

Endpoints:

  • Patient Attachments: POST /open-api-patients/file-presigned-upload-url

  • Patient File Entry: POST /open-api-patients/file-entry-write

  • Patient Notes: POST /open-api-patient-notes/write

Both attachments and plain text writeback are supported.

Located in Patient History

Located in Patient History. Included in Medical Record (attachments are downloaded or sent via email separately).

Clinic Zip Code Tax Rates

Description:
Retrieve tax rates by clinic zip code for improved regional tax compliance and automated tax handling.

Endpoint:
​GET /api/v1/tax/clinic-zip-code-tax-rate

Use Case:

  • Automatically pull zip-code-specific tax rates to apply the correct tax rate during invoicing.

  • Enables real-time tax rate adjustments based on the clinic’s location.

Parameters:

  • clinic_id (string, required)

  • zip_code (string, required)

  • effective_date (optional, defaults to current date)

Tax Rate Types

Description:
Retrieve all available tax rate types (e.g., standard, reduced, zero-rated) for services and products.

Endpoint:
​GET /api/v1/tax/tax-rate-types

Use Case:

  • Enables clinics to configure and assign the correct tax type to different products and services.

Parameters:

  • clinic_id (string, required)

  • category (optional, defaults to all types)

Tax Rate by Clinic

Description:
Fetch applicable tax rates specific to a clinic, accounting for both service and product tax classes.

Endpoint:
​GET /api/v1/tax/rates-by-clinic

Use Case:

  • Provides tax rate information for clinics handling multi-location tax management.

Parameters:

  • clinic_id (string, required)

  • tax_class (optional, filters by product/service class)

Product Tax Rates – New Filters

Description:
Added filtering capabilities to retrieve product tax rates based on clinic or group identifiers.

Endpoint:
​GET /api/v1/tax/product-tax-rate

Use Case:

  • Filter by clinicId or groupId to return product-specific tax rates relevant to the selected location or group.

Parameters:

  • clinicId (string, optional)

  • groupId (string, optional)

Product Tax Rate – Soft Delete

Description:
Implemented soft delete functionality for product tax rates to allow recovery or audit tracking.

Endpoint:
​DELETE /api/v1/tax/product-tax-rate

Use Case:

  • Instead of permanently deleting product tax rates, mark them as inactive with the ability to restore later.

Parameters:

  • product_tax_id (string, required)

  • soft_delete (boolean, defaults to true)

Provider Availability – Timeslot Updates

Description:
Start and end dates are now mandatory for retrieving provider availability timeslots, ensuring more accurate scheduling data.

Endpoint:
​GET /api/v1/provider/availability

Use Case:

  • Clinics can query available provider timeslots for specific date ranges to improve scheduling workflows.

Parameters:

  • provider_id (string, required)

  • startDate (date, required)

  • endDate (date, required)

Prescription Writing Improvements

Description:
Enhancements to prescription handling and validation to improve compliance and prevent errors.

Endpoint:
​POST /open-api-prescriptions/write

Key Updates:

  • Users can no longer create non-controlled written prescriptions without a prescribingDoctorId.

  • Expired prescriptions can no longer be created.

  • Prevented creation of prescriptions where RefillCount exceeds RefillQuantity.

  • Improved error messaging for failed prescription creation, including updates to isWritten, SoapID, and Quantity parameter descriptions.

Client Details for Regulatory Reporting

Description:
New fields added to support compliance with CURES and State Controlled Medication Reporting.

Endpoint Updates:

  • Client Endpoint: Added the following fields:

    • GenderId

    • ClientGender (with embedded Name and Abbreviation)

    • DateOfBirth (DOB)

  • ClientInfo Endpoint: Added:

    • Driver’s License

    • Driver’s License State

    • Driver’s License Expiration Date

    • Added filtering by clinicIds for refined queries.

Use Case:

  • Ensures collected client details are exportable for regulatory reporting by integration partners like VetSnap and Cubex.

Expanded ClinicID Filtering for SOAP & Other Endpoints

We’ve extended ClinicID filtering to additional SOAP-related endpoints and common record types, allowing integrators to narrow data to specific clinics in multi-location (msite) configurations. This filter applies only if the group is set to share clients/patients across clinics.

Key Endpoints Receiving ClinicID Filter Updates:

  • SoapDischargeInstructions

  • Refill

  • SoapAssessment

  • SoapPlanRecommendation

  • Client Balances (pav2/open-api-client-balances/balances)

(Note: pav2/open-api-client-balances/aging previously supported this filter, but is now officially documented in this release.)

Parameter

  • Typically clinicIds (comma-separated UUIDs).

  • If omitted (and sharing is enabled), the endpoint will include records from all clinics in the group.

Use Cases

  • Multi-Clinic Data Control: Each location sees only relevant discharge instructions, refills, or SOAP assessments.

  • Refined Queries: Integrators can query precisely the data they need by clinic for reporting or day-to-day workflows.

Open API Client Balances Endpoints

To improve financial visibility, we’ve introduced two endpoints under pav2/open-api-client-balances:

  1. POST /pav2/open-api-client-balances/balances

    • Retrieves real-time client balances (outstanding amounts, credits on file, etc.).

    • Useful for immediate visibility into owed balances across one or multiple clinics.

  2. POST /pav2/open-api-client-balances/aging

    • Returns aging data for client invoices, beneficial for automated overdue reminders or collections workflows.

    • Support for clinicIds ensures you can focus on a single clinic or multiple clinics as needed.

Both endpoints support ClinicID filtering to narrow results by clinic, especially helpful in multi-location contexts.

🔧 Improvements

  • Performance Enhancements: Response times for tax endpoints reduced by 20% through database optimization and caching strategies.

  • Validation Updates: Enhanced validation to ensure accurate data entry for tax rates, provider schedules, and prescription workflows.

  • Improved Parameter Descriptions: Updates to SoapID, Quantity, and isWritten for clearer guidance in prescription creation.

  • Client Embedding Fixes: Resolved an issue where certain fields (including clientId) were missing when embedding clients in multiple endpoints. Now, Appointment, Clients, ClientPatient, ClientReferralSource, and Patient endpoints consistently return the clientId field (among other previously missing fields) whenever a client is embedded. This ensures integrators have complete data in embedded objects.

⚠️ Breaking Changes

  • Provider Availability Timeslots: startDate and endDate are now required for all timeslot queries. Previously, these were optional, which may require updating existing queries.

  • Prescription Writing: Stricter validation may require partners to update their workflows to comply with the new parameters.

📚 Migration Notes

  1. Provider Availability: Existing implementations fetching provider availability must now include startDate and endDate.

  2. Tax Rate Deletions: For tax rate deletions, ensure soft_delete is explicitly set to true to avoid permanent deletions.

  3. Prescription Validation: Ensure integrations involving prescriptions align with the updated validation rules.

  4. Client & ClientInfo: Review workflows for these endpoints to accommodate new fields and filtering options.

  5. ClinicID Filtering: For multi-location setups, leverage clinicIds on updated SOAP and client balance endpoints for location-specific queries.

  6. Client Embedding: If your integration relies on embedded client objects, confirm that the newly included clientId and other fields meet your data needs.

❓ Questions or Support

If you have questions or need support, please contact OpenAPI@shepherd.vet or consult the Shepherd OpenAPI Documentation for more details.

Did this answer your question?