Swagger definition

swagger: '2.0'
x-samples-languages:
  - curl
  - javascript
  - node
  - java
  - kotlin
  - python
  - php
  - go
  - swift
info:
  description: >-

    The Karhoo Supply API definition allows Dispatch Management Systems to integrate directly
    into the Karhoo Platform.

    The process of integrating consists of writing API endpoints directly into
    your Dispatch Management System so 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: [email protected]
  x-hugo-values:
    tags:
      - api
    categories:
      - dispatch
    public: true
host: rest.sandbox.karhoo.com
basePath: /v1/supply


schemes:
  - https
paths:
  '/dispatch-system/trip':
    post:
      tags:
        - "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.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: request body
          required: true
          schema:
            $ref: '#/definitions/CreateTrip'
        - in: header
          name: x-karhoo-request-signature
          type: string
          required: true
          description: HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo
      responses:
        '200':
          description: Success response
          schema:
            $ref: '#/definitions/Trip'
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized. Invalid credentials provided
        '403':
          description: >-
            Forbidden. The credentials provided do not have sufficient authority
            for this request

    get:
      tags:
        - "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.
      produces:
        - application/json
      parameters:
        - name: trip_id
          in: query
          required: true
          description: The Karhoo trip id
          type: string
        - name: external_trip_id
          in: query
          description: "DMS trip id"
          required: true
          type: string
        - name: external_fleet_id
          in: query
          description: "DMS fleet id"
          required: true
          type: string
        - name: external_account_id
          in: query
          description: "A booking account id - allows demand partners to specify a account to book with"
          required: false
          type: string
        - in: header
          name: x-karhoo-request-signature
          type: string
          required: true
          description: HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo
      responses:
        '200':
          description: Success response
          schema:
            $ref: '#/definitions/Trip'
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized. Invalid credentials provided
        '403':
          description: >-
            Forbidden. The credentials provided do not have sufficient authority
            for this request

    delete:
      tags:
        - "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.
      produces:
        - application/json
      parameters:
        - name: trip_id
          in: query
          required: true
          description: The Karhoo trip id
          type: string
        - name: external_trip_id
          in: query
          description: "DMS trip id"
          required: true
          type: string
        - name: external_fleet_id
          in: query
          description: "DMS fleet id"
          required: true
          type: string
        - name: external_account_id
          in: query
          description: "A booking account id - allows demand partners to specify a account to book with"
          required: false
          type: string
        - in: header
          name: x-karhoo-request-signature
          type: string
          required: true
          description: HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo
      responses:
        '200':
          description: Success response
          schema:
            $ref: '#/definitions/Trip'
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/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:
        - "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.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: request body
          required: true
          schema:
            $ref: '#/definitions/QuoteRequest'
        - in: header
          name: x-karhoo-request-signature
          type: string
          required: true
          description: HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo
      responses:
        '200':
          description: Success response
          schema:
            $ref: '#/definitions/QuoteResponse'
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/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:
      - "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.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: request body
          required: true
          schema:
            $ref: '#/definitions/ETARequest'
        - in: header
          name: x-karhoo-request-signature
          type: string
          required: true
          description: HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo
      responses:
        '200':
          description: Success response
          schema:
            $ref: '#/definitions/ETAResponse'
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/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:
        - "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.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: request body
          required: true
          schema:
            $ref: '#/definitions/AvailabilityRequest'
        - in: header
          name: x-karhoo-request-signature
          type: string
          required: true
          description: HMAC Hash of the your shared secret and the request payload. Use this to validate all requests from Karhoo
      responses:
        '200':
          description: Success response
          schema:
            $ref: '#/definitions/AvailabilityResponse'
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/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.

        It 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.

      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '204':
          description: Success response, no content. Service is ok
        '500':
          description: Service is down.


securityDefinitions:
  Bearer:
    description: >-
      For accessing the API a valid JWT token must be passed in all the queries
      in the 'Authorization' header.

      A valid JWT token is generated by the v1/auth API here (https://docs.karhoo.com/v1/auth/)

      The following syntax must be used in the 'Authorization' header :

      `Bearer: xxxxxx.yyyyyyy.zzzzzz`
    type: apiKey
    name: Authorization
    in: header

definitions:
  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: '#/definitions/ErrorDetails'
      errors:
        type: array
        description: DEPRECATED, please use `details`
        items:
          $ref: '#/definitions/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 account ID of the demand partner
        example: "BBC"

  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
        <ul>
          <li>PICKUP_TYPE_NOT_SET -  Empty pickup type for Airport</li>
          <li>PICKUP_TYPE_MEET_AND_GREET - The driver will meet the passenger inside the terminal</li>
          <li>PICKUP_TYPE_CURBSIDE - The driver will wait curbside at a designated pickup point</li>
          <li>PICKUP_TYPE_STANDBY - The passenger must call when they are ready with their luggage</li>
        </ul>
    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: '#/definitions/PickupType'

  DetailsType:
    type: string
    description: |
      A secondary POI type for more detailed categorization
        - NOT_SET_DETAILS_TYPE
        - AIRPORT
        - TRAIN_STATION
    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: '#/definitions/DetailsType'

  MeetingPointType:
    type: string
    description: |
     If being picked up at an Airport, the pickup type
     <ul>
       <li>MEETING_POINT_TYPE_DEFAULT:  Standard driver behavior for pickup or dropoff</li>
       <li>PICK_UP: This is a special pick up point for this location</li>
       <li>DROP_OFF: This is a special dropoff up point for this location</li>
       <li>MEET_AND_GREET: Usually when the driver will meet the passenger with a greeting sign</li>
       <li>CURB_SIDE: The driver will wait curbside at a designated pickup point</li>
       <li>STAND_BY: The passenger must call when they are ready. Usually with their luggage when an airport</li>
     </ul>
    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: '#/definitions/LatLong'
      instructions:
        type: string
        description: The meeting point instructions
        example: London Heathrow Airport, Terminal 5 Arrivals
      type:
        $ref: '#/definitions/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: '#/definitions/Position'
      address:
        $ref: '#/definitions/Address'
      airport:
        $ref: '#/definitions/Airport'
        description: __DEPRECATED__ Please use `details`
      details:
        $ref: '#/definitions/Details'
      meeting_point:
        $ref: '#/definitions/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 <br>
        <ul>
          <li> NOT_SET </li>
          <li> AVAILABLE </li>
          <li> UNAVAILABLE </li>
        </ul>
    enum:
      - NOT_SET
      - AVAILABLE
      - UNAVAILABLE

  Vehicle:
    type: object
    properties:
      vehicle_class:
        type: string
        description: |
          Karhoo vehicle classification
            <ul>
              <li> EXEC </li>
              <li> LUX </li>
              <li> MOTO </li>
              <li> MPV </li>
            </ul><br>
            This field is for information purposed only and will change over time. It is only set by Karhoo.
        example: MPV
      vehicle_registration:
        type: string
        description: The legal registration of the vehicle
        example: EVY2323
      position:
        $ref: '#/definitions/Position'
      direction:
        $ref: '#/definitions/Direction'
      eta:
        $ref: '#/definitions/ETA'
      description:
        type: string
        description: Color, Make and Model of the vehicle
        example: Black Lincoln Town Car
      state:
        $ref: '#/definitions/VehicleState'
      driver:
        $ref: '#/definitions/Driver'
      external_info:
        $ref: '#/definitions/ExternalInfo'

  FareComponent:
    type: object
    required:
      - name
    properties:
      name:
        type: string
        description: |
          Name of fare breakdown line item.
          This is not an expansive list, more fare components can be added at request.
            <ul>
            <li>BASE_RATE</li>
            <li>TOLLS</li>
            <li>MEET_AND_GREET</li>
            <li>FUEL_SURCHARGE</li>
            <li>SERVICE_CHARGE</li>
            <li>VAT</li>
            <li>TAX</li>
            <li>GRATUITY</li>
            <li>PARKING</li>
            <li>STOP_CHARGE</li>
            <li>WAITING_TIME</li>
            <li>CANCELLATION_FEE</li>
            <li>WORKERS_COMP</li>
          </ul>
        example: BASE_RATE
      value:
        type: integer
        example: 2330
        description: |-
          A positive integer in the smallest unit the currency supports (pence, cents, etc).
            2300 for $23.3
            100 for ¥100 which is a non-decimal currency no need to multiply by 100.
          A 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
          decimal places, ignore this field. Ex.: For a vat_percent of 20.374 set vat_decimal_places to 3 and
          vat_percent to 20374.

  FareType:
    type: string
    description: |
      The status of the Trip Request
        <ul>
          <li>FARE_TYPE_NOT_SET - A null status. Never use this.</li>
          <li>FIXED - The fare was quoted at a fixed price.</li>
          <li>METERED - The fare was quoted as metered.</li>
        </ul>
    enum:
      - FARE_TYPE_NOT_SET
      - FIXED
      - METERED
    example: FIXED

  Fare:
    type: object
    required:
      - total
      - currency
    properties:
      id:
        type: string
        description: Karhoo Id
      type:
        $ref: '#/definitions/FareType'
      total:
        type: integer
        example: 2330
        description: |
          A positive integer in the smallest unit the currency supports (pence, cents, etc).<br>
           <br> 2300 for $23.3
           <br> 100 for ¥100 which is a non-decimal currency no need to multiply by 100.
      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: '#/definitions/FareComponent'

  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
        <ul>
          <li> REASON_NOT_SET - A null status. Never use this. </li>
          <li> OTHER_DISPATCH_REASON - Other reason </li>
          <li> REQUESTED_BY_PASSENGER - The passenger called to cancel </li>
          <li> PASSENGER_DIDNT_SHOW_UP - Passenger No Show </li>
          <li> DRIVER_CANCELED - Driver bailed out </li>
          <li> FLEET_CANCELLED - Operator cancelled </li>
          <li> DISPATCH_CANCELLED - System cancelled </li>
          <li> NO_AVAILABILITY_IN_THE_AREA - Unable to service trip </li>
          <li> NO_FEE - Cancelled without a cancellation fee </li>
        </ul>
    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
        <ul>
          <li>NOT_SET - A null status. Never use this.</li>
          <li><s>NEW</s> - <i>DEPRECATED, Never use this</i> - Initial state of new bookings from Karhoo.</li>
          <li><s>REQUESTED</s> - <i>DEPRECATED, Never use this</i> - You have received the trip and will service it.</li>
          <li>CONFIRMED - Send this once you have saved the reservation information successfully.</li>
          <li>ALLOCATED - A driver has been assigned to the trip.</li>
          <li>DRIVER_EN_ROUTE - The driver is on their way to trip origin.</li>
          <li>APPROACHING - The driver is nearby the trip origin.</li>
          <li>ARRIVED - The driver has arrived at the pickup and is waiting for the passenger.</li>
          <li>PASSENGER_ON_BOARD - The passenger has been picked up and is on board.</li>
          <li>COMPLETED - The passenger has been dropped off.</li>
          <li>CANCELLED_BY_USER - The passenger has cancelled trip.</li>
          <li>CANCELLED_BY_DISPATCH - You have decline to service this trip.</li>
          <li>CANCELLED_BY_KARHOO - Karhoo has cancelled the trip.</li>
        </ul>
    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

  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: '#/definitions/State'
      cancellation_reason:
        $ref: '#/definitions/CancellationReason'
      is_fare_final:
        type: boolean
        description: "The final fare is calculated"

  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 account ID of the demand partner
        example: "BBC"

  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: 2017-09-14T12:45:54Z
      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: '#/definitions/CreateTripExternalInfo'
      origin:
        $ref: '#/definitions/Location'
      destination:
        $ref: '#/definitions/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: '#/definitions/Passenger'
      quote:
        $ref: '#/definitions/Fare'
      train_number:
        type: string
        maxLength: 15
        description: the train number
      flight_number:
        type: string
        description: the flight number

  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: '#/definitions/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: 2017-09-14T12:45:54Z
      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: '#/definitions/Location'
      destination:
        $ref: '#/definitions/Location'
      state:
        $ref: '#/definitions/TripState'
      vehicle:
        $ref: '#/definitions/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: '#/definitions/Passenger'
      fare:
        $ref: '#/definitions/Fare'
      train_number:
        type: string
        maxLength: 15
        description: the train number
      flight_number:
        type: string
        description: the flight number
      quote:
        $ref: '#/definitions/Fare'

  QuoteRequest:
    type: object
    required:
      - origin
      - destination
    properties:
      origin:
        $ref: '#/definitions/Location'
      destination:
        $ref: '#/definitions/Location'
      external_info:
        $ref: '#/definitions/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: 2016-04-21T21:57:48Z
      passenger_capacity:
        type: integer
        description: Passenger Capacity of DMS Vehicle type
        example: 4

  QuoteResponse:
    type: object
    properties:
      quotes:
        type: array
        items:
          properties:
            quote:
              $ref: '#/definitions/Fare'
            vehicle:
              $ref: '#/definitions/Vehicle'
            external_info:
              $ref: '#/definitions/ExternalInfo'

  AvailabilityRequest:
    type: object
    required:
      - origin
    properties:
      origin:
        $ref: '#/definitions/Location'
      destination:
        $ref: '#/definitions/Location'
      external_info:
        $ref: '#/definitions/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: '#/definitions/Location'
      destination:
        $ref: '#/definitions/Location'
      external_info:
        $ref: '#/definitions/ExternalInfo'
      passenger_capacity:
        type: integer
        description: Passenger Capacity of DMS Vehicle type
        example: 4

  ETAResponse:
    type: object
    properties:
      etas:
        type: array
        items:
          $ref: '#/definitions/Vehicle'

  AvailabilityResponse:
    type: object
    properties:
      vehicles:
        type: array
        items:
          $ref: '#/definitions/Vehicle'