Introduction
Obtaining Access
Authentication & Authorization
Obtaining a Bearer Token
Access Claims
Access Endpoint
MediRoutes Environments
Diagrams
FAQs
API Endpoints
Managing Passengers
Managing Trips
Managing Webhooks
User Management
Funding Source Management
Brokerage Endpoints
Other Endpoints
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.
Our API is designed to be used by Transportation Brokers, Transportation Providers, as well as 3rd party administrators.
At a high level, API access can be divided into two categories. Client Users would be those with an active MediRoutes account, that would have access to all endpoints and funding sources of their MediRoutes Account, including those that manage internal users and funding sources. Brokerage users would be those that have access granted to them by MediRoutes Customers, and would only have access to Trips and Passengers of the funding sources they are authorized for, and no access to the User Management or Funding Source Management endpoints. Brokers would be able to access the Brokerage Endpoints, which are used to configure how MediRoutes Accounts interact with the brokerage, such as cancel reasons, reroute reasons, and space type mapping.
Client User - A user with administrative access to your individual MediRoutes Account will send a request to support@scheduleviewer.com, letting them know which user in your system you want granted API access. This user would be granted access to all funding sources in your MediRoutes Account.
Brokerage User - A data sharing agreement would be completed by an existing MediRoutes user with Administrative access to an account. In completing this data sharing agreement, the user would grant you access to a specific funding source for their account. This knowledgebase article will walk through the individual steps required by the client to complete that data sharing agreement (MediRoutes Knowledgebase). Currently we support the following brokers:
Alivi
Access2Care
Call The Car
Ride Health
Kaizen
MediTrans
Veyo
If you are a broker and would like to be included in this list, please send an email to support@scheduleviewer.com and we can schedule a meeting to discuss how you plan to use MediRoutes.
Like other RESTful APIs, the MediRoutes API uses JWT to handle authentication and authorization with refresh tokens.
POST https://external.mediroutesapi.com/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.
Authorization Grant: Using a client (or Swagger/Postman for testing), POST to the https://external.mediroutesapi.com/token endpoint to obtain access and refresh tokens using your MediRoutes Username and Password:
grant_type = “password”
username = <yourMediRoutesUsername>
password = <yourPassword>
MediRoutes returns Access token & Refresh token
Send Access token in request header as a bearer token for all other API endpoints
MediRoutes returns requested Resources
Once an Access Token expires, An Invalid Token Error (401 Unauthorized Error) will be returned, and 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.
GET https://mediroutes-primary.developer.azure-api.net/api-details#api=Mediroutes_Api&operation=get-access
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.
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:
Get Access Using a client (or Swagger/Postman for testing), GET https://external.mediroutesapi.com/api/v1/access using the API version number and the bearer token in the Authorization field:
version = <API version number> (currently "1")
Authorization = "bearer <access token>" (see screenshot below)*
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.
MediRoutes maintains 3 separate environments for APIs. Development and Test API environments are used when we are deploying enhancements to our APIs, and as such you may see different behavior within them that you would see using production endpoints. Due to this, it is recommended that all testing be done within our production API environment. If needed, we can grant limited access to a sandbox account so that testing can be done without impact to live data.
Production
Test
Development
Directly below, you can see the workflow of obtaining an Access Token:
This image shows a flowchart of the various states a MediRoutes trip would be in:
MediRoutes utilizes multiple IDs within the system for riders, trips, and funding sources.
ID / Client ID / Rider ID - This is intended to be a unique external ID that is associated to a record in an external system. For example, Medicaid ID, Insurance ID, SSN, are all IDs that would go into this field. This ID would be unique for each account, but is not unique across the entire MediRoutes system.
MediRoutes ID / MediRoutes Rider ID - This is a unique ID that MediRoutes automatically generates for each rider record in our system. This ID is unique across the entire MediRoutes system.
When creating a trip, rider_id is used to identify if the rider exists in the account.
ID / Trip ID / Authorization Number - This is intended to be a unique external ID that is associated to a record in an external system. One ID would be applied to each trip leg that is posted to our system. This ID would be unique for each account, but is not unique across the entire MediRoutes system.
GUID - This is a unique ID that MediRoutes automatically generates for each trip record in our system. This ID is unique across the entire MediRoutes system.
It is recommended that you associate your trip records with a MediRoutes GUID. it can be extremely helpful to utilize both an external ID and the GUID.
If a particular trip would show up within multiple MediRoutes accounts, make certain to update the GUID in your external system when creating the trip within a separate account.
Funding Source Name - The free form name assigned by a user to a particular funding source
Funding Source ID - A unique ID assigned to that account for that funding source
Using a Funding Source ID is generally preferred. Although it does not happen often, users can create a breaking change by updating their funding source name. The Funding Source ID does not change and is a far more reliable identifier.
MediRoutes uses 3 different types of trips. Appointment, Return, and Will Call. These are represented by Trip Types 1 (Will Call), 2 (Appointment), and 3 (Return).
A will call trip should have a pickup request time of 11:59 PM when created. Will calls are trips that do not have a time until a passenger requests to be picked up. In most cases, they represent the return leg of a trip/
An appointment trip must have an appointment time defined. If your trip request includes a pickup time, we will utilize the pickup time defined, if you do not utilize a pickup time we will calculate it based on the space type of the trip, time of day, and the distance between the locations. An appointment trip is a trip where there is a specified time the customer must arrive at the dropoff location.
A return trip must have a pickup time defined and should not have an appointment time defined. A return trip indicates that there is a specific time the passenger must be picked up, but there is no specific time they need to be at their destination.
The /riders endpoint is used to create and manage individual MediRoutes Riders/Passengers. Severeral of these endpoints have the same function, but utilize a different type of ID. Create Rider requires the Funding Source name to be used, while Create Rider Using Funding Source ID would require the Funding Source ID to be used instead (See Access endpoint for Funding Source IDs and Names).
A rider record would have both an ID (or Client ID, Rider ID) and a MediRoutes ID. The ID is a unique identifier used to associate the Rider with a record in an external system (external ID), while the MediRoutes ID is a unique ID that MediRoutes generates for all Rider records in our system. Multiple MediRoutes accounts that service the same Rider could all have that Client ID in their system, however the MediRoutes ID is unique across all of our Accounts and the same Rider would have a different MediRoutes ID for each of our Accounts that they are in.
GET https://mediroutes-primary.azure-api.net/api/v{version}/riders/getByRiderId?api_key={api_key}&rider_id={rider_id}
GET https://mediroutes-primary.azure-api.net/api/v{version}/riders/getByMediroutesRiderId?api_key={api_key}&mediroutes_rider_id={mediroutes_rider_id}
Searching for a Rider by MediRoutes ID will mirror the functionality of Search Rider by ID, however this searches based on their unique MediRoutes ID as opposed to the Client ID.
GET https://mediroutes-primary.azure-api.net/api/v{version}/riders?api_key={api_key}
POST https://mediroutes-primary.azure-api.net/api/v{version}/riders
POST https://mediroutes-primary.azure-api.net/api/v{version}/riders/createRiderUsingFsid
This mirrors the functionality of Create Rider, however this uses the Funding Source ID to find a matching funding source as opposed to the Funding Source Name.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/riders?api_key={api_key}&rider_id={rider_id}
Deleting a Rider is not possible, but you can mark one as inactive so that it is not readily displayed to a MediRoutes User.
PUT https://mediroutes-primary.azure-api.net/api/v{version}/riders
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/riders?api_key={api_key}&mediroutes_rider_id={mediroutes_rider_id}&rider_id={rider_id}
This mirrors the functionality of Update Rider, however this uses the MediRoutes ID to find a matching Rider as opposed to the ID or Client ID.
There are two main endpoints for managing trips, /rides is used to query groups of trips, update individual trips, and cancel existing trips, while the /singletrip endpoint is used to create individual trips, update specific properties of an individual trip, or to obtain a where’s my ride link. There is an additional /tripstatus endpoint that is used to get trip specific information regarding the status of a trip, collect PUDO times, and collect trip signatures.
Much like the riders endpoint, there are several endpoints that mirror functionality, but utilize a different ID. For trips, the two IDs commonly used are the Trip ID (or Authorization Number) and the Trip GUID. The Trip ID is the external ID used to associate a trip record to an external system, and could be found within other accounts. The Trip GUID is generated by MediRoutes and is a unique key to identify that trip across all accounts.
GET https://mediroutes-primary.azure-api.net/api/v{version}/singletrip?api_key={api_key}&trip_id={trip_id}
GET https://mediroutes-primary.azure-api.net/api/v{version}/rides?api_key={api_key}&ride_id={ride_id}
Both the /rides and /singletrip GET requests provide the same information.
GET https://mediroutes-primary.azure-api.net/api/v{version}/rides/getTripByGuid?api_key={api_key}&trip_guid={trip_guid}
This mirrors the functionality of Search for Trip however this uses the GUID to find a matching trip as opposed to the ID or Trip ID.
GET https://mediroutes-primary.azure-api.net/api/v{version}/rides/getRidesByDate?api_key={api_key}&includeUnScheduled={includeUnScheduled}&date={date}[&includeUnperformed][&includeBreaks]
This will return all of the trips for a single date and includes several parameters to further filter was is returned.
GET https://mediroutes-primary.azure-api.net/api/v{version}/rides/query
This will return trips for multiple dates but only for a single funding source.
GET https://mediroutes-primary.azure-api.net/api/v{version}/tripstatus?ride_id={ride_id}&apiKey={apiKey}
Trip Status is where you can find information regarding arrive times, signatures, and other perform related events.
GET https://mediroutes-primary.azure-api.net/api/v{version}/tripstatus/getTripStatusByTripGuid?trip_guid={trip_guid}&apiKey={apiKey}
This mirrors Get Trip Status, however this searches based on the GUID as opposed to the Trip ID.
GET https://mediroutes-primary.azure-api.net/api/v{version}/rides/getTripCostBreakdown?trip_guid={trip_guid}&api_key={api_key}
This provides a breakdown of individual billing items for a trip.
GET https://mediroutes-primary.azure-api.net/api/v{version}/singletrip/wheresMyRideUrl?api_key={api_key}&trip_guid={trip_guid}
This will provide a link to the MediRoutes Where's My Ride tool for a specific Trip GUID.
This is an extremely helpful link to provide to customers so that their MediRoutes Trips can be tracked.
To create a trip, a rider must first be created within the account. Once the rider is created, the rider is identified using the rider_id field and not the mediroutes_rider_id.
POST https://mediroutes-primary.azure-api.net/api/v{version}/singletrip
POST https://mediroutes-primary.azure-api.net/api/v{version}/singletrip/withFsid
POST https://mediroutes-primary.azure-api.net/api/v{version}/singletrip/withRider
The MediRoutes API does not restrict when trips can be updated as the intent is to ensure that data is properly synced, with the exception of if a trip has already been performed, it is unable to be canceled from MediRoutes. It is recommended that you work closely with our Transportation Providers when making any short notice updates, as they may already have these trips assigned to drivers already and any changes would impact their schedules.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/rides
We do not allow a trip to be deleted from the system, however it can be canceled through this request.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/rides/CancelTripByTripGuid
This mirrors Cancel a Trip, however this searches based on the GUID as opposed to the Trip ID.
PUT https://mediroutes-primary.azure-api.net/api/v{version}/rides?trip_guid={trip_guid}&api_key={api_key}&trip_id={trip_id}
This is a specialized call where you can search for a unique trip in MediRoutes, and update the Client ID. The intention of this is to make it easier for API users to update the external ID for trips, using the GUID as an identifier.
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/rides
Another specialized call used to update common fields that are updated for a will call trip, specifically the Time, Rider Phone Number, and Driver instructions, for a Will Call Trip
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/singletrip
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/singletrip/withProperties
This will allow you to update individual fields of a trip, without needing to include the entire body of the trip in the request.
POST https://mediroutes-primary.azure-api.net/api/v{version}/webhook/fsChange?api_key={api_key}
In order to subscribe to Funding Source-level webhooks via the MediRoutes API, users will need the following:
API Keys can be obtained per transportation provider via the /access endpoint
Funding Source IDs can be obtained by hitting the /access endpoint
The URL MediRoutes will call when a Trip Change occurs
Use webhook.site to obtain a test URL for testing purposes
These are optional, depending on your application’s implementation
Do not include sensitive information in the Call Back URL Headers. This is stored in the database in plain text.
Anything you’d like to name the webhook subscription, The Name of the subscription must be unique per transpotation provider, per webhook type.
The version of the API. Currently, version “1”
“bearer <access token>” (see screenshot below)
Can be obtained via the /token endpoint
Any added, canceled or edited trip associated with a given funding source will trigger a webhook message to be sent. This includes:
Scheduled to a Run / Unscheduled from a Run
Arrived Pickup & Dropoff / Performed Pickup & Dropoff
Canceled / Dry Run
Funding Source
Space Type
Charges
Addresses
Comments
Pickup and Dropoff Times
Appointment Times
etc.
POST https://mediroutes-primary.azure-api.net/api/v{version}/webhook/tripChange?api_key={api_key}
It is recommended that you utilize Funding Source level webhooks as opposed in individual trip webhooks.
POST https://mediroutes-primary.azure-api.net/api/v{version}/webhook/gps/vehicle?api_key={api_key}
This will provide a webhook indicating the vehicles location and trip GUIDs scheduled to that vehicle.
GET https://mediroutes-primary.azure-api.net/api/v{version}/webhook?api_key={api_key}
Will provide all currently active webhook subscriptions for an individual API key.
GET https://mediroutes-primary.azure-api.net/api/v{version}/webhook/id?api_key={api_key}&id={id}
Will retrieve a single webhook subscription by the webhook subscriptions ID.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/webhook?api_key={api_key}&keyOrId={keyOrId}
Deletes a Webhook subscription by API key and webhook ID.
POST https://mediroutes-primary.azure-api.net/api/v{version}/webhook/newTrip?api_key={api_key}
If you subscribe to a funding source webhook already, you do not need to subscribe to this endpoint as you will already receive a webhook upon trip creation.
Note that brokerage accounts would not have access to User Management Endpoints. Only users that have full API access to an account, and not API access to only a single funding source, would have access to User Management endpoints.
POST https://mediroutes-primary.azure-api.net/api/v{version}/users
Create a new user. Users must have a unique username.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/users?api_key={api_key}&user_name={user_name}
Deactivates a user specified by the username
GET https://mediroutes-primary.azure-api.net/api/v{version}/users?api_key={api_key}[&user_name][&includeInactiveUsers]
Get all users or a single user by username
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/users
Updates an existing user specified by the username
Note that brokerage accounts would not have access to Funding Source Endpoints. Only users that have full API access to an account, and not API access to only a single funding source, would have access to Funding Source endpoints.
If you are a brokerage account and need information on which funding sources you would have access to, you can utilize the Access endpoint which would return both the name and ID of available funding sources.
POST https://mediroutes-primary.azure-api.net/api/v{version}/fundingsources
Creates a new funding source.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/fundingsources?api_key={api_key}&funding_source_name={funding_source_name}
Deactivates an existing funding source via funding source name.
DEL https://mediroutes-primary.azure-api.net/api/v{version}/fundingsources/deactivateFundingSourceById?api_key={api_key}&funding_source_id={funding_source_id}
Deactivates an existing funding source via funding source ID.
GET https://mediroutes-primary.azure-api.net/api/v{version}/fundingsources?api_key={api_key}[&funding_source_name][&includeInactiveFundingSources]
Gets all funding sources for client or a single funding source by name.
GET https://mediroutes-primary.azure-api.net/api/v{version}/fundingsources/getFundingSourceById?api_key={api_key}&funding_source_id={funding_source_id}[&includeInactiveFundingSources]
Gets a single funding source by Id
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/fundingsources
Updates an existing funding source. Note.
Brokerage endpoints are designed to allow brokers to configure how our customers interact with your funding source within MediRoutes. Only users specifically identified as brokerage users would have access to these endpoints. If you are a broker working with Multiple MediRoutes customers and would like access to these brokerage endpoints, reach out to support@scheduleviewer.com and make a request to get your company added to our list of brokerage accounts.
You can do manage 3 key things through brokerage endpoints
- Notifications - Through these endpoints you can define a list of email addresses that we will notify when a customer either grants or rescinds their API access to you.
- Reroutes and Cancels - Through these endpoints you can define a list of reasons that our customers will select from when canceling a trip from MediRoutes. The reason the customer selected is available through the cancelation webhooks or from GET endpoints from within the Cancellation Reason field.
- Space Type Mapping - Through these endpoints you can create a list of space types that a MediRoutes customer can map their space types to. If you utilize a large number of specialized space types across many clients, this can significantly help to reduce the number of errors associated with attempting to send trips to customers who do not have the requested space type defined in the system.
POST https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/addNotificationEmail
A notification email is sent out when a customer enables or disables your API access to their account.
This endpoint allows you to add emails to send this notification to when this action occurs.
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/updateNotificationEmail
Replace an existing DSA notification email with a new one
DEL https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/deleteNotificationEmail
Delete a DSA notification email. NOTE: You cannot delete the email if there is only one.
GET https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/getNotificationEmails
Get all emails used for DSA notification.
POST https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/addRerouteOrCancelReason
A Reroute or Rejection would be a trip that a transportation provider has determined they do not want to take, but the passengers trip would still need to be completed. A Cancel would be a trip where the passengers trip does not need to be completed. For either reason, the trip status in MediRoutes would be Cancelled, however this endpoint allows you to force a user to supply a reason from a preset list that you define.
Add a new reroute or cancel reason. The reason type must be either "Reroute" or "Cancel."
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/activateDeactivateRerouteOrCancelReason
Marks the reroute or cancel reason as active or inactive.
GET https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/getCancelReasons
Returns all cancel reasons, including inactive.
GET https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/getRerouteReasons
Returns all reroute reasons, including inactive.
POST https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/addBrokerageSpaceType
Through this endpoint you can add a list of space types that a MediRoutes customer can use to map their space types to. Populate this list with all of the space types that you will send over to MediRoutes and our customers can map the space types they have created in MediRoutes with those you define.
PATCH https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/activateOrDeactivateBrokerageSpaceType
This will remove the space type from those available for the customer to map to.
GET https://mediroutes-primary.azure-api.net/api/v{version}/brokerage/getSpaceTypes
Returns all space types, including inactive.
GET https://mediroutes-primary.azure-api.net/api/v{version}/timekeeping?api_key={api_key}&user_name={user_name}&from_date={from_date}&to_date={to_date}[&includeInactiveUsers]
Will provide timecard breakdown for specific user, if the MediRoutes customer utilizes timekeeping.
©Copyright 2019 MediRoutes. All Rights Reserved.