Bookings

Receiving a booking from Karhoo

  1. Getting started
  2. Quotes
  3. Bookings
  4. Trip updates
  5. Settlements
  6. Testing

Booking a trip

Endpoint: POST https://supply-partner.com/trip

Similar to the Quotes step we will highlight the minimum set of information you'll need to process to fulfill a booking and then go through additional properties that we also offer.

{
  "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
  "external_info": {
    "fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
    "vehicle_type": "R6"
  }
  "origin": {
    "position": {
      "latitude": 40.6413111,
      "longitude": -73.7781391
    },
  },
  "destination": {
    "position": {
      "latitude": 40.7587711,
      "longitude": -73.9952016
    },
  },
  "passenger_count": 1,
  "passengers": [
    {
      "first_name": "Kurt",
      "last_name": "Godel",
      "phone_number": "+12121231234"
    }
  ]
}

Karhoo sends a booking request using quote_id, fleet_id and vehicle_type values that have been supplied by a previous quote response. These parameters are passed in the external_info object in the request body.

"external_info": {
    "fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
    "quote_id": "99864597614",
    "vehicle_type": "R6"
  }

📘

If you're a Fleet with their own custom DMS.

If your platform is a both a Dispatch Management System and a Fleet, where there is only a single fleet on the platform, then fleet_id can be omitted.

Minimal possible booking response

In the booking response we expect the trip object to be returned (check swagger definition). It is not required to set all the fields there though. Here is a minimal acceptance by our system trip object (no information about vehicle / driver etc).

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

Full Booking Request Example

🚧

Karhoo trip_id

Note here the trip_id is the Karhoo internal trip id for your reference, not the DMS trip_id that you may generate and use in the response.

{
  "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
  "date_scheduled": "2017-09-14T12:45:54Z",
  "date_scheduled_utc": 1505393154,
  "external_info": {
    "fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
    "quote_id": "99864597614",
    "vehicle_type": "R6"
  }
  "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"
    }
  },
  "comment": "I will have lots of luggage",
  "passenger_count": 1,
  "passengers": [
    {
      "first_name": "Kurt",
      "last_name": "Godel",
      "phone_number": "+12121231234"
    }
  ],
  "quote": {
    "id": "string",
    "type": "FIXED",
    "total": 2330,
    "currency": "USD"
  },
  "train_number": "string"
}

Reference

Service

API reference

Errors reference

Receive New Trips

[DMS Endpoint] Receive New Trips

Integration Errors

Troubleshooting

Some potential errors you might encounter are:

Error

Solution


What’s Next