<nav id="sidebar" class.bind="appState.toggleMenu ? 'active' : ''" if.bind="showNav">
    <header>
      <img click.trigger="navigate('reports')" src="https://mediroutescdn.azureedge.net/images/MediRoutes-Logo-White.png" alt="MediRoutes Logo">

      <button class="close-menu" click.trigger="toggleMenu()"> 
        <i class="fas fa-times"></i>
      </button>
    </header>

    <div class="navigation-scroll-container">
        <navigation></navigation>
    </div>
</nav>


Last Updated June 9th, 2020

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://external.mediroutesapi.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 webhook

Environments

EnvironmentBase URLSwagger URL
Productionhttps://external.mediroutesapi.com/https://external.mediroutesapi.com/swagger/ui/index#/
Testhttps://mediroutesexternalapi-primary-test.azurewebsites.net/https://mediroutesexternalapi-primary-test.azurewebsites.net/swagger/ui/index
Developmenthttps://mediroutesexternalapi-primary-development.azurewebsites.net/https://mediroutesexternalapi-primary-development.azurewebsites.net/swagger/ui/index

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://external.mediroutesapi.com/token endpoint to obtain access and refresh tokens using your MediRoutes Username and Password:

  1. grant_type = “password”
  2. username =
  3. password =

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 30 minutes and will require use of a refresh token. 

Request

POST{root_url}/token

ParameterTypeDescriptionNotes
grant_typestringtype in the string "password"REQUIRED
usernamestringMediRoutes usernameREQUIRED
passwordstringMediRoutes passwordREQUIRED

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

ParameterTypeDescription
access_tokenstring
token_typestringbearer
expires_inint1 day = 24 hours = 86400 seconds
refresh_tokenstring
userNamestringMediRoutes username
.issuedstringUTC date / time that token was issued
.expiresstringUTC date / time that token will expire

Sample 200 Response Body - Token Endpoint

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3ZDUyMmNiMS1iZDYxLTQzZDctOWY3OS04MzgyM...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "refresh_token": "CfDJ8EMw3GMoAG1Khpbl5wMJxvmsmeu553OU7whkKzFLC3h0ote-3NzDlA_I7PIqGnPn4UnmP6pZ8cS3...",
    "userName": "user@mediroutesapi.com",
    ".issued": "Mon, 08 Jun 2020 17:17:55 GMT",
    ".expires": "Tue, 09 Jun 2020 17:17:55 GMT"
}

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 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://external.mediroutesapi.com/api/v1/access using the API version number and the bearer token in the Authorization field:

  1. Version = (currently "1")
  2. Authorization = "bearer " (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

GET{root_url}/v{version}/access

ParameterTypeDescriptionNotes
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED

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

ParameterTypeDescription
APIKeystringUnique ID of Transportation Provider
TranportationProviderNamestringName of Transportation Provider
FundingSources-Collection of Funding Sources
.FundingSourceIdintUnique ID of Funding Source 
.FundingSourceNamestringName of Transportation Provider's Funding Source

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.

[
    {
    "APIKey": "00e1015d588f456444b6b3a7207762c1",
    "TranportationProviderName": "Transportation Provider Co #1",
    "FundingSources": [
    {
        "FundingSourceId": 918,
        "FundingSourceName": "Broker ABC"
    },
    {
    "APIKey": "233346f3e577f4c77af64c6f43454d454b",
    "TranportationProviderName": "Fictional Transportation Company #2",
    "FundingSources": [
    {
        "FundingSourceId": 1629,
        "FundingSourceName": "State Medicaid"
    },
    {
        "FundingSourceId": 1628,
        "FundingSourceName": "Broker ABC"
    }
    ]
    }
]

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 a new patient.

Please Note: If an additional claim 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.

SingleTrip

The Client can POST, GET or PATCH a single trip to MediRoutes API. A single trip is comprised of a pickup and a dropoff event. Trip ID is a user-defined value. Trip GUID is a MediRoutes-defined value and will be returned along with the entire trip object upon successful trip insertion, or POST.

Please Note: Round trips need to be entered as two separate trips.

POST SingleTrip Endpoint

There are three types of trips that can be inserted into MediRoutes, each with slightly different required fields:

  1. Appointment Trips
  2. Return Trips
  3. Will Call Trips

Please Note: You can either pass in a complete address in one field (shown in the pickup address below) or a broken out address with each field separated for Address1, Address2, City, State, and ZIP (shown in the dropoff address below) . Latitude and longitude are required with either type of address.

Request

POST{root_url}/v{version}/singletrip

ParameterTypeDescriptionNotes
tp_api_keystringREQUIRED
trip_idstringREQUIRED
rider_idstringREQUIRED
pickup-

.event_namestring

.event_commentstring

.complete_addressstring

.event_location


..location_namestring

..address1string

..address2string

..citystring

..statestring

..zipstring

..longitudedouble (?)

..latitudedouble (?)

.appt_time


.pickup_time


.phone_number


dropoff-

.event_name


.event_comment


.complete_address


.event_location-

..location_name


..address1


..address2


..city


..state


..zip


..longitude


..latitude


.appt_time


.pickup_timeWHY IS THIS NOT DROPOFF TIME?

.phone_number


funding_source_nameREQUIRED

space_typeREQUIRED

billable_distance


phone


trip_type


additional_passengers


.space_type


.count


POST Appointment Trip Sample

{
"tp_api_key": "00e1015d588f448384b6b3a7207762c1", //required
"trip_id": "TripApptTest3-10", //required
"rider_id": "rider90", //required
"pickup": {
"event_name": "Doe, Jane - Pickup Appointment",
"event_comment": "Drop off the patient in the back of building",
"complete_address": "2882 N Scottsdale Rd, Scottsdale, AZ 85257",
"event_location": {
"location_name": "Honor Health Scottsdale",
"address1": "",
"address2": "",
"city": "",
"state": "",
"zip": "",
"longitude": -111.9287566, //required
"latitude": 33.4799636 //required
}
},
"dropoff": {
"event_name": "Doe, Jane - Dropoff Appointment",
"event_comment": "Patient's caretaker can be reached at 602.123.1234 if needed upon arrival",
"complete_address": "",
"event_location": {
"location_name": "XYZ Retirement Community",
"address1": "6606 W Camelback Rd",
"address2": "Unit 123",
"city": "Glendale",
"state": "AZ",
"zip": "85301",
"longitude": -112.2035528, //required
"latitude": 33.5097911 //required
},
"appt_time": "04/10/2020 3:00PM" //required for appointment trip
},
"funding_source_name": "Broker ABC", //required
"space_type": "WCH", //required
"billable_distance": 0,
"phone": "(623)-453-3453",
"trip_type": "Appointment", //required
"additional_passengers": [
{
"space_type": "AMB",
"count": 1
}
]
}

POST Return Trip Sample

{
"tp_api_key": "00e1015d588f448384b6b3a7207762c1", //required
"trip_id": "TripReturnTest-12345", //required
"rider_id": "rider90", //required
"pickup": {
"event_name": "Doe, Jane - Pickup Return",
"event_comment": "Patient will exit from the east side of the building",
"complete_address": "2882 N Scottsdale Rd, Scottsdale, AZ 85257",
"event_location": {
"location_name": "Honor Health Scottsdale",
"address1": "",
"address2": "",
"city": "",
"state": "",
"zip": "",
"longitude": -111.9287566, required
"latitude": 33.4799636 required
},
"pickup_time": "04/11/2020 2:00PM", required for return trip
} required,
"dropoff": {
"event_name": "Doe, Jane - Dropff Return",
"event_comment": "Patient's caretaker can be reached at 602.123.1234 if needed upon arrival",
"complete_address": "",
"event_location": {
"location_name": "XYZ Retirement Community",
"address1": "6606 W Camelback Rd",
"address2": "Unit 123",
"city": "Glendale",
"state": "AZ",
"zip": "85301",
"longitude": -112.2035528, //required
"latitude": 33.5097911 //required
},


},
"funding_source_name": "Broker ABC", //required
"space_type": "WCH", //required
"billable_distance": 0,
"phone": "(623)-453-3453",
"trip_type": "Return", //required
"additional_passengers": [
{
"space_type": "AMB",
"count": 1
}
]
}

POST Will Call Trip Sample

Please Note: For Will Call trips, pickup_time is required and must have a date and time. Time is required to be 11:59PM to denote Will Call. Additionally, trip_type = "willcall".

{
"tp_api_key": "00e1015d588f448384b6b3a7207762c1", //required
"trip_id": "TripWillCall-Test123", //required
"rider_id": "rider90", //required
"pickup": {
"event_name": "Jane Doe - Will Call Pickup",
"event_comment": "Jane will call the transportation provider when she is ready to be picked up",
"complete_address": "2882 N Scottsdale Rd, Scottsdale, AZ 85257",
"event_location": {
"location_name": "",
"address1": "",
"address2": "",
"city": "",
"state": "",
"zip": "",
"longitude": -111.9287566, //required
"latitude": 33.4799636 //required
},
"pickup_time": "04/10/2020 11:59PM", //required for will call trip; time must be 11:59pm for will call
}
"dropoff": {
"event_name": "Jane Doe - Will Call Dropoff",
"event_comment": "",
"complete_address": "",
"event_location": {
"location_name": "XYZ Retirement Community",
"address1": "6606 W Camelback Rd",
"address2": "Unit 123",
"city": "Glendale",
"state": "AZ",
"zip": "85301",
"longitude": -112.2035528, //required
"latitude": 33.5097911 //required
},
"appt_time" : "04/10/2020 3:00PM"
},
"funding_source_name": "Broker ABC", //required
"space_type": "WCH", //required
"billable_distance": 0,
"phone": "(623)-453-3453",
"trip_type": "Willcall", //required
"additional_passengers": [
{
"space_type": "AMB",
"count": 1
}
]
}

Expected Responses

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.

403 forbidden? (PARNEET)

500 - Unknown error; Contact MediRoutes.

Webhooks

Webhooks are automated messages sent from apps when something happens. They have a message—or payload—and are sent to a unique URL. Essentially, the webhook subscriber provides an address for MediRoutes to send messages to when something changes in MediRoutes.

Trip-Level Webhooks

Subscribe to Trip-level Webhooks by Trip GUID

In order to subscribe to Trip-level webhooks via the MediRoutes API, users will need the following:

A. API Key

  1. API Keys can be obtained per transportation provider via the /access endpoint

B. Trip GUID (this is different than the Trip ID)

  1. Trip GUIDs can be obtained by hitting the /getRidesByDate endpoint

C. Call Back URL

  1. The URL MediRoutes will call when a Trip Change occurs
  2. Use webhook.site to obtain a test URL for testing purposes

D. Call Back URL Headers

  1. These are optional, depending on your application’s implementation

E. Name

  1. Anything you’d like to name the webhook subscription

F. Version

  1. The version of the API. Currently, version “1”

G. Authorization

  1. “bearer ” (see screenshot below)
  2. Can be obtained via the /token endpoint

Sample Response to Successful Subscription

Once you are successfully subscribed, you will receive a 200-response code and a message confirming the webhook subscription has been created.