Shepherd Veterinary Software Appointment Patient API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Appointment Patient 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: AppointmentPatient
paths:
  /pav2/open-api-appointment-patient:
    post:
      tags:
      - AppointmentPatient
      summary: Retrieves {OpenApiAppointmentPatientController.AppointmentPatient} resources…
      description: 'Example Request

        {

        "appointemntIds" : "b3e9fd15-0abc-4916-ab8e-b2e901023da7",

        "embed" : "patient,appointment"

        }


        Example Response

        {

        "embed": "patient,appointment",

        "item": [

        {

        "appointment": {

        "appointmentStatusId": "34fd7b72-2e9d-4db6-8a8e-b2f901bb6d98",

        "appointmentTypeId": "f0c9a7e4-8d56-4f7e-877b-b2f901bb7081",

        "clientId": "5a1d6fa2-7b6b-4264-a1f3-b2f901bb7234",

        "clinicId": "5fa03907-c437-4a56-8cd6-b2bb00ac4232",

        "createdByUserId": "7cb1040f-980b-42f3-b915-b2f901bb74c2",

        "endDate": "2025-06-10T10:30:00Z",

        "isDeleted": false,

        "providerId": "a22f5fcd-c85e-49f3-a2a2-b2f901bb7673",

        "recurringConfigurationId": null,

        "sendEmailNotification": true,

        "sendSmsNotification": false,

        "startDate": "2025-06-10T09:45:00Z",

        "visitReason": "Annual vaccination and check-up",

        "dateCreated": "2025-06-08T14:20:31.117Z",

        "dateUpdated": "2025-06-08T14:21:05.983Z",

        "id": "b3e9fd15-0abc-4916-ab8e-b2e901023da7"

        },

        "appointmentId": "b3e9fd15-0abc-4916-ab8e-b2e901023da7",

        "ignorePatient": false,

        "patient": {

        "additionalText": "Allergic to penicillin.",

        "alerts": "Requires muzzle during exams.",

        "breedId": "1d4c89b3-3bdf-4db2-9e4e-1b6e153b89a3",

        "color": "Golden",

        "dateDeceased": null,

        "dateOfBirth": "2017-11-12T00:00:00Z",

        "deleted": false,

        "homeClinicId": "5fa03907-c437-4a56-8cd6-b2bb00ac4232",

        "identifier": "4H2K9XP",

        "legacyId": "CL-19745",

        "microchipNumber": "191000001234567",

        "name": "Max",

        "patientCPRStatusNote": null,

        "patientCprstatusId": null,

        "rabiesTag": "RT2023-884",

        "sexId": "92d6532b-d8cb-4420-b109-d39282aa3149",

        "statusId": "8d3a1211-66e5-4e5b-a2ee-61c3e764b10d",

        "dateCreated": "2023-03-18T10:43:19.123Z",

        "dateUpdated": "2024-06-02T08:59:11.784Z",

        "id": "f5a53df1-5fbd-4e3f-9c0a-b2f901bb78f2"

        },

        "patientId": "f5a53df1-5fbd-4e3f-9c0a-b2f901bb78f2",

        "soap": null,

        "soapId": null,

        "dateCreated": "2025-06-08T14:21:05.984Z",

        "dateUpdated": "2025-06-08T14:21:05.984Z",

        "id": "93a49fbd-88de-4661-a54a-b2f901bb7984"

        }

        ]

        }'
      operationId: OpenApiAppointmentPatientGet
      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 appointment patients matching the supplied filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiAppointmentPatientController.AppointmentPatient'
            text/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiAppointmentPatientController.AppointmentPatient'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiAppointmentPatientController.AppointmentPatient'
        '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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiAppointmentPatientController.AppointmentPatientFilterModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiAppointmentPatientController.AppointmentPatientFilterModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiAppointmentPatientController.AppointmentPatientFilterModel'
        required: true
components:
  schemas:
    OpenApiAppointmentPatientController.Appointment:
      description: Appointment REST model.
      type: object
      properties:
        appointmentStatusId:
          description: Unique identifier representing the related AppointmentStatus entity.
          type: string
        appointmentTypeId:
          description: 'Unique identifier representing the related AppointmentStatus entity, if the appointment type identifier is null then the appointment is a

            block off appointment for the provider.'
          type: string
        clientId:
          description: Unique identifier representing the related Client entity
          type: string
        clinicId:
          description: Unique identifier representing the related Clinic entity.
          type: string
        createdByUserId:
          description: Unique identifier representing the user who created the appointment.
          type: string
        endDate:
          format: date-time
          description: Appointments end date and time.
          type: string
        isDeleted:
          description: Value indicating whether this appointment is deleted.
          type: boolean
        providerId:
          description: Unique identifier representing the related Provider entity.
          type: string
        recurringConfigurationId:
          description: Recurring configuration identifier, only exists for recurring appointments.
          type: string
        sendEmailNotification:
          description: Value indicating whether this appointment sends email notifications.
          type: boolean
        sendSmsNotification:
          description: Value indicating whether this appointment sends SMS notifications.
          type: boolean
        startDate:
          format: date-time
          description: Appointment's start date and time.
          type: string
        visitReason:
          description: Optional free-text field indicating visit reason for appointment.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiAppointmentPatientController.Soap:
      description: Soap REST model.
      type: object
      properties:
        clinicId:
          description: Unique identifier representing the related Clinic entity.
          type: string
        createdByUserId:
          description: Unique identifier representing the user who created this SOAP entry
          type: string
        dateCheckedIn:
          format: date-time
          description: Date and time when the patient was checked in.
          type: string
        dateDeleted:
          format: date-time
          description: Date and time when the SOAP was deleted.
          type: string
        deleted:
          description: Value indicating whether this soap is deleted.
          type: boolean
        invoiceId:
          description: Unique identifier representing the invoice associated with this SOAP.
          type: string
        locationId:
          description: Unique identifier representing the Soap location.
          type: string
        patientId:
          description: Unique identifier representing the patient to whom this SOAP belongs.
          type: string
        soapStatusId:
          description: Unique identifier representing the related SoapStatus entity.
          type: string
        supervisingDoctorId:
          description: Unique identifier representing the related SupervisingDoctor entity.
          type: string
        title:
          description: Soap title.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiAppointmentPatientController.Patient:
      description: Patient REST model.
      type: object
      properties:
        additionalText:
          description: Optional free-text field for internal notes or additional information about the patient.
          type: string
        alerts:
          description: Important info for the patient, e.g. "Difficult to work with"
          type: string
        breedId:
          description: Identifier representing the patient's breed.
          type: string
        color:
          description: Field representing patient color or marking (e.g., "Brown")
          type: string
        dateDeceased:
          format: date-time
          description: Date when the patient was marked as deceased.
          type: string
        dateOfBirth:
          format: date-time
          description: Birth date of the patient.
          type: string
        deleted:
          description: Value indicating whether patient is deleted.
          type: boolean
        homeClinicId:
          description: Identifier of the home clinic associated with the patient.
          type: string
        identifier:
          description: Clinic-specific short identifier used to reference the patient.
          type: string
        legacyId:
          description: Legacy identifier for the patient, used if patient was migrated from an other system.
          type: string
        microchipNumber:
          description: Microchip number assigned to the patient.
          type: string
        name:
          description: Patient's name.
          type: string
        patientCPRStatusNote:
          description: Notes or additional instructions related to the patients CPR status.
          type: string
        patientCprstatusId:
          description: Unique identifier representing the patient's CPR status.
          type: string
        rabiesTag:
          description: Rabies tag number assigned to the patient.
          type: string
        sexId:
          description: Unique identifier representing the patient's sex..
          type: string
        statusId:
          description: Unique identifier representing the patient's current status.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    RESTCollectionModelBase_OpenApiAppointmentPatientController.AppointmentPatient:
      type: object
      properties:
        embed:
          type: string
        item:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiAppointmentPatientController.AppointmentPatient'
        page:
          format: int32
          type: integer
        recordsPerPage:
          format: int32
          type: integer
        searchQuery:
          type: string
        sort:
          type: string
        totalRecords:
          format: int32
          type: integer
    OpenApiAppointmentPatientController.AppointmentPatient:
      description: Appointment Patient REST model
      type: object
      properties:
        appointment:
          $ref: '#/components/schemas/OpenApiAppointmentPatientController.Appointment'
          description: Object representing the related Appointemnt entity.
        appointmentId:
          format: uuid
          description: Unique identifier representing the related Appointment entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        ignorePatient:
          description: A value indicating whether a client and/or a patient is inactive and therefore should be ignored.
          type: boolean
        patient:
          $ref: '#/components/schemas/OpenApiAppointmentPatientController.Patient'
          description: Object representing the related Patient entity.
        patientId:
          format: uuid
          description: Unique identifier representing the related Patient entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        soap:
          $ref: '#/components/schemas/OpenApiAppointmentPatientController.Soap'
          description: Object representing the related Soap entity.
        soapId:
          format: uuid
          description: Unique identifier representing the Soap entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiAppointmentPatientController.AppointmentPatientFilterModel:
      description: Appointment Patient Filter model.
      type: object
      properties:
        appointmentIds:
          description: Filters by Comma-separated list of unique appointment identifiers.
          type: string
        clinicIds:
          description: Comma-separated list of Clinic identifiers. Defaults to null. The filter is applicable only if the group to which the clinic belongs shares clients and patients.
          type: string
        ignorePatient:
          description: Filters by Ignore patient status. Defaults to null (fetches all entities no matter IgnorePatient status).
          type: boolean
        includePatientHomeClinic:
          description: "Used to support multi-site practices that share patients and clients.\nDetermines whether to include Appointment patients from a patient's home clinic\nwhen filtering by clinic.\n            \nBehavior:\n- If true:\n  - Includes Appointment patients from the specified clinic (default)\n  - Also includes appointment patients from other clinics where the patient's home clinic\n    matches the specified clinic\n- If false (default):\n  - Only includes Appointment patients 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: Filters by Comma-separated list of unique patient identifiers.
          type: string
        soapIds:
          description: 'Filters SOAP entries by their unique identifiers. Results are only returned for SOAPs created on the

            appointment page; those created on the SOAP page return null.'
          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