Shepherd Veterinary Software Prescription API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Prescription API
  description: 'Production Base URL: https://open-api.shepherd.vet/pav2/


    Production App URL: https://app.shepherd.vet/


    Production Documentation URL: https://app.shepherd.vet/swagger/


    Sandbox Base URL: https://demo-open-api.shepherd.vet/pav2/


    Sandbox App URL: https://demo.shepherd.vet/


    Sandbox Documentation URL: https://demo.shepherd.vet/swagger


    Authorization: The integration is authorized by providing two headers in the API call


    X-Integration-Private-Key - this contains the private key from your credentials

    X-Integration-Public-Key - this contains the public key from your credentials


    Additionally, for all requests other than Clinic, the X-Clinic-Id header must be provided with the value of the clinic entity id for which you are running the API requests. You can get the entity id by calling the Clinic endpoint. If authorization fails, the request returns HTTP status 401 and the response body is one of the messages below. Missing X-Integration-Public-Key header - the public key header is absent from the request. Missing X-Integration-Private-Key header - the private key header is absent from the request. Missing X-Clinic-Id header - the clinic identifier header is absent, and the endpoint is clinic scoped. Incorrect API keys provided - both key headers were supplied, but the public key matches no integration, or the private key is not valid for that integration. Integration not enabled for the provided clinic - the key pair is valid, but the integration is not enabled and active for the clinic supplied in X-Clinic-Id. NEW: Each API call will count against your RPH and RPM limits. Once you exhaust those limits, requests will start returning HTTP status 429. The RPH is set to 12000 and RPM to 800 (subject to change). Where an endpoint supports searchQuery, a query longer than 500 characters may return HTTP status 400 with ERROR_MESSAGES.SEARCH_PHRASE.TOO_LONG, and a query with more than 10 words may return HTTP status 400 with ERROR_MESSAGES.SEARCH_PHRASE.TOO_MANY_PHRASES. NOTE: Since this API is WIP, we would be happy to hear any feedback and to implement additional filtering/sorting options etc. **Endpoints:

    All endpoints are POST requests that accept JSON bodies. The common request properties for all endpoints are:**


    rpp::int - The number of items to return per page. The max is 1000. Defaults to 10. page::int - The page number. Defaults to 1. sort::string - Which field to sort by. Needs to be in "field|order" format, where order is either "asc" or "desc". All top-level properties should be sortable, only some nested-fields work and you should probably not use them until this API reaches production and we settle on which nested-field sortings we will support. Default depends on endpoint, usually "id|asc". embed::string - Comma-separated values for nested-fields you want to fetch (eg. "clientPhones,clientPhones.phoneType" on Client endpoint). If a specific embed is not requested, the response will contain either null or an empty array for that value. No default. dateCreatedFrom::date

    dateCreatedTo::date

    dateUpdatedFrom::date

    dateUpdatedTo::date

    - Date range filters for either the creation date or last update date. - You can pass in either one end or both of them. *


    * Only the date filters listed on an endpoint''s request model are supported; sending another one, or a ''From'' later than its ''To'', returns HTTP status 400. The request responses will come back as a JSON object. The common response properties for all endpoints are:


    embed::string - Lists the embed used in the request. This may sometimes be different from what you sent in, if in the future we add that some embeds get set automatically on certain endpoints

    links::object[] - Always empty, a leftover from the internal framework we use on our web API. Will be removed in the future if possible so do not rely on this

    page::int - Which page was fetched.'
servers:
- url: https://open-api.shepherd.vet
tags:
- name: Prescription
paths:
  /pav2/open-api-prescriptions:
    post:
      tags:
      - Prescription
      summary: Retrieves {OpenApiPrescriptionController.Prescription} resources that match the…
      description: 'Example Request

        {

        "clinicIds": "a1234567-89ab-4cde-b234-b2bb00aabbcc",

        "embed": "createdByUser"

        }


        Example Response

        {

        "embed": "createdByUser",

        "item": [

        {

        "cancelNote": null,

        "clinicId": "a1234567-89ab-4cde-b234-b2bb00aabbcc",

        "createdByPav2User": null,

        "createdByUser": {

        "firstName": "Jhon",

        "lastName": "Doe",

        "dateCreated": "2025-04-10T08:00:00Z",

        "dateUpdated": "2025-04-10T08:00:00Z",

        "id": "b9988776-1234-4fed-9123-b2ee00ccddaa"

        },

        "createdByUserId": "b9988776-1234-4fed-9123-b2ee00ccddaa",

        "direction": "Take with food",

        "expirationDate": "2025-12-31T23:59:59Z",

        "isCanceled": false,

        "isChronicMedication": true,

        "isRefillAllowed": true,

        "isWritten": true,

        "name": "Prescription A-200",

        "patientId": "c1122334-5678-4abc-98ef-b2aa00bbccdd",

        "pav2User": null,

        "prescribingDoctor": null,

        "prescribingDoctorId": "d4455667-89ab-4cde-9012-b2cc00ddeeff",

        "productId": null,

        "quantity": 2,

        "refillCount": 3,

        "refillPrn": false,

        "refillQuantity": 2,

        "soapId": null,

        "substitutionPermitted": true,

        "writtenIsControlled": false,

        "writtenProduct": "Canis Pain Relief 20mg",

        "dateCreated": "2025-06-01T10:15:30Z",

        "dateUpdated": "2025-06-01T10:15:30Z",

        "id": "f7788990-aabb-4ccd-88ee-b2dd00ffaabb"

        }

        ],

        "links": [],

        "page": 1,

        "recordsPerPage": 10,

        "searchQuery": null,

        "sort": null,

        "totalRecords": 1

        }'
      operationId: OpenApiPrescriptionGet
      parameters:
      - name: x-integration-public-key
        in: header
        description: Your public API key
        required: true
        schema:
          type: string
      - name: x-integration-private-key
        in: header
        description: Your private API key
        required: true
        schema:
          type: string
      - name: x-clinic-id
        in: header
        description: The clinic uuid identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A paged collection of prescriptions matching the supplied filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiPrescriptionController.Prescription'
            text/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiPrescriptionController.Prescription'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiPrescriptionController.Prescription'
        '401':
          description: 'Authorization failed. One of: Missing X-Integration-Public-Key header, Missing X-Integration-Private-Key header, Missing X-Clinic-Id header, Incorrect API keys provided, or Integration not enabled for the provided clinic.'
        '429':
          description: Request rate limit exceeded. Please wait before making further requests. Returned once the integration passes its configured hourly or per-minute request allowance.
        '400':
          description: "A filter is outside the limits for this endpoint. The response body is one of:\n             \"DateCreated filter 'From' can't be later than 'To'.\" - dateCreatedFrom is after dateCreatedTo.\n             \"DateUpdated filter 'From' can't be later than 'To'.\" - dateUpdatedFrom is after dateUpdatedTo.\n             \"ERROR_MESSAGES.SEARCH_PHRASE.TOO_LONG\" - searchQuery is longer than 500 characters.\n             \"ERROR_MESSAGES.SEARCH_PHRASE.TOO_MANY_PHRASES\" - searchQuery contains more than 10 search terms; each word counts as one term, and text in double quotes counts as one term."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiPrescriptionController.PrescriptionFilterModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiPrescriptionController.PrescriptionFilterModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiPrescriptionController.PrescriptionFilterModel'
        description: The model.
        required: true
  /pav2/open-api-prescriptions/write:
    post:
      tags:
      - Prescription
      summary: Inserts a new {OpenApiPrescriptionController.PrescriptionWriteModel} resource
      description: 'Example Request

        {

        "expirationDate": "2025-06-30T10:13:15.000Z",

        "isChronicMedication": false,

        "isWritten": false,

        "patientId": "f1a2b3c4-5678-4d90-8123-abcdef123456",

        "prescribingDoctorId": "12345678-9abc-def0-1234-56789abcdef0",

        "productId": "0f1e2d3c-4b5a-6978-90ab-cdef12345678",

        "quantity": 2,

        "refillCount": 2,

        "refillQuantity": 3

        }


        Example Response

        {

        "cancelNote": null,

        "clinicId": "aa12bb34-cc56-7890-dd12-ee34ff56gg78",

        "createdByPav2User": null,

        "createdByUser": null,

        "createdByUserId": "98abc123-4567-4def-8901-23456789abcd",

        "direction": null,

        "expirationDate": "2025-06-30T06:13:15",

        "isCanceled": false,

        "isChronicMedication": false,

        "isRefillAllowed": true,

        "isWritten": false,

        "name": null,

        "patientId": "f1a2b3c4-5678-4d90-8123-abcdef123456",

        "pav2User": null,

        "prescribingDoctor": null,

        "prescribingDoctorId": "12345678-9abc-def0-1234-56789abcdef0",

        "productId": "0f1e2d3c-4b5a-6978-90ab-cdef12345678",

        "quantity": 2,

        "refillCount": 2,

        "refillPrn": false,

        "refillQuantity": 3,

        "soapId": null,

        "substitutionPermitted": false,

        "writtenIsControlled": null,

        "writtenProduct": null,

        "dateCreated": "2025-06-30T11:18:37.0913316Z",

        "dateUpdated": "2025-06-30T11:18:37.0913316Z",

        "id": "77ee88ff-99aa-4bcc-bdee-001122334455"

        }'
      operationId: OpenApiPrescriptionPost
      parameters:
      - name: x-integration-public-key
        in: header
        description: Your public API key
        required: true
        schema:
          type: string
      - name: x-integration-private-key
        in: header
        description: Your private API key
        required: true
        schema:
          type: string
      - name: x-clinic-id
        in: header
        description: The clinic uuid identifier
        required: true
        schema:
          type: string
      responses:
        '201':
          description: The created prescription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiPrescriptionController.Prescription'
            text/json:
              schema:
                $ref: '#/components/schemas/OpenApiPrescriptionController.Prescription'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OpenApiPrescriptionController.Prescription'
        '401':
          description: 'Authorization failed. One of: Missing X-Integration-Public-Key header, Missing X-Integration-Private-Key header, Missing X-Clinic-Id header, Incorrect API keys provided, or Integration not enabled for the provided clinic.'
        '429':
          description: Request rate limit exceeded. Please wait before making further requests. Returned once the integration passes its configured hourly or per-minute request allowance.
        '400':
          description: "A validation rule failed. The response body is one of:\n             (empty body) - the request body is missing.\n             \"The request is invalid.\" with modelState - expirationDate or patientId is missing. modelState names the offending field.\n             \"The Quantity Dispensed must be greater than 0\" - quantity is missing, 0 or negative.\n             \"ProductId is required for in-house prescriptions when 'isWritten' is false. For written prescriptions, 'isWritten' must be true, and 'ProductId' should not be provided.\" - isWritten is false and productId is missing or the empty GUID.\n             \"If the prescription is Written (isWritten property is true), no ProductId should be included in the request.\" - isWritten is true and a productId is supplied.\n             \"PatientId is required and cannot be empty.\" - patientId is the empty GUID.\n             [\"The provided PatientId does not belong to the clinic.\", ...] - a JSON array with one entry per identifier that does not resolve: PatientId (not a patient in the caller's clinic), SoapId (not a SOAP of that patient in the caller's clinic), ProductId (not a product of the caller's clinic) or PrescribingDoctorId (not a doctor in the caller's group).\n             \"A prescribingDoctorId is required to create a substitutionPermitted non-controlled written prescription.\" - prescribingDoctorId is omitted while substitutionPermitted is true and writtenIsControlled is false.\n             \"The date cannot be set to a value earlier than today.\" - expirationDate is before today in the clinic's time zone.\n             \"The Refill Quantity cannot be less than 0.\" - refillQuantity is negative.\n             \"The Refill Count cannot be less than 0.\" - refillCount is negative.\n             \"The Refill Count cannot exceed the Refill Quantity.\" - refillCount is greater than refillQuantity.\n             \"Prescriptions cannot be created with product type: Vaccine\" - productId refers to a vaccine product.\n             \"INVENTORY_PRODUCT.INVENTORY_TRACKING.LOT_REQUIRED\" - an in-house prescription for an inventory-tracked product in a clinic with inventory tracking enabled; lots cannot be supplied through this endpoint."
        '409':
          description: '"PRESCRIPTION.ERROR.SOAP_LOCKED" - soapId refers to a locked SOAP.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiPrescriptionController.PrescriptionWriteModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiPrescriptionController.PrescriptionWriteModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiPrescriptionController.PrescriptionWriteModel'
        description: The model.
        required: true
components:
  schemas:
    OpenApiPrescriptionController.PrescriptionWriteModel:
      description: Prescription write REST model
      required:
      - expirationDate
      - patientId
      type: object
      properties:
        direction:
          description: Free-text field for Direction, explaining how to use the product/medication.
          type: string
        expirationDate:
          format: date-time
          description: 'The expiration date of the prescription. In the application, this is labeled ''Rx Valid Thru''.

            It represents the last date on which the prescription is valid for refills.'
          type: string
        isChronicMedication:
          description: Flag indicating whether this prescription is chronic medication.
          type: boolean
        isWritten:
          description: Indicates if this is a written prescription. If true, 'productId' should not be included in the request.
          type: boolean
        patientId:
          description: Unique identifier representing the related Patient entity.
          type: string
        prescribingDoctorId:
          description: Unique identifier representing the related user entity who prescribed this prescription.
          type: string
        productId:
          description: 'Product identifier. If the prescription type is not "Written" (i.e., isWritten is false), a productId must be provided.

            If the prescription type is "Written" (i.e., isWritten is true), no productId should be specified.'
          type: string
        quantity:
          format: double
          description: Quantity Dispensed. The default value is 0.
          type: number
        refillCount:
          format: int32
          description: 'Refill Count: The number of refills available for this prescription.

            The value cannot exceed the refill quantity. If no value is provided, it defaults to the value of the refill quantity.'
          type: integer
        refillPrn:
          description: Flag indicating whether this prescription supports PRN refills.
          type: boolean
        refillQuantity:
          format: int32
          description: Total Available Refill Amount. If this value is not provided, it defaults to 0.
          type: integer
        soapId:
          description: Unique identifier representing the SOAP entity. Adding this to the model will create a SOAP prescription.
          type: string
        substitutionPermitted:
          description: Flag indicating whether substitution is permitted for the written prescription product.
          type: boolean
        writtenIsControlled:
          description: Flag indicating whether written prescription product is a controlled product.
          type: boolean
        writtenProduct:
          description: Name of the written product, used when flag "IsWritten" is set to true.
          type: string
    OpenApiPrescriptionController.Pav2User:
      description: Pav2User rest model.
      type: object
      properties:
        licenseNumber:
          description: Pav2User's License number.
          type: string
        prefix:
          description: Pav2User's prefix.
          type: string
        suffix:
          description: Pav2User's suffix.
          type: string
        userId:
          description: Unique identifier of this Pav2User.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiPrescriptionController.PrescriptionFilterModel:
      description: Prescription Filter REST model
      type: object
      properties:
        clientIds:
          description: Comma-separated string of Client identifiers. Default is null.
          type: string
        clinicIds:
          description: 'Comma-separated list of clinic identifiers. Defaults to null.

            This filter applies only if the group to which the clinic belongs shares clients and patients.

            If provided, only Prescription data from the specified clinics will be returned - but only if the clinic is the patient''s home clinic (regardless of the x-clinic-id in the header).

            If null, data from all clinics in the group will be returned.'
          type: string
        includePatientHomeClinic:
          description: "Used to support multi-site practices that share patients and clients.\nDetermines whether to include Prescriptions from a patient's home clinic\nwhen filtering by clinic.\n            \nBehavior:\n- If true:\n  - Includes Prescriptions from the specified clinic (default)\n  - Also includes Prescriptions from other clinics where the patient's home clinic\n    matches the specified clinic\n- If false (default):\n  - Only includes Prescriptions directly from the specified clinic\n            \nNote: The patient's home clinic is only considered if ClinicIds are provided\nin the filter; otherwise, all data from the group is returned."
          type: boolean
        patientIds:
          description: Comma-separated string of Patient identifiers. Default is null.
          type: string
        productIds:
          description: Comma-separated string of Product identifiers. Default is null.
          type: string
        searchQuery:
          description: Filters prescriptions by the 'direction' text.
          type: string
        dateCreatedFrom:
          format: date-time
          description: 'Sets the start of the date range filter on the entity creation date. Must not be later than DateCreatedTo, or

            the request returns 400. Defaults to null.'
          type: string
        dateCreatedTo:
          format: date-time
          description: The end of the date range filter on the entity creation date. Defaults to null.
          type: string
        dateUpdatedFrom:
          format: date-time
          description: 'The start of the date range filter on the entity last update date. Must not be later than DateUpdatedTo, or the

            request returns 400. Defaults to null.'
          type: string
        dateUpdatedTo:
          format: date-time
          description: The end of the date range filter on the entity last update date. Defaults to null.
          type: string
        embed:
          description: Comma-separated list of embedded properties to fetch. Nested fetches can be specified using dot notation (e.g., "client.clientPhones"). Defaults to null.
          type: string
        excludeIds:
          description: Comma-separated list of IDs representing entities that you wish to exclude from your search. Defaults to null.
          type: string
        ids:
          description: Comma-separated list of IDs representing entities that you wish to include in your search. Defaults to null.
          type: string
        page:
          format: int32
          description: The page number. Defaults to 1.
          type: integer
        rpp:
          format: int32
          description: The number of items to return per page. The max is 1000. Defaults to 10.
          type: integer
        sort:
          description: Which field to sort by. Needs to be in "field|order" format, where order is either "asc" or "desc". The default sort field depends on the endpoint, typically "id|asc"
          type: string
    OpenApiPrescriptionController.Prescription:
      description: Prescription REST model.
      type: object
      properties:
        cancelNote:
          description: Free-text field for Cancel note, this is mandatory field when canceling prescription.
          type: string
        clinicId:
          description: Unique identifier representing the related Clinic entity.
          type: string
        createdByPav2User:
          $ref: '#/components/schemas/OpenApiPrescriptionController.Pav2User'
          description: Object representing the related User entity who Created this Prescription.
        createdByUser:
          $ref: '#/components/schemas/OpenApiPrescriptionController.UserInfo'
          description: Object representing the related UserInfo entity for user who created this Prescription.
        createdByUserId:
          format: uuid
          description: Unique identifier representing the related user who Created this Prescription.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        direction:
          description: Free-text field for Direction, explaining how to use the product/medication.
          type: string
        expirationDate:
          format: date-time
          description: 'The expiration date of the prescription. In the application, this is labeled ''Rx Valid Thru''.

            It represents the last date on which the prescription is valid for refills.'
          type: string
        isCanceled:
          description: Flag indicating whether this prescription is canceled.
          type: boolean
        isChronicMedication:
          description: Flag indicating whether this prescription is chronic medication.
          type: boolean
        isPartiallyReturned:
          description: Flag indicating whether this prescription was partially returned, which voids any remaining refills.
          type: boolean
        isRefillAllowed:
          description: Indicates whether refills are allowed. Set to true if 'refillQuantity' > 0; otherwise, false.
          type: boolean
        isWritten:
          description: Indicates if this is a written prescription. If true, 'productId' should not be included in the request.
          type: boolean
        name:
          description: The name of the prescription.
          type: string
        patientId:
          description: Unique identifier representing the related Patient entity.
          type: string
        pav2User:
          $ref: '#/components/schemas/OpenApiPrescriptionController.Pav2User'
          description: Object representing the related Pav2 user entity.
        prescribingDoctor:
          $ref: '#/components/schemas/OpenApiPrescriptionController.UserInfo'
          description: Object representing UserInfo of the User who Prescribed this Prescription.
        prescribingDoctorId:
          description: Unique identifier of the user who Prescribed this Prescription.
          type: string
        productId:
          description: Unique identifier representing the related Product entity.
          type: string
        quantity:
          format: double
          description: Quantity amount on the prescription.
          type: number
        refillCount:
          format: int32
          description: Refill count. The amount of times this prescription was refilled.
          type: integer
        refillPrn:
          description: Flag indicating whether this prescription supports PRN refills.
          type: boolean
        refillQuantity:
          format: int32
          description: Total available refill amount.
          type: integer
        soapId:
          description: Unique identifier representing the related SOAP entity.
          type: string
        substitutionPermitted:
          description: Flag indicating whether substitution is permitted for the written prescription product.
          type: boolean
        writtenIsControlled:
          description: Flag indicating whether written product for this prescription is a controlled product.
          type: boolean
        writtenProduct:
          description: Name of the written product, used when flag "IsWritten" is set to true.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    RESTCollectionModelBase_OpenApiPrescriptionController.Prescription:
      type: object
      properties:
        embed:
          type: string
        item:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiPrescriptionController.Prescription'
        page:
          format: int32
          type: integer
        recordsPerPage:
          format: int32
          type: integer
        searchQuery:
          type: string
        sort:
          type: string
        totalRecords:
          format: int32
          type: integer
    OpenApiPrescriptionController.UserInfo:
      description: CoreUser REST model.
      type: object
      properties:
        firstName:
          description: User's First name.
          type: string
        lastName:
          description: User's Last name.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string