Shepherd Veterinary Software Appointment Note API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Appointment Note 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: AppointmentNote
paths:
  /pav2/open-api-appointment-notes/write:
    post:
      tags:
      - AppointmentNote
      summary: Inserts a new {OpenApiAppointmentNoteController.AppointmentNote}
      description: 'Example Request

        {

        "appointmentId" : "1d5787f5-ca0c-40a5-863c-b348008e776b",

        "note" : "Potential 15 minutes delay"

        }


        Example Response

        {

        "appointmentId": "1d5787f5-ca0c-40a5-863c-b348008e776b",

        "createdByUser": null,

        "createdByUserId": "8af89d24-588d-4e77-b5d2-b32f00b596dc",

        "editedByUser": null,

        "editedByUserId": null,

        "note" : "Potential <b>15 minutes</b> delay"

        "pav2User": null,

        "taggedTeamsIds": null,

        "taggedUsersIds": null,

        "dateCreated": "2025-09-18T12:53:26.8083725Z",

        "dateUpdated": "2025-09-18T12:53:26.8083725Z",

        "id": "18ea8f0c-1654-43e4-ad27-b35c0110a888"

        }'
      operationId: OpenApiAppointmentNotePost
      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 appointment note.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiAppointmentNoteController.AppointmentNote'
            text/json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiAppointmentNoteController.AppointmentNote'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RESTCollectionModelBase_OpenApiAppointmentNoteController.AppointmentNote'
        '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 was rejected. One of:\n             AppointmentId is missing. - appointmentId was not supplied or was an empty uuid.\n             Note is missing. - note was not supplied or contained only whitespace.\n             The request body was missing or could not be read into the model. The response body is empty.\n             The appointment note could not be stored. The response body is empty.\n             The provided AppointmentId does not belong to the clinic. - appointmentId does not resolve to an appointment in the caller's clinic."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiAppointmentNoteController.AppointmentNoteWriteModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiAppointmentNoteController.AppointmentNoteWriteModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiAppointmentNoteController.AppointmentNoteWriteModel'
        description: The model.
        required: true
components:
  schemas:
    RESTCollectionModelBase_OpenApiAppointmentNoteController.AppointmentNote:
      type: object
      properties:
        embed:
          type: string
        item:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiAppointmentNoteController.AppointmentNote'
        page:
          format: int32
          type: integer
        recordsPerPage:
          format: int32
          type: integer
        searchQuery:
          type: string
        sort:
          type: string
        totalRecords:
          format: int32
          type: integer
    OpenApiAppointmentNoteController.AdditionalUserInfo:
      description: REST model representing the additional User info.
      type: object
      properties:
        isDoctor:
          description: Flag indicating whether this user is doctor.
          type: boolean
        prefix:
          description: User's assigned prefix (e.g., "Dr.", "Mr.", "Mrs.").
          type: string
        suffix:
          description: User's assigned suffix (e.g., "MD", "PhD", "Jr.").
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiAppointmentNoteController.CreatedByUser:
      description: REST model representing the info of the User who created this note.
      type: object
      properties:
        firstName:
          description: The user's first name.
          type: string
        lastName:
          description: The user's last name.
          type: string
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string
    OpenApiAppointmentNoteController.AppointmentNoteWriteModel:
      description: Request model for writing a new appointment note.
      type: object
      properties:
        appointmentId:
          description: Unique identifier representing the Appointment for which is this note inserted.
          type: string
        note:
          description: Free-text content of the note.
          type: string
    OpenApiAppointmentNoteController.AppointmentNote:
      description: REST model representing the User who created this note.
      type: object
      properties:
        additionalUserInfo:
          $ref: '#/components/schemas/OpenApiAppointmentNoteController.AdditionalUserInfo'
          description: Object representing the additional user info of related User entity.
        appointmentId:
          format: uuid
          description: Unique identifier representing the appointment this note belongs to.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        createdByUser:
          $ref: '#/components/schemas/OpenApiAppointmentNoteController.CreatedByUser'
          description: Object representing the additional info of user who created this appointment note.
        createdByUserId:
          format: uuid
          description: Unique identifier representing the user who created this appointment note.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        editedByUser:
          $ref: '#/components/schemas/OpenApiAppointmentNoteController.CreatedByUser'
          description: Object representing the additional info of user who edited this appointment note.
        editedByUserId:
          format: uuid
          description: Unique identifier representing the user who edited this appointment note.
          type: string
          example: 00000000-0000-0000-0000-000000000000
        note:
          description: Free-text content of the note.
          type: string
        taggedTeamsIds:
          description: List of tagged team identifiers associated with this note.
          type: array
          items:
            format: uuid
            type: string
            example: 00000000-0000-0000-0000-000000000000
        taggedUsersIds:
          description: List of tagged user identifiers associated with this note.
          type: array
          items:
            format: uuid
            type: string
            example: 00000000-0000-0000-0000-000000000000
        dateCreated:
          format: date-time
          type: string
        dateUpdated:
          format: date-time
          type: string
        id:
          type: string