Shepherd Veterinary Software Soap Assessment Document API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Soap Assessment Document 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: SoapAssessmentDocument
paths:
  /pav2/open-api-soap-assessment-documents/file-presigned-upload-url:
    post:
      tags:
      - SoapAssessmentDocument
      summary: Generates a presigned upload URL for a SOAP Assessment Document file.
      description: 'Example Request

        {

        "filename": "vaccine-consent.pdf",

        "soapId": "cd9e67e7-dc5e-4e21-8855-b8123456abcd"

        }


        Example Response

        {

        "contentType": "application/pdf",

        "fileName": "vaccine-consent",

        "path": "/PAV2Module/A1b2C3d4Ef5Gh6Ij7Klm8n/OzLIJh67BcXW0098JhZqTg/Assessment/K9uYTcvbX12mkzAsDFqP0t.pdf",

        "url": "example.bucket/MediaVault/PAV2/PAV2Module/A1b2C3d4Ef5Gh6Ij7Klm8n/OzLIJh67BcXW0098JhZqTg/Assessment/"

        }'
      operationId: OpenApiSoapAssessmentDocumentFileGet
      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 presigned upload URL and the path to send to file-entry-write.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.PresignedUrlResponseModel'
            text/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.PresignedUrlResponseModel'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.PresignedUrlResponseModel'
        '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             \"Request model is missing.\" - the request body is missing.\n             \"The request is invalid.\" with modelState - fileName or soapId is missing. modelState names the offending field.\n             \"The request is invalid.\" - fileName contains a character that is not allowed in a file path (a double quote, an angle bracket, a pipe or a control character).\n             \"File name must include a file extension\" - fileName has no extension.\n             \"File extension '{extension}' is not supported. Allowed extensions: {allowed extensions}.\" - the extension of fileName is not an allowed document, image or video extension.\n             \"SoapId is not valid\" - soapId is not a GUID, or is the empty GUID."
        '404':
          description: '"SOAP not found" - soapId does not refer to a SOAP in the caller''s clinic.'
        '409':
          description: '"SOAP is locked" - the SOAP is locked.'
        '500':
          description: '"An unexpected error occurred while processing your request." - the upload URL could not be generated.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.FileUploadPresignedUrlRequestModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.FileUploadPresignedUrlRequestModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.FileUploadPresignedUrlRequestModel'
        required: true
  /pav2/open-api-soap-assessment-documents/file-entry-write:
    post:
      tags:
      - SoapAssessmentDocument
      summary: After a file has been successfully uploaded to the S3 bucket with the generated…
      description: 'Example Request

        {

        "filename": "vaccine-consent",

        "path": "/PAV2Module/XzT9PoF3RqXkLfJuBv7cMa/7glhV98RtZKYe3uNfXpWdr/Assessment/UyTrEwqL92kjHtZcPgVb55.pdf",

        "soapId": "cd9e67e7-dc5e-4e21-8855-b8123456abcd"

        }'
      operationId: OpenApiSoapAssessmentDocumentWrite
      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 created SOAP assessment document file entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel'
            text/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel'
        '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             \"Request model is missing.\" - the request body is missing.\n             \"The request is invalid.\" with modelState - fileName, path or soapId is missing. modelState names the offending field.\n             \"The request is invalid.\" - path contains a character that is not allowed in a file path (a double quote, an angle bracket, a pipe or a control character).\n             \"File name must include a file extension\" - path has no file extension. The uploaded file is deleted from the S3 bucket.\n             \"File extension '{extension}' is not supported. Allowed extensions: {allowed extensions}. Uploaded file has been deleted from the S3 bucket.\" - the extension of path is not an allowed document, image or video extension.\n             \"SoapId is not valid\" - soapId is not a GUID, or is the empty GUID.\n             \"The provided path does not belong to the specified SOAP\" - path does not contain the SOAP's and its clinic's segments, as returned by file-presigned-upload-url for that SOAP.\n             \"Uploaded file exceedes the upload file size limit: {limit}. Uploaded file has been deleted from the S3 bucket.\" - the uploaded file is larger than the configured limit, in bytes."
        '404':
          description: "The response body is one of:\n             \"SOAP not found\" - soapId does not refer to a SOAP in the caller's clinic.\n             \"File upload not found in S3 for path '{path}'.\" - no file was uploaded to the presigned URL for path."
        '409':
          description: "The response body is one of:\n             \"SOAP is locked\" - the SOAP is locked.\n             \"A file with this path is already linked to the target SOAP\" - path has already been linked to this SOAP as an assessment document."
        '500':
          description: '"An unexpected error occurred while processing your request." - the file could not be linked. Examples: path is already linked to the SOAP as an imaging file; fileName is longer than 500 characters; the uploaded file could not be read from S3 for a reason other than it not existing.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel'
        required: true
components:
  schemas:
    OpenApiSoapAssessmentDocumentController.SoapAssessmentDocumentEntryModel:
      description: Soap assessment document file entry write model.
      required:
      - fileName
      - path
      - soapId
      type: object
      properties:
        fileName:
          description: The name of the uploaded file without the file type extension (e.g., "vaccine-consent").
          type: string
        path:
          description: The key generated in the presigned URL response. Required for making the file accessible via the application.
          type: string
        soapId:
          description: The unique identifier of the SOAP for which the file is uploaded.
          type: string
    OpenApiSoapAssessmentDocumentController.PresignedUrlResponseModel:
      description: 'The response model which will return the upload URL for a file upload to the S3 bucket along with the Path and

        FileName which are needed for creating an entry in our database making the uploaded file accessible via the application.'
      type: object
      properties:
        contentType:
          description: The type of the content that will be uploaded to the S3 bucket.
          type: string
        fileName:
          description: The name of the file that will be uploaded.
          type: string
        path:
          description: The key used to link the uploaded file with the database record.
          type: string
        url:
          description: The Presigned upload URL used for direct file upload to the S3 bucket.
          type: string
    OpenApiSoapAssessmentDocumentController.FileUploadPresignedUrlRequestModel:
      description: 'A model containing properties required for the Presigned upload URL generation. Both properties are required in

        order to generate the URL.'
      required:
      - fileName
      - soapId
      type: object
      properties:
        fileName:
          description: The name of the file to be uploaded once the presigned URL is generated. Must include the file type extension (e.g., "vaccine-consent.pdf").
          type: string
        soapId:
          description: The unique identifier of the SOAP under which a file will be uploaded once the presigned URL is generated.
          type: string