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


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

GET{root_url}/v{version}/fundingsources/getFundingSourceById


ParameterTypeDescriptionNotes
api_keystring
REQUIRED
funding_source_idintId of the funding source REQUIRED
includeInactiveFundingSourcesBoolInclude removed funding sources
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED


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.

[
  "Data": [
    {
      "name": "000AAA",
      "account": "",
      "phone": "",
      "fax_number": "",
      "email": "",
      "is_payee": false,
      "address": {
        "address1": "123 main st",
        "address2": "",
        "city": "mesa",
        "state": "az",
        "zip": ""
      },
      "contact": {
        "primary_contact": {
          "first_name": "",
          "middle_name": "",
          "last_name": ""
        },
        "alternative_contact": {
          "first_name": "",
          "last_name": ""
        }
      },
      "options": {
        "mileage_charge_calculation_is_routed": true,
        "smartphone_options": {
          "require_passenger_signature_pickup": true,
          "require_passenger_signature_dropoff": false,
          "require_passenger_agreement": "",
          "require_driver_signature_pickup": false,
          "require_driver_signature_dropoff": false,
          "require_odometer": true,
          "display_cost_to_driver": false,
          "disable_display": false,
          "driver_cancel_deletes_charges": false
        },
        "other_options": {
          "copy_client_code_to_auth": false,
          "require_authorization": false
        }
      },
      "isActive": true
    }
]



Deactivate Funding Source By Id Endpoint

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


Request

DELETE{root_url}/v{version}/fundingsources/deactivateFundingSourceById


ParameterTypeDescriptionNotes
api_keystring
REQUIRED
funding_source_idintId of the funding source to deactivate.REQUIRED
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED


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.

[
  {
    "StatusCode": 200,
    "Message": "Funding Source [Test FS] has been successfully removed."
  }
]



Deactivate FundingSource Endpoint

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


Request

DELETE{root_url}/v{version}/fundingsources


ParameterTypeDescriptionNotes
api_keystring
REQUIRED
funding_source_namestringName of the funding source to deactivate.REQUIRED
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED



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.

[
  {
    "StatusCode": 200,
    "Message": "Funding Source [Test FS] has been successfully removed."
  }
]


Get Funding Sources Endpoint


Request

GET{root_url}/v{version}/fundingsources


ParameterTypeDescriptionNotes
api_keystring
REQUIRED
funding_source_namestringFunding source name. Provide to get the funding source with this name.
includeInactiveFundingSourcesbooleanInclude removed funding sources
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED


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.

[
  "Data": [
    {
      "name": "000AAA",
      "account": "",
      "phone": "",
      "fax_number": "",
      "email": "",
      "is_payee": false,
      "address": {
        "address1": "123 main st",
        "address2": "",
        "city": "mesa",
        "state": "az",
        "zip": ""
      },
      "contact": {
        "primary_contact": {
          "first_name": "",
          "middle_name": "",
          "last_name": ""
        },
        "alternative_contact": {
          "first_name": "",
          "last_name": ""
        }
      },
      "options": {
        "mileage_charge_calculation_is_routed": true,
        "smartphone_options": {
          "require_passenger_signature_pickup": true,
          "require_passenger_signature_dropoff": false,
          "require_passenger_agreement": "",
          "require_driver_signature_pickup": false,
          "require_driver_signature_dropoff": false,
          "require_odometer": true,
          "display_cost_to_driver": false,
          "disable_display": false,
          "driver_cancel_deletes_charges": false
        },
        "other_options": {
          "copy_client_code_to_auth": false,
          "require_authorization": false
        }
      },
      "isActive": true
    }
]


Update Funding Source Endpoint


Request

PATCH{root_url}/v{version}/fundingsources


ParameterTypeDescriptionNotes
modelstringSee model definition belowREQUIRED
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED


Model Definition

ParameterTypeDescriptionNotes
api_keystring
REQUIRED
funding_source-

.namestringFunding Source NameREQUIRED
.accountstring

.phonestring

.fax_numberstring

.emailstring

.isPayeeboolean
REQUIRED
.address-

..address1string

..address2string

..citystring

..statestring

..zipstring

.contact-

..primary_contact-

...first_namestring

...middle_namestring

...last_namestring

..alternative_contact-

...first_namestring

...middle_namestring

...last_namestring

.options-

..mileage_charge_calculation_is_routedboolean

..smartphone_options-

...require_passenger_signature_pickupboolean

...require_passenger_signature_dropoffboolean

...require_passenger_agreementboolean

...require_driver_signature_pickupboolean

...require_driver_signature_dropoffboolean

...require_odometerboolean

...display_cost_to_driverboolean

...disable_displayboolean

...driver_cancel_deletes_chargesboolean

..other_options-

...copy_client_code_to_authboolean

...require_authorizationboolean

.isActiveboolean



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

{
  "api_key": "56e1015d588fgdpf448384b6b3a345dfgd564",
  "funding_source": {
    "name": "Test Funding Source",
    "account": "",
    "phone": "",
    "fax_number": "",
    "email": "",
    "is_payee": false,
    "address": {
      "address1": "123 Main St",
      "address2": "",
      "city": "Mesa",
      "state": "AZ",
      "zip": ""
    },
    "contact": {
      "primary_contact": {
        "first_name": "",
        "middle_name": "",
        "last_name": ""
      },
      "alternative_contact": {
        "first_name": "",
        "middle_name": "",
        "last_name": ""
      }
    },
    "options": {
      "mileage_charge_calculation_is_routed": true,
      "smartphone_options": {
        "require_passenger_signature_pickup": true,
        "require_passenger_signature_dropoff": true,
        "require_passenger_agreement": "",
        "require_driver_signature_pickup": true,
        "require_driver_signature_dropoff": true,
        "require_odometer": true,
        "display_cost_to_driver": true,
        "disable_display": true,
        "driver_cancel_deletes_charges": true
      },
      "other_options": {
        "copy_client_code_to_auth": true,
        "require_authorization": true
      }
    },
    "isActive": true
  }
}


Create Funding Source Endpoint


Request

POST{root_url}/v{version}/fundingsources


ParameterTypeDescriptionNotes
modelstringSee model definition belowREQUIRED
versionintAPI version; currently = "1"REQUIRED
Authorizationstringbearer {access token}REQUIRED


Model Definition

ParameterTypeDescriptionNotes
api_keystring
REQUIRED
funding_source-

.namestringFunding Source NameREQUIRED
.accountstring

.phonestring

.fax_numberstring

.emailstring

.isPayeeboolean
REQUIRED
.address-

..address1string

..address2string

..citystring

..statestring

..zipstring

.contact-

..primary_contact-

...first_namestring

...middle_namestring

...last_namestring

..alternative_contact-

...first_namestring

...middle_namestring

...last_namestring

.options-

..mileage_charge_calculation_is_routedboolean

..smartphone_options-

...require_passenger_signature_pickupboolean

...require_passenger_signature_dropoffboolean

...require_passenger_agreementboolean

...require_driver_signature_pickupboolean

...require_driver_signature_dropoffboolean

...require_odometerboolean

...display_cost_to_driverboolean

...disable_displayboolean

...driver_cancel_deletes_chargesboolean

..other_options-

...copy_client_code_to_authboolean

...require_authorizationboolean

.isActive