Shepherd Veterinary Software Provider Availability API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Provider Availability 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: ProviderAvailability
paths:
  /pav2/open-api-provider-availabilities:
    post:
      tags:
      - ProviderAvailability
      summary: Retrieves {OpenApiProviderAvailabilityController.ProviderAvailability} resource…
      description: 'Example Request

        {

        "rpp": 1

        }


        Example Response

        {

        "embed": null,

        "item": [

        {

        "createdByUser": null,

        "createdByUserId": "ab12cd34-ef56-7890-ab12-cd34ef567890",

        "endDate": "2025-08-04T10:00:00Z",

        "extraAvailabilityType": null,

        "extraAvailabilityTypeId": null,

        "isMultiple": false,

        "isStandardBreakType": null,

        "providerAvailabilityBreaks": [],

        "providerId": "12345678-90ab-cdef-1234-567890abcdef",

        "routineAvailabilityType": null,

        "routineAvailabilityTypeId": "9f8e7d6c-5b4a-3210-9f8e-7d6c5b4a3210",

        "startDate": "2025-08-03T22:00:00Z",

        "validFromDate": "2025-08-04T09:42:22.886697Z",

        "validToDate": null,

        "dateCreated": "2025-08-04T09:42:22.984688Z",

        "dateUpdated": "2025-08-04T09:42:22.984688Z",

        "id": "fedcba98-7654-3210-fedc-ba9876543210"

        }

        ],

        "links": [],

        "page": 1,

        "recordsPerPage": 1,

        "searchQuery": null,

        "sort": null,

        "totalRecords": 8

        }'
      operationId: OpenApiProviderAvailabilityGet
      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 provider availabilities matching the supplied filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiProviderAvailabilityController.ProviderAvailability'
            text/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiProviderAvailabilityController.ProviderAvailability'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiProviderAvailabilityController.ProviderAvailability'
        '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: 'The date range is invalid: date.dateMin is after date.dateMax, or an overlappingDatesToCheck entry has dateMin after dateMax. The body is the message "Invalid date range: DateMin must be earlier than DateMax."'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityFilterModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityFilterModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityFilterModel'
        description: The model.
        required: true
  /pav2/open-api-provider-availabilities/timeslots:
    post:
      tags:
      - ProviderAvailability
      summary: Retrieves the provider availability times that match the specified filter…
      description: 'Example Request

        {

        "endDate": "2025-08-05T09:35:40.000Z",

        "startDate": "2025-08-03T09:10:30.000Z"

        }


        Example Response

        {

        "item": [

        {

        "available": [

        {

        "max": "2025-08-05T09:35:40Z",

        "min": "2025-08-04T22:00:00Z"

        }

        ],

        "break": [],

        "clinicBreak": [],

        "end": [

        {

        "max": null,

        "min": "2025-08-05T10:00:00Z"

        }

        ],

        "officeClosure": [],

        "providerId": "a1b2c3d4-e5f6-7890-ab12-c3d4e5f67890",

        "unavailable": [

        {

        "max": "2025-08-04T00:00:00Z",

        "min": "2025-08-03T22:00:00Z"

        }

        ]

        }

        ]

        }'
      operationId: ProviderGetAvailabilityTimeslots
      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: The provider time slots for the requested date range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderTimeSlotAvailabilityRESTModel'
            text/json:
              schema:
                $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderTimeSlotAvailabilityRESTModel'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderTimeSlotAvailabilityRESTModel'
        '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: '"The request is invalid." with modelState - startDate or endDate is missing or not a valid date; the entry names the field.

            "The request is invalid." without modelState - the two dates span more than 30 days. A span of exactly 30 days is accepted.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityTimeSlotFilterModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityTimeSlotFilterModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityTimeSlotFilterModel'
        required: true
components:
  schemas:
    OpenApiProviderAvailabilityController.ProviderAvailabilityTimeSlotFilterModel:
      description: ProviderAvailabilityTimeSlotFilterModel class
      required:
      - endDate
      - startDate
      type: object
      properties:
        endDate:
          format: date-time
          description: The end of the date range filter.
          type: string
        filterActiveAppointments:
          description: Flag filtering by FilterActiveAppointments status. If set to true, Canceled and Deleted appointments will not be returned.
          type: boolean
        providerIds:
          description: Comma-separated list of provider identifiers to filter on. If not provided, all providers are returned.
          type: string
        startDate:
          format: date-time
          description: The start of the date range filter.
          type: string
    OpenApiProviderAvailabilityController.ProviderTimeSlotAvailabilityItemRESTModel:
      description: ProviderTimeSlotAvailability item REST model.
      type: object
      properties:
        available:
          description: List of Time slots in which Provider is available.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.TimeSlotRange'
        break:
          description: List of Time slots in which Provider has break.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.TimeSlotRange'
        clinicBreak:
          description: List of Time slots in which Clinic has break.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.TimeSlotRange'
        end:
          description: List of The end time slot.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.TimeSlotRange'
        officeClosure:
          description: List of Time slots of the office closure.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.TimeSlotRange'
        providerId:
          format: uuid
          description: Unique identifier representing the related provider entity.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        unavailable:
          description: List of Time slots in which provider is unavailable.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.TimeSlotRange'
    OpenApiProviderAvailabilityController.DateTimeRangeValues:
      description: DateTimeRangeValues class
      required:
      - dateMax
      - dateMin
      type: object
      properties:
        dateMax:
          format: date-time
          description: The maximum DateTime value used to filter overlapping ProviderAvailabilities.
          type: string
        dateMin:
          format: date-time
          description: The minimum DateTime value used to filter overlapping ProviderAvailabilities.
          type: string
    OpenApiProviderAvailabilityController.ProviderTimeSlotAvailabilityRESTModel:
      description: ProviderTimeSlotAvailability REST model.
      type: object
      properties:
        item:
          description: The list of time slots for providers.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderTimeSlotAvailabilityItemRESTModel'
    OpenApiProviderAvailabilityController.TimeSlotRange:
      description: TimeSlotRange REST model.
      type: object
      properties:
        max:
          format: date-time
          description: The end of the time slot.
          type: string
        min:
          format: date-time
          description: The start of the time slot.
          type: string
    OpenApiProviderAvailabilityController.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
    RESTCollectionModelBase_OpenApiProviderAvailabilityController.ProviderAvailability:
      type: object
      properties:
        embed:
          type: string
        item:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailability'
        page:
          format: int32
          type: integer
        recordsPerPage:
          format: int32
          type: integer
        searchQuery:
          type: string
        sort:
          type: string
        totalRecords:
          format: int32
          type: integer
    OpenApiProviderAvailabilityController.ExtraAvailabilityType:
      description: ExtraAvailabilityType REST model.
      type: object
      properties:
        abrv:
          description: Short unique identifier for the lookup.
          type: string
        description:
          description: The description of the lookup entry.
          type: string
        name:
          description: The name of the lookup entry.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiProviderAvailabilityController.ProviderAvailabilityBreak:
      description: ProviderAvailabilityBreak REST model.
      type: object
      properties:
        endDate:
          format: date-time
          description: Date when the Provider availability break is set to end.
          type: string
        providerAvailabilityId:
          description: Unique identifier representing the related Provider availability entity.
          type: string
        startDate:
          format: date-time
          description: Date when the Provider availability break is set to start.
          type: string
        validFromDate:
          format: date-time
          description: This date marks date from which this provider availability break is valid.
          type: string
        validToDate:
          format: date-time
          description: This date marks date to which this provider availability break is valid.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiProviderAvailabilityController.ProviderAvailabilityFilterModel:
      description: ProviderAvailability Filter REST model.
      type: object
      properties:
        date:
          $ref: '#/components/schemas/OpenApiProviderAvailabilityController.DateTimeRangeValues'
          description: Object representing the Date value used to filter out existing provider availabilities that fall within the specified date range. This filter applies only to ExtraAvailabilities; routine ProviderAvailabilities will be fetched without filtering.
        extraAvailabilityTypeIds:
          description: List of GUIDs used to filter by ExtraAvailabilityTypeId.
          type: string
        ignoreExtraAvailabilities:
          description: Boolean value that determines whether to exclude ExtraAvailabilities. If true, they are excluded; if false, they are included.
          type: boolean
        isRoutine:
          description: Boolean value used to filter ProviderAvailabilities. If true, only routine availabilities are included; if false, only non-routine availabilities are retrieved.
          type: boolean
        overlappingDatesToCheck:
          description: List of DateTime values used to filter out overlapping ProviderAvailabilities within the specified date ranges.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.DateTimeRangeValues'
        providerIds:
          description: Comma-separated list of provider identifiers.
          type: string
        searchQuery:
          description: Filters by name.
          type: string
        showPastAdditionalAvailabilitiesAndUnavailabilities:
          description: Boolean value that determines whether to include past additional availabilities and unavailabilities. If true, they are included; if false, they are excluded.
          type: boolean
        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
    OpenApiProviderAvailabilityController.RoutineAvailabilityType:
      description: RoutineAvailabilityType REST model.
      type: object
      properties:
        abrv:
          description: Short unique identifier for the lookup.
          type: string
        description:
          description: The description of the lookup entry.
          type: string
        name:
          description: The name of the lookup entry.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiProviderAvailabilityController.ProviderAvailability:
      description: ProviderAvailability REST model.
      type: object
      properties:
        createdByUser:
          $ref: '#/components/schemas/OpenApiProviderAvailabilityController.UserInfo'
          description: Object representing the related UserInfo entity.
        createdByUserId:
          description: Unique identifier representing the User.
          type: string
        endDate:
          format: date-time
          description: Date when the Provider availability is set to end.
          type: string
        extraAvailabilityType:
          $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ExtraAvailabilityType'
          description: 'Object representing the Type of the extra availability. If abrv is b then it is office closure, if abrv is

            s then it is additional availability.'
        extraAvailabilityTypeId:
          description: Unique identifier representing the related Extra availability type entity.
          type: string
        isMultiple:
          description: Flag indicating whether this ProviderAvailabilty is applied for multiple days.
          type: boolean
        isStandardBreakType:
          description: 'A flag indicating whether this ProviderAvailability has a standard or custom type of break.

            When true, a Standard Break is applied - the same break time is used consistently for a specific day of the week (e.g., every Monday).

            When false, a Custom Break is applied - different break times can be set for each date within the additional availability range (e.g., different break times for two separate Mondays).

            When null, no break is defined for the additional availability. This parameter applies only to additional availabilities and does not reflect regular office hour breaks.'
          type: boolean
        providerAvailabilityBreaks:
          description: List of objects representing the related Provider availability break entity.
          type: array
          items:
            $ref: '#/components/schemas/OpenApiProviderAvailabilityController.ProviderAvailabilityBreak'
        providerId:
          description: 'Unique identifier representing the related Provider entity. When the provider identifier ProviderId is null it will show clinic

            availability or office closures. Clinic availability will be set in routine availabilities. Office

            closures will be set in extra availabilities.'
          type: string
        routineAvailabilityType:
          $ref: '#/components/schemas/OpenApiProviderAvailabilityController.RoutineAvailabilityType'
          description: Object representing the related Type of the routine availability entity.
        routineAvailabilityTypeId:
          description: Unique identifier representing the related Routine availability type entity.
          type: string
        startDate:
          format: date-time
          description: Date when the Provider availability is set to start.
          type: string
        validFromDate:
          format: date-time
          description: This date marks date from which this provider availability is valid.
          type: string
        validToDate:
          format: date-time
          description: This date marks date to which this provider availability is valid.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string