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.Rate limit: You can send up to 50 requests per minute.
Pagination: The API supports offset-based pagination to handle large datasets efficiently. The following parameters control pagination:
- offset (optional): The starting point of the data to retrieve. Default is 0.
- limit (optional): The number of records to retrieve. Default is 50, with a maximum value of 50.
This allows you to retrieve subsets of data in sequential requests. For example:
offset=0&limit=50 retrieves the first 50 records.offset=50&limit=50 retrieves the next 50 records.
Vim allows developers to test the API without accessing live data. By using vimOrganizationId = 123456789 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.
How This API Works
This API is not a real-time backend-to-backend EHR integration. It is a daily snapshot system — Vim syncs appointment data from the EHR once per day, and this endpoint serves that latest snapshot.
Daily sync flow:
- Once per day, Vim syncs appointments from the EHR for each provider with an NPI, covering the next 10 days.
- The data is stored in Vim''s backend.
- This endpoint returns that stored snapshot — it does not query the EHR in real time.
Supported EHRs: ECW, Athena, and Sandbox EHR (for testing).
Key constraints:
- Not real-time: Data is synced once daily. Expect up to a 24-hour lag for new appointments.
- NPI required: Only physicians with an NPI set in the EHR are included in the sync.
- App must be initialized: The app authentication flow must be completed for that user before any data is synced for them.
- Physician must be logged in: Vim Connect must be active during the daily sync window for that provider''s data to be extracted.
- Appointment timing matters: Appointments added to the EHR after the daily sync has run won''t appear until the following day.
- Lookahead window: Only the next 10 days of appointments are available.
'
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