{"openapi":"3.0.0","x-global-options":{"go_package":"github.com/karhoo/api-v1-supply/proto/src/go/dispatch"},"x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"description":"\nThe Karhoo Supply API allows Dispatch Management Systems to integrate directly into the Karhoo Platform.\nThe process of integrating consists of writing webhooks directly into your Dispatch Management System where Karhoo can request quotes, send new trips and check on the progress of active trips.","version":"v1.0","title":"Supply API 1.0","contact":{"email":"api@karhoo.com"},"x-hugo-values":{"tags":["api"],"categories":["dispatch"],"public":true}},"paths":{"/availability":{"post":{"tags":["[Push] Availability"],"summary":"Stream fleet wide vehicle availability to Karhoo","description":"Send your fleet availability to Karhoo in real-time. Actively pushing to Karhoo eliminates the load Karhoo would otherwise put on your systems when polling for availability. The alternative is that you can implement this API call as an endpoint within your DMS which Karhoo will poll frequently to request availability.","operationId":"availabilityPushToKarhoo","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityPushRequest"}}},"description":"request body","required":true},"responses":{"201":{"description":"Request accepted"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}},"security":[{"Bearer":[]}]}},"/trip/status":{"post":{"tags":[" [Push] Trip Status"],"summary":"DMS Trip Status Push to Karhoo","description":"Send trip updates to Karhoo in real-time. Actively pushing to Karhoo eliminates the load Karhoo would otherwise put on your systems by polling for updates.","requestBody":{"$ref":"#/components/requestBodies/Trip"},"responses":{"201":{"description":"Request accepted"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}},"security":[{"Bearer":[]}]}},"/trip/document/":{"post":{"tags":[" [Push] Trip Document"],"summary":"DMS Trip document push to Karhoo","description":"Send a document for a trip to Karhoo. Should only be used with fully trusted flow. ","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushTripDocumentRequest"}}},"description":"request body","required":true},"responses":{"201":{"description":"Request accepted"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}},"security":[{"Bearer":[]}]}},"/dispatch-system/trip":{"post":{"tags":["[DMS Endpoint] Receive New Trips"],"summary":"DMS hosted API endpoint for receiving Karhoo trip bookings","description":"This endpoint must be hosted within the Dispatch Managment System's platform to listen for new Karhoo Bookings in the described format.","parameters":[{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrip"}}},"description":"request body","required":true},"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trip"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}},"get":{"tags":["[DMS Endpoint] Provide Trip Details"],"summary":"DMS Hosted endpoint to respond to Karhoo Trip Detail requests","description":"This endpoint must be hosted within the DMS platform to listen for trip detail requests in the described format.","parameters":[{"name":"trip_id","in":"query","required":true,"description":"The Karhoo trip id","schema":{"type":"string"}},{"name":"external_trip_id","in":"query","description":"DMS trip id","required":true,"schema":{"type":"string"}},{"name":"external_fleet_id","in":"query","description":"DMS fleet id","required":true,"schema":{"type":"string"}},{"name":"external_account_id","in":"query","description":"A booking account id - allows fleets to offer difference services and SLAs to the marketplace","required":false,"schema":{"type":"string"}},{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trip"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}},"delete":{"tags":["[DMS Endpoint] Cancel Trip"],"summary":"DMS Hosted endpoint to respond to Karhoo Trip Cancellation requests","description":"This endpoint must be hosted within the DMS platform to listen for trip detail requests in the described format.","parameters":[{"name":"trip_id","in":"query","required":true,"description":"The Karhoo trip id","schema":{"type":"string"}},{"name":"external_trip_id","in":"query","description":"DMS trip id","required":true,"schema":{"type":"string"}},{"name":"external_fleet_id","in":"query","description":"DMS fleet id","required":true,"schema":{"type":"string"}},{"name":"external_account_id","in":"query","description":"A booking account id - allows fleets to offer difference services and SLAs to the marketplace","required":false,"schema":{"type":"string"}},{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trip"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}},"put":{"tags":["[DMS Endpoint] Update Trip"],"summary":"DMS Hosted API endpoint to respond to Karhoo Trip Update requests to your DMS platform.","description":"This endpoint must be hosted within the DMS platform to listen for trip detail requests in the described format.","parameters":[{"name":"trip_id","in":"query","required":true,"description":"The Karhoo trip id","schema":{"type":"string"}},{"name":"external_trip_id","in":"query","description":"DMS trip id","required":true,"schema":{"type":"string"}},{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC hash of your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/Trip"},"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trip"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}}},"/dispatch-system/quote":{"post":{"tags":["[DMS Endpoint] Quote Request"],"summary":"DMS hosted API endpoint for responding to quote requests","description":"This endpoint must be hosted within the Dispatch Managment System's platform to listen for Karhoo Quote requests in the described format.","parameters":[{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"description":"request body","required":true},"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}}},"/dispatch-system/eta":{"post":{"tags":["[DMS Endpoint] ETA Request"],"summary":"DMS hosted API endpoint for responding to ETA requests","description":"This endpoint must be hosted within the Dispatch Managment System's platform to listen for Karhoo ETA requests in the described format.","parameters":[{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETARequest"}}},"description":"request body","required":true},"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ETAResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}}},"/dispatch-system/availability":{"post":{"tags":["[DMS Endpoint] Availability Request"],"summary":"Karhoo Availability Request to DMS","description":"This endpoint must be hosted within the Dispatch Managment System's platform to listen for Karhoo Availability requests in the described format.","parameters":[{"in":"header","name":"x-karhoo-request-signature","required":true,"description":"HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityRequest"}}},"description":"request body","required":true},"responses":{"200":{"description":"Success response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided"},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request"}}}},"/healthcheck":{"get":{"tags":["Healthcheck"],"summary":"Health check endpoint","description":"This endpoint is hosted by Karhoo for use by Dispatch Management Systems and it should be hosted as a DMS Endpoint for use by Karhoo.\nIt should check if internal resources like databases or caches are healthy and respond with a HTTP `204` status. Anything else would signal the required services as being down.","responses":{"204":{"description":"Success response, no content. Service is ok"},"500":{"description":"Service is down."}}}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/supply"}],"components":{"requestBodies":{"Trip":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trip"}}},"description":"request body","required":true}},"securitySchemes":{"Bearer":{"description":"For accessing the API a valid JWT token must be passed in all the queries in the 'Authorization' header.\nA valid JWT token is generated by the v1/auth API here (https://docs.karhoo.com/v1/auth/)\nThe following syntax must be used in the 'Authorization' header :\n`Bearer: xxxxxx.yyyyyyy.zzzzzz`","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ErrorDetails":{"type":"object","description":"Additional information about the error (such as which field failed validation)","properties":{"name":{"type":"string","description":"DEPRECATED, please use `message`"},"message":{"type":"string","description":"details of error encountered"},"detail":{"type":"string","description":"error details"}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Main error message"},"status":{"type":"number","format":"int32","description":"DEPRECATED, this will be removed in the future"},"code":{"type":"string","description":"Internally generated code for this error"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}},"errors":{"type":"array","description":"DEPRECATED, please use `details`","items":{"$ref":"#/components/schemas/ErrorDetails"}}}},"ExternalInfo":{"type":"object","properties":{"fleet_id":{"type":"string","description":"DMS Fleet Id","example":"64"},"fleet_phone_number":{"type":"string","description":"E.164 formatted phone number of the fleet https://en.wikipedia.org/wiki/E.164","example":"+12121231234"},"trip_id":{"type":"string","description":"DMS Trip Id","example":"325486921"},"quote_id":{"type":"string","description":"DMS Quote Id","example":"99864597614"},"vehicle_type":{"type":"string","description":"DMS Vehicle type","example":"R4"},"driver_id":{"type":"string","description":"DMS Driver Id","example":"25"},"vehicle_id":{"type":"string","description":"DMS Vehicle Id","example":"404"},"fare_id":{"type":"string","description":"Unique DMS id for fare that should be charged","example":"2184XVYT23"},"account_id":{"type":"string","description":"The ID that allows fleets to offer different services and SLAs to the marketplace","example":"fixed-fare-812"}}},"Direction":{"type":"object","properties":{"kph":{"type":"number","description":"Kilometers Per Hour","example":23},"heading":{"type":"number","description":"degress clockwise from due north","example":45}}},"Driver":{"type":"object","required":["first_name","phone_number"],"properties":{"first_name":{"type":"string","description":"First name of driver.","pattern":"^[^!@€£#$%^&*()+={}\\[\\]:;|?±§_~<>\\\\]*$","maxLength":50,"example":"Kurt"},"last_name":{"type":"string","description":"Last name of driver.","pattern":"^[^!@€£#$%^&*()+={}\\[\\]:;|?±§_~<>\\\\]*$","maxLength":50,"example":"Godel"},"phone_number":{"type":"string","description":"E.164 formatted phone number of the driver https://en.wikipedia.org/wiki/E.164","example":"+12121231234"},"photo_url":{"type":"string","description":"Photo URL of the driver. The image should have a 1:1 aspect ratio and can be a gif, jpg or png.","example":"https://raw.githubusercontent.com/encharm/Font-Awesome-SVG-PNG/master/black/png/22/user.png"},"photo_content":{"type":"string","description":"Driver photo encoded as bas64 string. The image should have a 1:1 aspect ratio and can be a gif, jpg or png.","example":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAABlBMVEXMzMyWlpYU2uzLAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAACklEQVQImWNgAAAAAgAB9HFkpgAAAABJRU5ErkJggg=="},"license_number":{"type":"string","description":"License as required by local regulation.","example":"E892321567"}}},"Position":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double","description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","example":51.5086692},"longitude":{"type":"number","format":"double","description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","example":-0.1375291}}},"Address":{"type":"object","properties":{"display_address":{"type":"string","description":"Full address string","example":"407 W 42nd St New York, NY, 10036"},"building_number":{"type":"string","example":"407"},"street_name":{"type":"string","example":"W 42nd St"},"city":{"type":"string","example":"New York"},"region":{"type":"string","example":"NY"},"postal_code":{"type":"string","example":"10036"},"postal_code_ext":{"type":"string"},"country_code":{"type":"string","description":"Two digit country code","example":"US"}}},"PickupType":{"type":"string","description":"If being picked up at an Airport, the pickup type\n \n - PICKUP_TYPE_NOT_SET - Empty pickup type for Airport
\n - PICKUP_TYPE_MEET_AND_GREET - The driver will meet the passenger inside the terminal
\n - PICKUP_TYPE_CURBSIDE - The driver will wait curbside at a designated pickup point
\n - PICKUP_TYPE_STANDBY - The passenger must call when they are ready with their luggage
\n
\n","enum":["PICKUP_TYPE_NOT_SET","PICKUP_TYPE_MEET_AND_GREET","PICKUP_TYPE_CURBSIDE","PICKUP_TYPE_STANDBY"]},"Airport":{"type":"object","description":"__DEPRECATED__ Please use `details`","properties":{"airport_code":{"type":"string","description":"Airport IATA code","example":"JFK"},"airline_code":{"type":"string","description":"Airline code","example":"B6"},"terminal":{"type":"string","description":"Airport terminal","example":"1"},"flight_number":{"type":"string","description":"Flight Number","example":"7015"},"pickup_type":{"$ref":"#/components/schemas/PickupType"}}},"DetailsType":{"type":"string","description":"A secondary POI type for more detailed categorization\n - NOT_SET_DETAILS_TYPE\n - AIRPORT\n - TRAIN_STATION\n","enum":["NOT_SET_DETAILS_TYPE","AIRPORT","TRAIN_STATION","METRO_STATION"],"example":"AIRPORT"},"Details":{"type":"object","description":"Defines additional properties of a Location","properties":{"iata":{"type":"string","description":"if Location is an Airport this is its IATA code","example":"LHR"},"terminal":{"type":"string","example":5},"type":{"$ref":"#/components/schemas/DetailsType"}}},"MeetingPointType":{"type":"string","description":"If being picked up at an Airport, the pickup type\n\n - MEETING_POINT_TYPE_DEFAULT: Standard driver behavior for pickup or dropoff
\n - PICK_UP: This is a special pick up point for this location
\n - DROP_OFF: This is a special dropoff up point for this location
\n - MEET_AND_GREET: Usually when the driver will meet the passenger with a greeting sign
\n - CURB_SIDE: The driver will wait curbside at a designated pickup point
\n - STAND_BY: The passenger must call when they are ready. Usually with their luggage when an airport
\n
\n","enum":["MEETING_POINT_TYPE_NOT_SET","MEETING_POINT_TYPE_DEFAULT","PICK_UP","DROP_OFF","MEET_AND_GREET","CURB_SIDE","STAND_BY"]},"LatLong":{"type":"object","description":"Specifies a geographic location in terms of its Latitude and Longitude. For address autocompletion this location is used as bias to produce relevant Place IDs.","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double","description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","example":51.47},"longitude":{"format":"double","type":"number","description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","example":0.4543}}},"MeetingPoint":{"type":"object","description":"Specifies a geographic location in terms of its Latitude and Longitude","required":["position","type"],"properties":{"position":{"$ref":"#/components/schemas/LatLong"},"instructions":{"type":"string","description":"The meeting point instructions","example":"London Heathrow Airport, Terminal 5 Arrivals"},"type":{"$ref":"#/components/schemas/MeetingPointType"}}},"Location":{"type":"object","required":["position"],"properties":{"name":{"type":"string"},"google_place_id":{"type":"string","description":"A Google Places ID for the location","example":"Ei4xNCBQaWNjYWRpbGx5IENpcmN1cywgU29obywgTG9uZG9uIFcxRCA3RVQsIFVL"},"fleet_place_id":{"type":"string","description":"ID of the POI that is recognised by your fleet or dispatch. You need to configure the POI in order for this field to be set","example":"782295f3-4f0a-4e4a-ba58-87147f89b531"},"karhoo_place_id":{"type":"string","description":"If this place is a Karhoo POI, this field will be set","example":"532295f3-4f0a-4e4a-ba58-87147f89b357"},"comment":{"type":"string","description":"Location specific comment"},"position":{"$ref":"#/components/schemas/Position"},"address":{"$ref":"#/components/schemas/Address"},"airport":{"$ref":"#/components/schemas/Airport"},"details":{"$ref":"#/components/schemas/Details"},"meeting_point":{"$ref":"#/components/schemas/MeetingPoint"}}},"ETA":{"type":"object","properties":{"distance":{"type":"number","format":"double","description":"Distance in meters","example":160},"minutes":{"type":"number","format":"double","description":"Estimated Time of Arrival","example":5}}},"VehicleState":{"type":"string","description":"Status of the vehicle
\n \n - NOT_SET
\n - AVAILABLE
\n - UNAVAILABLE
\n
\n","enum":["NOT_SET","AVAILABLE","UNAVAILABLE"]},"Vehicle":{"type":"object","properties":{"vehicle_class":{"type":"string","description":"Karhoo vehicle classification\n \n - EXEC
\n - LUX
\n - MOTO
\n - MPV
\n
\n This field is for information purposed only and will change over time. It is only set by Karhoo.\n","example":"MPV"},"vehicle_registration":{"type":"string","description":"The legal registration of the vehicle","example":"EVY2323"},"position":{"$ref":"#/components/schemas/Position"},"direction":{"$ref":"#/components/schemas/Direction"},"eta":{"$ref":"#/components/schemas/ETA"},"description":{"type":"string","description":"Additional vehicle information","example":"Black Lincoln Town Car"},"make":{"type":"string","description":"Vehicle brand","example":"BMW"},"model":{"type":"string","description":"Vehicle model","example":"5-series"},"colour":{"type":"string","description":"Karhoo vehicle color\n \n - COLOUR_NOT_SET
\n - BLACK
\n - BLUE
\n - BROWN
\n - GOLD
\n - GRAY
\n - GREEN
\n - ORANGE
\n - PURPLE
\n - RED
\n - SILVER
\n - TAN
\n - WHITE
\n - YELLOW
\n
\n","enum":["COLOUR_NOT_SET","BLACK","BLUE","BROWN","GOLD","GRAY","GREEN","ORANGE","PURPLE","RED","SILVER","TAN","WHITE","YELLOW"],"example":"Black"},"state":{"$ref":"#/components/schemas/VehicleState"},"driver":{"$ref":"#/components/schemas/Driver"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"}}},"FareComponent":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of fare breakdown line item.\nThis is not an expansive list, more fare components can be added at request.\n \n - BASE_RATE
\n - TOLLS
\n - MEET_AND_GREET
\n - FUEL_SURCHARGE
\n - SERVICE_CHARGE
\n - GRATUITY
\n - PARKING
\n - STOP_CHARGE
\n - WAITING_TIME
\n - CANCELLATION_FEE
\n - WORKERS_COMP
\n
\n","example":"BASE_RATE"},"value":{"type":"integer","example":2330,"description":"A positive integer in the smallest unit the currency supports (pence, cents, etc).\n 2300 for $23.3\n 100 for ¥100 which is a non-decimal currency no need to multiply by 100.\nA value MUST be supplied."},"vat_percent":{"type":"integer","example":10,"description":"The vat percent for this fare line."},"vat_decimal_places":{"type":"integer","example":3,"description":"The number of decimal places that Karhoo should take into account for vat_percent. If vat_percent has no\ndecimal places, ignore this field. Ex.: For a vat_percent of 20.374 set vat_decimal_places to 3 and\nvat_percent to 20374.\n"},"tax_amount":{"type":"number","description":"Internal use only."},"uplift_percent":{"type":"number","description":"Internal use only."}}},"FareType":{"type":"string","description":"The status of the Trip Request\n \n - FARE_TYPE_NOT_SET - A null status. Never use this.
\n - FIXED - The fare was quoted at a fixed price.
\n - METERED - The fare was quoted as metered.
\n
\n","enum":["FARE_TYPE_NOT_SET","FIXED","METERED"],"example":"FIXED"},"Fare":{"type":"object","required":["total","currency"],"properties":{"id":{"type":"string","description":"Karhoo Id"},"type":{"$ref":"#/components/schemas/FareType"},"total":{"type":"integer","example":2330,"description":"A positive integer in the smallest unit the currency supports (pence, cents, etc).
\n
2300 for $23.3\n
100 for ¥100 which is a non-decimal currency no need to multiply by 100.\n"},"currency":{"type":"string","maxLength":3,"description":"Currency code formatted according to [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)","example":"USD"},"breakdown":{"type":"array","description":"The price breakdown. The breakdown components should sum to the total.","items":{"$ref":"#/components/schemas/FareComponent"}},"is_fare_final":{"type":"boolean","description":"flag to specify if fare is final fare."}}},"Passenger":{"type":"object","required":["last_name","phone_number"],"properties":{"first_name":{"type":"string","description":"First name of passenger.","pattern":"^[^!€£#$%^&*()+={}\\[\\]:;|?±§_~<>\\\\]*$","maxLength":50,"example":"Kurt"},"last_name":{"type":"string","description":"Last name of passenger.","pattern":"^[^!@€£#$%^&*()+={}\\[\\]:;|?±§_~<>\\\\]*$","maxLength":50,"example":"Godel"},"phone_number":{"type":"string","description":"E.164 formatted phone number of the passenger https://en.wikipedia.org/wiki/E.164","example":"+12121231234"}}},"CancellationReason":{"type":"string","description":"The trip cancellation reason\n \n - REASON_NOT_SET - A null status. Never use this.
\n - OTHER_DISPATCH_REASON - Other reason
\n - REQUESTED_BY_PASSENGER - The passenger called to cancel
\n - PASSENGER_DIDNT_SHOW_UP - Passenger No Show
\n - DRIVER_CANCELED - Driver bailed out
\n - FLEET_CANCELLED - Operator cancelled
\n - DISPATCH_CANCELLED - System cancelled
\n - NO_AVAILABILITY_IN_THE_AREA - Unable to service trip
\n - NO_FEE - Cancelled without a cancellation fee
\n
\n","enum":["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"]},"State":{"type":"string","description":"The status of the Trip Request\n \n - NOT_SET - A null status. Never use this.
\n NEW - DEPRECATED, Never use this - Initial state of new bookings from Karhoo.REQUESTED - DEPRECATED, Never use this - You have received the trip and will service it.- CONFIRMED - Send this once you have saved the reservation information successfully.
\n - ALLOCATED - A driver has been assigned to the trip.
\n - DRIVER_EN_ROUTE - The driver is on their way to trip origin.
\n - APPROACHING - The driver is nearby the trip origin.
\n - ARRIVED - The driver has arrived at the pickup and is waiting for the passenger.
\n - PASSENGER_ON_BOARD - The passenger has been picked up and is on board.
\n - COMPLETED - The passenger has been dropped off.
\n - CANCELLED_BY_USER - The passenger has cancelled trip.
\n - CANCELLED_BY_DISPATCH - You have decline to service this trip.
\n - CANCELLED_BY_KARHOO - Karhoo has cancelled the trip.
\n
\n","enum":["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"],"example":"ALLOCATED"},"StateDetails":{"type":"string","description":"Additional information about the state\n \n - FOLLOW_ON - Signifies the driver is completing a follow up trip, use only when state is DRIVER_EN_ROUTE and unset when driver is en route to passenger
\n
\n","enum":["FOLLOW_ON"]},"TripState":{"type":"object","description":"Information about the trup state","properties":{"state_change_details":{"type":"string","description":"Dynamic description of state change","example":"Driver 25 allocated 2 hours prior to pickup"},"state":{"$ref":"#/components/schemas/State"},"cancellation_reason":{"$ref":"#/components/schemas/CancellationReason"},"is_fare_final":{"type":"boolean","description":"DEPRECATED, please use is fare final inside Fare object instead"},"state_details":{"$ref":"#/components/schemas/StateDetails"}}},"CreateTripExternalInfo":{"type":"object","properties":{"vehicle_type":{"type":"string","description":"DMS Vehicle type","example":"R4"},"fleet_id":{"type":"string","description":"DMS Fleet Id","example":"64"},"quote_id":{"type":"string","description":"DMS Quote Id","example":"99864597614"},"account_id":{"type":"string","description":"The ID that allows fleets to offer different services and SLAs to the marketplace","example":"fixed-fare-812"}}},"CreateTrip":{"type":"object","required":["origin","destination","trip_id","external_info"],"properties":{"trip_id":{"type":"string","description":"Karhoos unqiue reference for a trip","example":"a96f4513-7846-4f9b-bb23-1d2f5247b493"},"partner_trip_id":{"type":"string","description":"Trip Reference Id provided by Karhoo Demand Partners","example":"4f9b-bb23"},"date_scheduled":{"type":"string","description":"Date should be specified in ISO 8601 Date Time format with the correct timezone for the origin, leave empty for ASAP booking","example":"2024-04-18T14:27:22.063Z"},"date_scheduled_utc":{"type":"integer","format":"int64","description":"UNIX Timestamp for scheduled pickup time, Represents seconds of UTC time since Unix epoch","example":1505393154},"external_info":{"$ref":"#/components/schemas/CreateTripExternalInfo"},"origin":{"$ref":"#/components/schemas/Location"},"destination":{"$ref":"#/components/schemas/Location"},"comment":{"type":"string","description":"Passenger entered notes for the trip","example":"do not beep car horn please"},"passenger_count":{"type":"number","description":"number of passengers","example":1},"passengers":{"type":"array","description":"passengers for the trip, this is optional","items":{"$ref":"#/components/schemas/Passenger"}},"quote":{"$ref":"#/components/schemas/Fare"},"train_number":{"type":"string","maxLength":15,"description":"the train number"},"flight_number":{"type":"string","description":"the flight number"},"meta":{"type":"object","description":"Additional meta data for the trip","additionalProperties":{"type":"string"}}}},"Trip":{"type":"object","properties":{"trip_id":{"type":"string","description":"Karhoo's unqiue reference for a trip","example":"a96f4513-7846-4f9b-bb23-1d2f5247b493"},"partner_trip_id":{"type":"string","description":"Trip Reference Id provided by Karhoo Demand Partners","example":"4f9b-bb23"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"},"date_scheduled":{"type":"string","description":"Date should be specified in ISO 8601 Date Time format with the correct timezone for the origin, leave empty for ASAP booking","example":"2024-04-18T14:27:22.063Z"},"date_scheduled_utc":{"type":"integer","format":"int64","description":"UNIX Timestamp for scheduled pickup time, Represents seconds of UTC time since Unix epoch","example":1505393154},"origin":{"$ref":"#/components/schemas/Location"},"destination":{"$ref":"#/components/schemas/Location"},"state":{"$ref":"#/components/schemas/TripState"},"vehicle":{"$ref":"#/components/schemas/Vehicle"},"comment":{"type":"string","description":"Passenger entered notes for the trip","example":"do not beep car horn please"},"passenger_count":{"type":"number","format":"int32","description":"number of passengers","example":1},"passengers":{"type":"array","description":"passengers for the trip, this is optional","items":{"$ref":"#/components/schemas/Passenger"}},"fare":{"$ref":"#/components/schemas/Fare"},"train_number":{"type":"string","maxLength":15,"description":"the train number"},"flight_number":{"type":"string","description":"the flight number"},"quote":{"$ref":"#/components/schemas/Fare"}}},"QuoteRequest":{"type":"object","required":["origin","destination"],"properties":{"origin":{"$ref":"#/components/schemas/Location"},"destination":{"$ref":"#/components/schemas/Location"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"},"date_scheduled":{"type":"string","description":"Date should be specified in ISO 8601 Date Time format with the correct timezone for the origin, leave empty for ASAP booking","example":"2024-04-18T14:27:22.064Z"},"passenger_capacity":{"type":"integer","description":"Passenger Capacity of DMS Vehicle type","example":4},"driving_distance_metres":{"type":"integer","description":"Estimated driving distance in metres","example":4500}}},"QuoteResponse":{"type":"object","properties":{"quotes":{"type":"array","items":{"properties":{"quote":{"$ref":"#/components/schemas/Fare"},"vehicle":{"$ref":"#/components/schemas/Vehicle"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"}}}}}},"AvailabilityRequest":{"type":"object","required":["origin"],"properties":{"origin":{"$ref":"#/components/schemas/Location"},"destination":{"$ref":"#/components/schemas/Location"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"},"radius":{"type":"number","format":"int32","description":"Optional radius in KM"},"passenger_capacity":{"type":"integer","description":"Passenger Capacity of DMS Vehicle type","example":4}}},"ETARequest":{"type":"object","required":["origin"],"properties":{"origin":{"$ref":"#/components/schemas/Location"},"destination":{"$ref":"#/components/schemas/Location"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"},"passenger_capacity":{"type":"integer","description":"Passenger Capacity of DMS Vehicle type","example":4}}},"ETAResponse":{"type":"object","properties":{"etas":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}}}},"AvailabilityResponse":{"type":"object","properties":{"vehicles":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}}}},"AvailabilityPushRequest":{"type":"object","required":["fleet_id"],"properties":{"fleet_id":{"type":"string","description":"DMS fleet ID"},"vehicles":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}},"passenger_capacity":{"type":"integer","description":"Passenger Capacity of DMS Vehicle type","example":4}}},"TripDocument":{"type":"object","required":["document_data","file_type","document_number","document_issued_date"],"properties":{"document_data":{"type":"string","description":"base64 encoded document data"},"file_type":{"type":"string","description":"document file type\n \n","enum":["PDF"]},"document_number":{"type":"string","description":"document or invoice number"},"document_issued_date":{"type":"string","description":"date and time document was issued date in RFC3339 format"}}},"PushTripDocumentRequest":{"type":"object","required":["trip_id","trip_document","external_info"],"properties":{"trip_id":{"type":"string","description":"karhoo trip ID"},"external_info":{"$ref":"#/components/schemas/ExternalInfo"},"trip_document":{"$ref":"#/components/schemas/TripDocument"}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}