Vim Appointments API

openapi: 3.2.0
info:
  title: Vim REST Appointments API
  version: 1.0.0
  description: 'The Vim REST API allows you to access various resources and services provided by Vim.

    The API is based on the OAuth 2.0 protocol and uses the client credentials grant type for authentication.

    Before calling any authenticated resource request, you must obtain an access token by calling the [Obtain access token](#post-token-obtain-an-access-token) endpoint.


    **Note**: The Vim API is only available for USA server-based instances. This means your application server must be hosted within the United States to access Vim''s EHR connectivity features. If you are a developer accessing from outside of the US, you need to use a VPN to connect, but your app server must still be in the US for production use.


    These docs are interactive, so you can change the request parameters and see the response in real-time. Try it out!'
servers:
- url: https://api.getvim.com/v1
tags:
- name: Appointments
paths:
  /appointments/{vimOrganizationId}:
    get:
      parameters:
      - name: vimOrganizationId
        in: path
        description: The Vim unique identifier for the organization. Vim constrains the available information; Vim shares information from organizations where your application is installed.
        required: true
        schema:
          type: string
        example: '123456789'
      - name: offset
        in: query
        required: false
        description: The starting point of the data to retrieve. Default is 0.
        schema:
          type: integer
          example: 0
      - name: limit
        in: query
        required: false
        description: The number of records to retrieve. Default is 50, with a maximum value of 50.
        schema:
          type: integer
          example: 50
      operationId: getFutureAppointments
      security:
      - Access token: []
      tags:
      - Appointments
      summary: Get future appointments data
      description: 'Appointments public api enables Canvas''s app developers to get the clinic NPI''s future appointments as a back end API request.

        The endpoint returns scheduled appointments for the upcoming 10 days for Authorized Users within the customer organization which have your application installed.

        For authorization, you must use the token obtained from the [Obtain access token](#post-oauth-token) endpoint.<p><b>Rate limit:</b> You can send up to 50 requests per minute.<p><b>Pagination:</b> The API supports offset-based pagination to handle large datasets efficiently. The following parameters control pagination:</p><ul><li><b>offset</b> (optional): The starting point of the data to retrieve. Default is 0.</li><li><b>limit</b> (optional): The number of records to retrieve. Default is 50, with a maximum value of 50.</li></ul><p>This allows you to retrieve subsets of data in sequential requests. For example:</p><ul><li><code>offset=0&limit=50</code> retrieves the first 50 records.</li><li><code>offset=50&limit=50</code> retrieves the next 50 records.</li></ul></p><p>Vim allows developers to test the API without accessing live data. By using <code>vimOrganizationId = 123456789</code> in the API parameter, developers receive a predefined JSON response that simulates real appointment data but with de-identified data. Please note that you have to be authorized to use the service.</p><h3>How This API Works</h3><p>This API is <b>not</b> a real-time backend-to-backend EHR integration. It is a <b>daily snapshot</b> system — Vim syncs appointment data from the EHR once per day, and this endpoint serves that latest snapshot.</p><p><b>Daily sync flow:</b></p><ol><li>Once per day, Vim syncs appointments from the EHR for each provider with an NPI, covering the next 10 days.</li><li>The data is stored in Vim''s backend.</li><li>This endpoint returns that stored snapshot — it does not query the EHR in real time.</li></ol><p><b>Supported EHRs:</b> ECW, Athena, and Sandbox EHR (for testing).</p><p><b>Key constraints:</b></p><ul><li><b>Not real-time:</b> Data is synced once daily. Expect up to a 24-hour lag for new appointments.</li><li><b>NPI required:</b> Only physicians with an NPI set in the EHR are included in the sync.</li><li><b>App must be initialized:</b> The app authentication flow must be completed for that user before any data is synced for them.</li><li><b>Physician must be logged in:</b> Vim Connect must be active during the daily sync window for that provider''s data to be extracted.</li><li><b>Appointment timing matters:</b> Appointments added to the EHR after the daily sync has run won''t appear until the following day.</li><li><b>Lookahead window:</b> Only the next 10 days of appointments are available.</li></ul>'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        identifiers:
                          type: object
                          required:
                          - vimAppointmentId
                          properties:
                            vimAppointmentId:
                              type: string
                              description: The Vim unique identifier for the appointment
                              example: 550e8400-e29b-41d4-a716-446655440000
                            ehrAppointmentId:
                              type: string
                              description: The EHR unique identifier for the appointment
                              example: AP-20240315-0001
                        basicInformation:
                          type: object
                          properties:
                            status:
                              type: string
                              description: The current status of the appointment (e.g., confirmed, canceled)
                              example: confirmed
                            type:
                              type: string
                              description: The type of appointment (e.g., Annual, follow-up)
                              example: routine_checkup
                            facility:
                              type: object
                              properties:
                                facilityEhrId:
                                  type: string
                                  description: The EHR unique identifier of the medical facility
                                  example: MIAMI_SPORTS_MED
                                name:
                                  type: string
                                  description: The name of the medical facility where the appointment will take place
                                  example: Miami Sports Medicine Center
                            time:
                              type: object
                              required:
                              - startTime
                              - endTime
                              - timeZone
                              properties:
                                startTime:
                                  type: string
                                  description: Any additional notes or comments made by the provider or staff
                                  format: YYYY-MM-DD HH:MM:SS
                                  example: '2023-03-15 09:00:00'
                                endTime:
                                  type: string
                                  description: The scheduled end time of the appointment
                                  format: YYYY-MM-DD HH:MM:SS
                                  example: '2023-03-15 09:30:00'
                                timeZone:
                                  type: string
                                  description: The time zone in which the startTime and endTime
                                  example: UTC
                        patient:
                          type: object
                          properties:
                            identifiers:
                              type: object
                              required:
                              - vimPatientId
                              properties:
                                vimPatientId:
                                  type: string
                                  description: The Vim unique identifier for the patient
                                  example: ab123456-c789-d22342432-d3482e9fb436
                                ehrPatientId:
                                  type: string
                                  description: "The EHR unique identifier for the patient. \n This field also represents the MRN (Medical Record Number) on the EHR"
                                  example: EHR1-1A2B
                                mrn:
                                  type: string
                                  description: The patient medical record number
                                  example: MED-2023-54321
                            demographics:
                              type: object
                              required:
                              - firstName
                              - lastName
                              - dateOfBirth
                              properties:
                                firstName:
                                  type: string
                                  description: The patient's primary given name
                                  example: Michael
                                lastName:
                                  type: string
                                  description: The patient's surname
                                  example: Johnson
                                middleName:
                                  type: string
                                  description: Additional given names
                                  example: Robert
                                dateOfBirth:
                                  type: string
                                  description: The patient's date of birth
                                  format: YYYY-MM-DD
                                  example: '1987-06-24'
                                gender:
                                  type: string
                                  description: The patient's gender
                                  example: male
                            address:
                              type: object
                              properties:
                                address1:
                                  type: string
                                  description: The patient's first address
                                  example: 1234 Sunshine Boulevard
                                address2:
                                  type: string
                                  description: The patient's second address
                                  example: Suite 1
                                city:
                                  type: string
                                  description: The city where the patient's is located
                                  example: Miami
                                state:
                                  type: string
                                  description: The patient's state
                                  example: FL
                                zipCode:
                                  type: string
                                  description: The patient's zip code
                                  example: '33101'
                                fullAddress:
                                  type: string
                                  description: The complete address in one string
                                  example: 1234 Sunshine Boulevard, Suite 1, Miami, FL 33101
                            insurance:
                              type: object
                              properties:
                                ehrInsurance:
                                  type: string
                                  description: 'The insurance information as represented in the EHR that may include the plan name, the insurer (payer) name and/or a combination of both.

                                    The exact format and content may vary depending on the EHR and implementation'
                                  example: Vim Choice Plus Gold - Sunrise Health Insurance
                                groupId:
                                  type: string
                                  description: The insurance group/employer plan identifier
                                  example: GRP-982341
                                payerId:
                                  type: string
                                  description: The unique identifier for the insurance payer
                                  example: '12345'
                                memberId:
                                  type: string
                                  description: The patient's member/subscriber identifier
                                  example: M123456789
                        appointmentProvider:
                          type: object
                          required:
                          - npi
                          properties:
                            npi:
                              type: string
                              description: The provider's National Provider Identifier (NPI)
                              format: 10 digit number
                              example: '1234567890'
                            ehrProviderId:
                              type: string
                              description: The provider unique id in the EHR
                              example: EHRPID-123
                            demographics:
                              type: object
                              required:
                              - firstName
                              - lastName
                              properties:
                                firstName:
                                  type: string
                                  description: The first name of the provider (e.g., 'Kristel')
                                  example: Sarah
                                lastName:
                                  type: string
                                  description: The last name of the provider (e.g., 'De Varona')
                                  example: Williams
                                middleName:
                                  type: string
                                  description: The middle name of the provider (if applicable)
                                  example: John
                            facility:
                              type: object
                              properties:
                                facilityEhrId:
                                  type: string
                                  description: The unique identifier of the facility in the EHR system
                                  example: MIAMI_HEALTH_CLINIC
                                name:
                                  type: string
                                  description: The name of the facility where the provider works
                                  example: Miami Health Clinic
                                address:
                                  type: object
                                  properties:
                                    address1:
                                      type: string
                                      description: The facility's first address
                                      example: 5678 Medical Drive
                                    address2:
                                      type: string
                                      description: The facility's second address
                                      example: Suite 2
                                    city:
                                      type: string
                                      description: The city where the facility is located
                                      example: Miami
                                    state:
                                      type: string
                                      description: The state where the facility is located
                                      example: FL
                                    zipCode:
                                      type: string
                                      description: The facility's zip code
                                      example: '33102'
                                    fullAddress:
                                      type: string
                                      description: The complete address in one string
                                      example: 5678 Medical Drive, Suite 2, Miami, FL 33102
                                contact_info:
                                  type: object
                                  properties:
                                    homePhoneNumber:
                                      type: string
                                      description: The facility's home phone number
                                      example: 305-888-8888
                                    faxNumber:
                                      type: string
                                      description: The facility's fax number
                                      example: 305-888-7777
                                    mobilePhoneNumber:
                                      type: string
                                      description: The facility's mobile phone number
                                      example: 305-888-9999
                                    email:
                                      type: string
                                      description: The facility's email address
                                      example: contact@miamiclinic.com
                            specialty:
                              type: array
                              items:
                                type: string
                              description: A list of the provider's specialties
                              format: e.g., 'Cardiology', 'Pediatrics'
                              example:
                              - Family Medicine
                            providerDegree:
                              type: string
                              description: The provider's degree
                              format: e.g., 'MD', 'DO', 'PhD'
                              example: MD
                  meta:
                    type: object
                    properties:
                      currentOffset:
                        type: integer
                        description: The current offset of the data retrieval
                        example: 0
                      nextOffset:
                        type: integer
                        required: false
                        description: The next offset for data retrieval, if more data exists
                        example: 50
                      limit:
                        type: integer
                        description: The maximum number of records retrieved
                        example: 50
                      isFinished:
                        type: boolean
                        description: Indicates whether all data has been retrieved
                        example: true
                    required:
                    - currentOffset
                    - limit
                    - isFinished
        '400':
          description: Bad request. Occurs when the provided organizationId is not in the correct format
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 400
                  error:
                    type: string
                    description: Bad Request
                  message:
                    type: string
                    description: Invalid vimOrganizationId, should be a number
        '403':
          description: 'Forbidden: Insufficient permissions to perform this action'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 403
                  error:
                    type: string
                    description: FORBIDDEN
                  message:
                    type: string
                    description: Forbidden resource
        '429':
          description: 'Rate limit exceeded: Too many requests'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                  error:
                    type: string
                    description: TOO_MANY_REQUESTS
                  message:
                    type: string
                    description: 'Rate limit exceeded: Too many requests'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 500
                  error:
                    type: string
                    description: INTERNAL_SERVER_ERROR
                  message:
                    type: string
                    description: Unexpected error occurred on the server
components:
  securitySchemes:
    Access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use this token in the Authorization header when calling any authenticated resource request