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 webhooks



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 = <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

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

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 a Transportation Provider
TranportationProviderNamestringName of Transportation Provider
FundingSources-Collection of Funding Sources per Transportation Provider
.FundingSourceIdintUnique ID of a 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 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.


SingleTrip

The Client can POST, GET or PATCH a single trip to MediRoutes via the 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_keystring
REQUIRED
trip_idstring
REQUIRED
rider_idstring
REQUIRED
pickup-

.event_namestring

.event_commentstring

.complete_addressstring

.event_location-

..location_namestring

..address1string

..address2string

..citystring

..statestring

..zipstring

..latitudedouble 
REQUIRED
..longitudedouble 
REQUIRED
.appt_timedatetimeformat = "2020-06-11 14:48:49.403"
.pickup_timedatetimeformat = "2020-06-11 14:48:49.403"
.phone_numberstring

dropoff-

.event_namestring

.event_commentstring

.complete_addressstring

.event_location-

..location_namestring

..address1string

..address2string

..citystring

..statestring

..zipstring

..latitudedouble
REQUIRED
..longitudedouble
REQUIRED
.appt_timedatetimeformat = "2020-06-11 14:48:49.403"
.pickup_time--Read Only
.phone_numberstring

funding_source_namestring
REQUIRED
space_typestring
REQUIRED
billable_distancedoubleDistance in miles.  If no value is passed, MediRoutes will calculate the mileage using the Transportation Provider's distance settings and Bing Maps API.  If a value is passed, MediRoutes will accept the provided value and will not calculate a distance. 
phonestring

trip_typestring
REQUIRED
additional_passengers-

.space_typestringTypically AMB.
.countint


POST Appointment Trip Sample

{
  "tp_api_key": "56e1015d588fgdpf448384b6b3a345dfgd564", 
  "trip_id": "TripApptTest3-10", 
  "rider_id": "rider90", 
  "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,
      "latitude": 33.4799636 
    },
    "pickup_time": "2020-04-10 14:48:49.403",
    "phone_number": "520.234.2342"
  },
  "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, 
      "latitude": 33.5097911 
    },
    "appt_time": "04/10/2020 3:00PM", 
    "phone_number": "502.234.2342"
  },
  "funding_source_name": "Broker ABC", 
  "space_type": "WCH", 
  "billable_distance": 4,
  "phone": "(623)-453-3453",
  "trip_type": "Appointment", 
  "additional_passengers": [
    {
      "space_type": "AMB",
      "count": 1
    }
  ]
}


POST Return Trip Sample

{
  "tp_api_key": "56e1015d588fgdpf448384b6b3a345dfgd564", 
  "trip_id": "ReturnSample-11", 
  "rider_id": "rider90", 
  "pickup": {
    "event_name": "Doe, Jane - Pickup Return",
    "event_comment": "Pick up 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,
      "latitude": 33.4799636 
    },
    "pickup_time": "2020-04-10 14:48:49.403",
    "phone_number": "520.234.2342"
  },
  "dropoff": {
    "event_name": "Doe, Jane - Dropoff 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, 
      "latitude": 33.5097911 
    },
    "phone_number": "502.234.2342"
  },
  "funding_source_name": "Broker ABC", 
  "space_type": "WCH", 
  "billable_distance": 4,
  "phone": "(623)-453-3453",
  "trip_type": "Return", 
  "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": "56e1015d588fgdpf448384b6b3a345dfgd564", 
  "trip_id": "WillcallSample-12", 
  "rider_id": "rider90", 
  "pickup": {
    "event_name": "Doe, Jane - Pickup Return",
    "event_comment": "Pick up 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,
      "latitude": 33.4799636 
    },
    "pickup_time": "2020-04-10 23:59",
    "phone_number": "520.234.2342"
  },
  "dropoff": {
    "event_name": "Doe, Jane - Dropoff 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, 
      "latitude": 33.5097911 
    },
    "phone_number": "502.234.2342"
  },
  "funding_source_name": "Broker ABC", 
  "space_type": "WCH", 
  "billable_distance": 4,
  "phone": "(623)-453-3453",
  "trip_type": "Willcall", 
  "additional_passengers": [
    {
      "space_type": "AMB",
      "count": 1
    }
  ]
}


Expected Responses

200 - Request was successful; Returns trip object.

400 - Bad Data; If Pickup Time is later than the Appointment time, for example.

401 - "You do not have access to this resource." Request was unsuccessful

500 - Unknown error; Contact MediRoutes.


Webhooks

Webhooks are a publisher subscriber model. API users subscribe to listen to changes in MediRoutes and MediRoutes publishes changes back to the subscriber in real time via an HTTP web request. They have a message—or payload—and are sent to a unique URL of the subscriber's choosing. 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 or any time a trip is created, the Trip GUID is returned

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
  2. Do not include sensitive information in the Call Back URL Headers. This is stored in the database in plain text.

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 <access token>” (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.