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.

PATCH SingleTrip with Properties Endpoint

Instead of posting an entire trip model like the other PATCH endpoint does, you can submit changes to individual properties in the trip.

Request

POST	{root_url}/v{version}/singletrip/withProperties

Parameter	Type	Description	Notes
trip	string	Property_to_change model. See model definition below	REQUIRED
version	int	API version; currently = "1"	REQUIRED
Authorization	string	bearer {access token}	REQUIRED

Model Definition

Parameter	Type	Description	Notes
key	string	The property to change	REQUIRED
value	string	The new value for the property	REQUIRED

The model is a key/value pair of strings. If changes are made to numeric values or date/time values, they must be submitted as a string value as well otherwise it will not parse.

The allowed properties (Keys) that can be changed are:

Key	Description	Example
pickup.event_name	The name of the pickup event	Doe, Jane - Pickup Appointment
pickup.complete_address	The complete pickup address on a single line	2882 N Scottsdale Rd, Scottsdale, AZ, 85257
pickup.event_location.location_name	The location name for the pickup event	Honor Health Scottsdale
pickup.event_location.address1	Pickup first address line	2822 N Scottsdale Rd
pickup.event_location.address2	Pickup second address line
pickup.event_location.city	Pickup city	Scottsdale
pickup.event_location.state	Pickup state	AZ
pickup.event_location.zip	Pickup zip	85257
pickup.event_location.latitude	Pickup latitude	33.4799636
pickup.event_location.longitude	Pickup longitude	-111.9287566
pickup.appt_time	Pickup appointment time
pickup.pickup_time	Pickup pickup time	2022-04-10 14:48:49.403
pickup.phone_number	Pickup phone number	5202342342
dropoff.event_name	The name of the dropoff event	Doe, Jane - Dropoff Appointment
dropoff.complete_address	The complete dropoff address on a single line	6606 W Camelback Rd Unit 123, Glendale, AZ, 85301
dropoff.event_location.location_name	The location name for the dropoff event	XYZ Retirement Community
dropoff.event_location.address1	Dropoff first address line	6606 W Camelback Rd
dropoff.event_location.address2	Dropoff second address line	Unit 123
dropoff.event_location.city	Dropoff city	Glendale
dropoff.event_location.state	Dropoff state	AZ
dropoff.event_location.zip	Dropoff zip	85301
dropoff.event_location.latitude	Dropoff latitude	33.5097911
dropoff.event_location.longitude	Dropoff longitude	-112.2035528
dropoff.appt_time	Dropoff appointment time	04/10/2022 3:00PM
dropoff.pickup_time	Dropoff pickup time
dropoff.phone_number	Dropoff phone number	5022342342
space_type	The space type required for the trip	AMB
billable_distance	The billable distance for the trip	4
trip_type	The trip type in an integer value between 1 and 3. 1 = Will Call Trip, 2 = Appointment Trip, 3 = Return Trip	2
caller	The caller for the trip	John Doe
additional_passengers	The additional passengers for the trip	AMB\|1

NOTE: Changes to Address fields in either the Pickup event or Dropoff event other than changes to the Latitude or Longitude will cause the address to get geocoded with the new changes and return the correct address in the payload.

Here is an example of how the submission payload should look for a single change to one of the properties:

{
 "trip_guid": "0c7e24aa-7ebf-457c-9e87-b8ec87fef40c",
 "tp_api_key": "56e1015d588fgdpf448384b6b3a345dfgd564",
 "properties_to_change": [{"Key": "pickup_zip", "Value": "85051"}]
}

Here is another example where multiple properties require changes:

{
 "trip_guid": "0c7e24aa-7ebf-457c-9e87-b8ec87fef40c",
 "tp_api_key": "56e1015d588fgdpf448384b6b3a345dfgd564",
 "properties_to_change": [
             {"Key": "pickup_zip", "Value": "85051"},
             {"Key": "pickup_phone_number", "Value": "6025551212"},
             {"Key": "dropoff_phone_number", "Value": "6025551313"}]
}

Additional passengers is the only property that is slightly different from the rest. It requires pipe delimited value that contains the space type and the count. It can also contain multiple passengers with different space types. If there is more than one space type required for additional passengers, then you will need to put a semicolon between each additional passenger value.

For example: If the trip requires one additional ambulatory passenger, the value would be “AMB|1”

{
 "trip_guid": "0c7e24aa-7ebf-457c-9e87-b8ec87fef40c",
 "tp_api_key": "56e1015d588fgdpf448384b6b3a345dfgd564",
 "properties_to_change": [{"Key": "additional_passengers", "Value": "AMB|1"}]
}

If the trip requires two additional passengers, one ambulatory and one wheelchair the value would be “AMB|1;WCH1”

{
 "trip_guid": "0c7e24aa-7ebf-457c-9e87-b8ec87fef40c",
 "tp_api_key": "56e1015d588fgdpf448384b6b3a345dfgd564",
 "properties_to_change": [{"Key": "additional_passengers", "Value": "AMB|1;WCH|1"}]
}

Expected Response Codes

Code	Description
200	Request was successful; API Key(s) and Funding Source(s) returned.
400	Missing or unaligned data. Error message will be returned with response
403	The API key used does not have access to this resource.
500	Unknown error; Contact MediRoutes.

POST SingleTrip Endpoint

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

Appointment Trips
Return Trips
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

Parameter	Type	Description	Notes
tp_api_key	string		REQUIRED
trip_id	string		REQUIRED
rider_id	string		REQUIRED
pickup	-
.event_name	string
.event_comment	string
.complete_address	string
.event_location	-
..location_name	string
..address1	string
..address2	string
..city	string
..state	string
..zip	string
..latitude	double		REQUIRED
..longitude	double		REQUIRED
.appt_time	datetime	format = "2020-06-11 14:48:49.403"
.pickup_time	datetime	format = "2020-06-11 14:48:49.403"
.phone_number	string
dropoff	-
.event_name	string
.event_comment	string
.complete_address	string
.event_location	-
..location_name	string
..address1	string
..address2	string
..city	string
..state	string
..zip	string
..latitude	double		REQUIRED
..longitude	double		REQUIRED
.appt_time	datetime	format = "2020-06-11 14:48:49.403"
.pickup_time	-	-	Read Only
.phone_number	string
funding_source_name	string		REQUIRED
space_type	string		REQUIRED
billable_distance	double	Distance 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.
phone	string
trip_type	string	"2" = Appointment, "3" = Return, "1" = Will Call	REQUIRED
additional_passengers	-
.space_type	string
.count	int	Typically AMB.

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 Response Codes

Code	Description
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.