Trip updates

Endpoint: GET https://supply-partner.com/trip?trip_id=a96f4513-7846-4f9b-bb23-1d2f5247b493&external_trip_id=325486921

Supported URI Parameters	Description
trip_id	Karhoo's trip id
external_trip_id	The trip id you use to identify a booking. This is also visible to the passenger
external_fleet_id	The fleet id you use to identify a fleet on your platform
external_account_id	Used to specify an account with special SLAs or pricing

This is a DMS endpoint the Karhoo Platform polls for trip updates to track the driver, trip status and final fare.

The following example represents the bare minimum of trip tracking but does not offer the best passenger experience and can result in more passengers calling your main office for updates.

{
    "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
    "external_info": {
        "trip_id": "55555"
        "fleet_id": "12333"
    },
    "state": {
        "state": 3
    }
}

States Mapping

In the trip object above you see the state object with the state field. Here is a human-readable form of the states mappings:

"STATE_NOT_SET"
"NEW"
"REQUESTED"
"CONFIRMED"
"ALLOCATED"
"DRIVER_EN_ROUTE”
"APPROACHING"
"ARRIVED"
"PASSENGER_ON_BOARD"
"COMPLETED"
"CANCELLED_BY_USER"
"CANCELLED_BY_DISPATCH"
"CANCELLED_BY_KARHOO"

For cancelled trips we would like to also receive the cancellation reason as part of the state object:

"state": {
        "state": "CANCELLED_BY_DISPATCH",
        "cancellation_reason": "OTHER_DISPATCH_REASON",
    }

Cancellation reasons in human readable form:

"REASON_NOT_SET"
"OTHER_DISPATCH_REASON"
"REQUESTED_BY_PASSENGER"
"PASSENGER_DIDNT_SHOW_UP"
"DRIVER_CANCELED"
"FLEET_CANCELLED"
"DISPATCH_CANCELLED"
"NO_AVAILABILITY_IN_THE_AREA"
"NO_FEE"

Vehicle & Driver

Let’s say that trip time is coming and you already have a vehicle assigned. Minimal acceptable payload in this case is:

{
    "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
    "external_info": {
        "trip_id": "55555"
        "fleet_id": "12333"
    },
    "state": {
        "state":"ALLOCATED"
    },
    "vehicle": {
        "description": "BMW 5-series",
        "driver": {
           "first_name": "Aliaksandr",
           "phone_number": "+12121231234",
        },
    }
}

🚧
E.164 Formatted Phone Number
Please note that the driver phone number should adhere to the E.164 standard of formatting.

Default polling intervals

Karhoo will poll for updates on trip details with the following frequencies. These frequencies are a platform configuration option that can be discussed more by contacting the Karhoo team.

	Conditions	Polling frequency
PRE-BOOK
	greater than 3 hours before pickup time	1 hour
	1 hour before pickup time	5 minutes
	10 minutes before pickup time	30 seconds
	Up to 5 minutes after pickup time	30 seconds
	Up to 30 minutes after pickup time	1 minute
	Up to 1 hour after pickup time	5 minutes
	After 1 hour after pickup time	1 hour
ASAP
	Default	5 seconds
ONCE COMPLETED
	Less than 2 hours since polling started	15 hours
	More than 28 hours since polling started	1 minute
	Default	12 hours

Example response

{
  "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
  "external_info": {
    "fleet_id": "64",
    "fleet_phone_number": "+12121231234",
    "trip_id": "325486921",
    "quote_id": "99864597614",
    "vehicle_type": "R4",
    "fare_id": "2184XVYT23"
  },
  "date_scheduled": "2017-09-14T12:45:54.000Z",
  "date_scheduled_utc": 1505393154,
  "origin": {
    "position": {
      "latitude": 40.6413111,
      "longitude": -73.7781391
    },
    "address": {
      "display_address": "John F. Kennedy International Airport, New York, US",
      "building_number": "",
      "street_name": "",
      "city": "Queens",
      "region": "NY",
      "postal_code": "11430",
      "country_code": "US"
    },
    ,
    "airport": {
      "airport_code": "JFK",
      "flight_number": "B67015",
      "pickup_type": "MEET_AND_GREET"
    }
  },
  "destination": {
    "position": {
      "latitude": 40.7587711,
      "longitude": -73.9952016
    },
    "address": {
      "display_address": "407 W 42nd St New York, NY, 10036",
      "building_number": "407",
      "street_name": "W 42nd St",
      "city": "New York",
      "region": "NY",
      "postal_code": "10036",
      "country_code": "US"
    }
  },
  "state": {
    "state_change_details": "Driver 25 allocated 2 hours prior to pickup",
    "state": "ALLOCATED"
  },
  "vehicle": {
    "vehicle_class": "MPV",
    "vehicle_registration": "EVY2323",
    "position": {
      "latitude": 51.5086692,
      "longitude": -0.1375291
    },
    "direction": {
      "kph": 23,
      "heading": 45
    },
    "eta": {
      "distance": 160,
      "minutes": 5
    },
    "description": "Black Lincoln Town Car",
    "driver": {
      "first_name": "Kurt",
      "last_name": "Godel",
      "phone_number": "+12121231234",
      "photo_url": "https://raw.githubusercontent.com/encharm/Font-Awesome-SVG-PNG/master/black/png/22/user.png",
      "photo_content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAABlBMVEXMzMyWlpYU2uzLAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAACklEQVQImWNgAAAAAgAB9HFkpgAAAABJRU5ErkJggg==",
      "license_number": "E892321567"
    },
    "external_info": {
      "vehicle_type": "R4",
      "driver_id": "25",
      "vehicle_id": "404"
    }
  },
  "comment": "do not beep car horn please",
  "passenger_count": 1,
  "passengers": [
    {
      "first_name": "Kurt",
      "last_name": "Godel",
      "phone_number": "+12121231234"
    }
  ],
  "fare": {
    "id": "string",
    "type": "FIXED",
    "total": 3530,
    "currency": "USD",
    "breakdown": [
      {
        "name": "BASE_RATE",
        "value": 2330,
        "vat_percent": 10
      },
      {
        "name": "WAITING_TIME",
        "value": 500,
        "vat_percent": 10
      },
      {
        "name": "TOLLS",
        "value": 700,
        "vat_percent": 10
      }
    ]
  }
}

Trip cancellation

Endpoint: DELETE https://supply-partner.com/trip?trip_id=3413241&external_trip_id=2WEKaVNO

Karhoo’s trip_id and your trip id external_trip_id are passed in as query parameters.

If there are any cancellation charges, please respond with a fare object and its breakdown with the cancellation confirmation. The trip state should also be set as cancelled.

"fare": {
    "id": "string",
    "type": "FIXED",
    "total": 3530,
    "currency": "USD",
    "breakdown": [
        {
        "name": "BASE_RATE",
        "value": 2330,
        "vat_percent": 10
        },
        {
        "name": "WAITING_TIME",
        "value": 500,
        "vat_percent": 10
        },
        {
        "name": "CANCELLATION_FEE",
        "value": 700,
        "vat_percent": 10
        }
    ]
}

Reference

Service	API reference	Errors reference
Update Trips	Update Trip	Integration Errors
Trip Details	Provide Trip Details	Integration Errors

Troubleshooting

Some potential errors you might encounter are:

Error	Solution

Trip updates

States Mapping

Vehicle & Driver

🚧E.164 Formatted Phone Number

Default polling intervals

Example response

Trip cancellation

Reference

Troubleshooting

🚧
E.164 Formatted Phone Number