Last Updated March 31st, 2022

The MediRoutes API allows users to interact with MediRoutes data. The API is designed around RESTful principles and return JSON in response to HTTP requests. 

Up to date endpoints: https://api.mediroutes.com/swagger/ui/index#!

Contact MediRoutes Support for access to the MediRoutes API.

Support@ScheduleViewer.com

Who uses it?

1. Transportation Brokers
2. Transportation Providers / MediRoutes Clients
3. Third Party Administrators

How can it be used?

Trip/Ride Management

1. Get a list of trips by date
2. Create a trip
3. Update a trip
4. Update the status of a will call trip
5. Cancel a trip
6. Obtain real-time trip status
7. Subscribe to trip-level webhooks

Rider/Passenger/Patient Management

1. Create a rider
2. Update a rider
3. Obtain rider details

User Management

1. Create a user
2. Update a user
3. Obtain user details & permissions
4. Deactivate a user
5. Fetch timekeeping records

Funding Source / Payer Management

1. Create a funding source
2. Update a funding source
3. Obtain funding source details
4. Deactivate a funding source
5. Subscribe to funding source-level webhooks

Environments

Rate Limiting / Endpoint Throttling

In order to uphold the highest standard of performance and reliability for each API consumer, our architecture incorporates both a comprehensive global rate limiting strategy as well as endpoint-specific limitations. This approach, as detailed below, is designed to ensure optimal service delivery while maintaining the integrity and effectiveness of each individual API endpoint.

Exceeding these rate limits will result in a response code of 429. If are are experiencing a large number of responses with this status code, our recommendation is to use an exponential backoff retry policy.

Authentication & Authorization

Like other RESTful APIs, the MediRoutes API uses JWT to handle authentication and authorization with refresh tokens. 

How to Obtain a Bearer Token

Once the MediRoutes Team grants you access to the MediRoutes API, you can obtain a bearer token which can be used to hit all other API endpoints.

A.   Authorization Grant: Using a client (or Swagger/Postman for testing), POST to the https://api.mediroutes.com/token endpoint to obtain access and refresh tokens using your MediRoutes Username and Password:

1. grant_type = “password”
2. username = <yourMediRoutesUsername>
3. password = <yourPassword>

B.   MediRoutes returns Access token & Refresh token

C.   Send Access token in request header as a bearer token for all other API endpoints

D.   MediRoutes returns requested Resources

E.    Once an Access Token expires,

F.    An Invalid Token Error (401 Unauthorized Error) will be returned

G.   a Refresh Token must be used to obtain new access token

Please Note: Access tokens expire after 24 hours and will require use of a refresh token. 

Request

Expected Response Codes

200 - Request was successful; Access and Refresh tokens returned.

401 - Request was unsuccessful; Username, Password and/or Grant Type incorrect. (grant_type value is equal to the string "password")

500 - Unknown error; Contact MediRoutes.

Expected Response Body

Sample 200 Response Body - Token Endpoint

Access Claims

Each transportation provider has one or many Funding Sources in MediRoutes to manage and logically organize trips. In MediRoutes, a funding source is synonymous with a Payer - the entity who is actually paying the transportation provider to perform the trip. Funding sources are often brokers, healthcare organizations, private payers and managed care facilities.

Since a MediRoutes API user may work with one or many transportation providers, API access (also known as 'claims') is granted to users at the transportation provider level and associated funding source level.

API users on behalf of brokers may have access to a single funding source for many transportation providers. API users who work for or with a single transportation provider may be granted access to only their own MediRoutes data by granting access to all funding sources for that single transportation provider.

Access Endpoint

The access endpoint will return a nested list of all transportation providers and associated funding sources your API user has access to. Each transportation provider has a Transportation Provider Name and an API Key. Each Funding Source has a Funding Source Name and a Funding Source ID.

To see which transportation providers and funding sources you have access to, simply hit the GET Access endpoint:

A. Get Access Using a client (or Swagger/Postman for testing), GET https://api.mediroutes.com/api/v1/access using the API version number and the bearer token in the Authorization field:

1. version = <API version number> (currently "1")
2. Authorization = "bearer <access token>" (see screenshot below)*

B. MediRoutes API returns a list of Transportation Providers, their unique API Key and all currently accessible Funding Sources as well as their associated Funding Source IDs

*Please Note: the word "bearer" and a space " " must come before the bearer token in the Authorization parameter. This applies to all endpoints that require Authorization.

Request

Expected Response Codes

200 - Request was successful; API Key(s) and Funding Source(s) returned.

401 - "You do not have access to this resource." Request was unsuccessful; Either token is invalid, the word "bearer " is missing, or token is expired.

500 - Unknown error; Contact MediRoutes.

Expected Response Body

Sample 200 Response Body - Token Endpoint

The following sample response shows what a user would receive back from the Access endpoint if they had access to two transportation providers with one or two funding sources.

The API Key for each transportation provider will be used in conjunction with the bearer token to hit all other endpoints in the API. Funding Source Name is also required for several of the API calls such as inserting a trip or adding a new patient.

Please Note: If an additional transportation provider and/or funding source is added to your API user access, you will need to obtain a new token to see these new claims reflected in the Access endpoint response.

FundingSource

The client can DELETE, GET, PATCH, or POST funding source information. NOTE: You must have the ability to manage users.

Get Funding Source By Id Endpoint

Gets a single funding source by Id. NOTE: You must have the ability to manage users.

Request

Expected Response Codes

200 - Request was successful; Status code and message returned.

401 - User management is not allowed for this api_key.

403 - The api key used does not have access to this resource.

Sample 200 Response Body - Get Funding Sources Endpoint

The following sample response shows what a user would receive back for a request where the user only has a single funding source.

Deactivate Funding Source By Id Endpoint

Deactivates an existing funding source. NOTE: You must have the ability to manage users.

Request

Expected Response Codes

200 - Request was successful; Status code and message returned.

401 - User management is not allowed for this api_key.

403 - The api key used does not have access to this resource.

Sample 200 Response Body - Deactivate Funding Source Endpoint

The following sample response shows what a user would receive back from the deactivate funding source endpoint.

Deactivate FundingSource Endpoint

Deactivates an existing funding source. NOTE: You must have the ability to manage users.

Request

Expected Response Codes

200 - Request was successful; Status code and message returned.

401 - User management is not allowed for this api_key.

403 - The api key used does not have access to this resource.

Sample 200 Response Body - Deactivate Funding Source Endpoint

The following sample response shows what a user would receive back from the deactivate funding source endpoint.

Get Funding Sources Endpoint

Request

Expected Response Codes

200 - Request was successful; Funding sources returned.

401 - User management is not allowed for this api_key.

403 - The api key used does not have access to this resource.

Sample 200 Response Body - Get Funding Sources Endpoint

The following sample response shows what a user would receive back for a request where the user only has a single funding source.

Update Funding Source Endpoint

Request

Model Definition

Expected Response Codes

200 - Request was successful.

401 - User management is not allowed for this api_key.

403 - The api key used does not have access to this resource.

Funding Source Model Sample

Create Funding Source Endpoint

Request

Model Definition