Pumpkin Mobility Open & Free Ridesharing API, Limo API, Private-Hire API, Taxi API

Pumpkin Mobility is a mobility-as-a-service API to access pre-booked and on-demand mobility worldwide.

(This API is currently under active development and is very likely to change.)

Authorization

API Key

Pumpkin uses a Customer Key in the header (Authorization), and an Application Key in the body of the request (client_id) to authorize requests. Please contact us in order to begin this process.

Rides

Search for taxi, rideshare, private hire, business class & limo rides from around the world.

POST https://sandbox.pumpkinapi.com/search
RequestsGPSAddress
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "hail": {
    "start": {
      "latitude": "52.53023",
      "longitude": "13.234548",
      "requested_time": "2018-09-26T07:00:00+01:00"
    },
    "end": {
      "latitude": "52.50668",
      "longitude": "13.33346"
    },
    "vehicle": {
      "vehicle_class": "FIRST",
      "vehicle_type": "ANY",
      "passengers": 1,
      "luggage": 2,
      "sport_luggage": 0,
      "animals": 0,
      "children_seat_1": null,
      "children_seat_2": null,
      "driver_instructions": "Please perform a task."
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "client_id": "50fa099e-a924-5e96-b7b4-125b2923b778",
  "status": "SEARCH",
  "available": {
    "available_rides": [
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 37.9,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": 7
        },
        "vehicle": {
          "car_model": "Quality Taxi",
          "vehicle_class": "TAXI",
          "vehicle_type": "SEDAN",
          "color": null,
          "id": 0,
          "luggage": 4,
          "passengers": 4,
          "animals": null,
          "wheelchair": null,
          "sport_luggage": null,
          "children_seat_1": null,
          "children_seat_2": null
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 42.9,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": 7
        },
        "vehicle": {
          "car_model": "Quality Taxi",
          "vehicle_class": "TAXI",
          "vehicle_type": "VAN",
          "color": null,
          "id": -1,
          "luggage": 8,
          "passengers": 7,
          "animals": null,
          "wheelchair": null,
          "sport_luggage": null,
          "children_seat_1": null,
          "children_seat_2": null
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 151.41,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "Mercedes-Benz Sprinter",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "MINIBUS",
          "color": "black",
          "id": "5467",
          "luggage": 16,
          "passengers": 16,
          "animals": false,
          "wheelchair": false,
          "sport_luggage": 1,
          "children_seat_1": "",
          "children_seat_2": ""
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 150.6,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "VW T5",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "VAN",
          "color": "black",
          "id": "1628",
          "luggage": 6,
          "passengers": 6,
          "animals": false,
          "wheelchair": false,
          "sport_luggage": 1,
          "children_seat_1": "II/III: 15 - 36 kg",
          "children_seat_2": ""
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 139.9,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "Toyota Prius",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "SEDAN",
          "color": "black",
          "id": "3494",
          "luggage": 3,
          "passengers": 4,
          "animals": false,
          "wheelchair": false,
          "sport_luggage": 1,
          "children_seat_1": "II/III: 15 - 36 kg",
          "children_seat_2": ""
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      }
    ]
  },
  "hail": {
    "hail_id": "3756ca67-330f-4579-939d-3dae04838bb7",
    "hail_timestamp": "2018-09-24T11:21:33.981Z",
    "server_timestamp": "2018-09-24T11:21:33.981Z",
    "start": {
      "latitude": 52.56263999999999,
      "longitude": 13.20911,
      "address": "Streitstraße 32, 13587 Berlin, Germany",
      "requested_time": "2018-10-01T00:01:49+02:00",
      "estimated_time": null,
      "actual_time": null,
      "timezone": "Europe/Berlin",
      "estimated_delay_seconds": null
    },
    "end": {
      "latitude": 52.50523399999999,
      "longitude": 13.3931736,
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "requested_time": null,
      "estimated_time": null,
      "actual_time": null,
      "timezone": null,
      "estimated_delay_seconds": null
    },
    "passenger": {
      "mobile": "+491622920357",
      "email": "art@pumpk.in",
      "first_name": "art",
      "last_name": "richards"
    },
    "vehicle": {
      "vehicle_type": "ANY",
      "vehicle_class": "ANY",
      "passengers": 2,
      "luggage": 2,
      "sport_luggage": 0,
      "animals": 0,
      "children_seat_1": "",
      "children_seat_2": "",
      "special_instructions": ""
    }
  },
  "sentinel": "none",
  "sentinel_timestamp": "none"
}
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "hail": {
    "start": {
      "address": "Torstr. 12, Berlin, DE",
      "requested_time": "2018-09-26T07:00:00+01:00"
    },
    "end": {
      "address": "charlottenstr. 2, 10969, Berlin, DE"
    },
    "vehicle": {
      "vehicle_class": "FIRST",
      "vehicle_type": "ANY",
      "passengers": 1,
      "luggage": 2,
      "sport_luggage": 0,
      "animals": 0,
      "children_seat_1": null,
      "children_seat_2": null,
      "driver_instructions": "Please perform a task."
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "client_id": "50fa099e-a924-5e96-b7b4-125b2923b778",
  "status": "SEARCH",
  "available": {
    "available_rides": [
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 37.9,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": 7
        },
        "vehicle": {
          "car_model": "Quality Taxi",
          "vehicle_class": "TAXI",
          "vehicle_type": "SEDAN",
          "color": null,
          "id": 0,
          "luggage": 4,
          "passengers": 4,
          "animals": null,
          "wheelchair": null,
          "sport_luggage": null,
          "children_seat_1": null,
          "children_seat_2": null
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 42.9,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": 7
        },
        "vehicle": {
          "car_model": "Quality Taxi",
          "vehicle_class": "TAXI",
          "vehicle_type": "VAN",
          "color": null,
          "id": -1,
          "luggage": 8,
          "passengers": 7,
          "animals": null,
          "wheelchair": null,
          "sport_luggage": null,
          "children_seat_1": null,
          "children_seat_2": null
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 151.41,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "Mercedes-Benz Sprinter",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "MINIBUS",
          "color": "black",
          "id": "5467",
          "luggage": 16,
          "passengers": 16,
          "animals": false,
          "wheelchair": false,
          "sport_luggage": 1,
          "children_seat_1": "",
          "children_seat_2": ""
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 150.6,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "VW T5",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "VAN",
          "color": "black",
          "id": "1628",
          "luggage": 6,
          "passengers": 6,
          "animals": false,
          "wheelchair": false,
          "sport_luggage": 1,
          "children_seat_1": "II/III: 15 - 36 kg",
          "children_seat_2": ""
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      },
      {
        "estimated_duration": 2760,
        "estimated_price": {
          "amount": 139.9,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "Toyota Prius",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "SEDAN",
          "color": "black",
          "id": "3494",
          "luggage": 3,
          "passengers": 4,
          "animals": false,
          "wheelchair": false,
          "sport_luggage": 1,
          "children_seat_1": "II/III: 15 - 36 kg",
          "children_seat_2": ""
        },
        "start": {
          "requested_time": "2018-09-30T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-09-30T22:01:00.000Z"
        },
        "end": {
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-09-30T22:47:00.000Z"
        }
      }
    ]
  },
  "hail": {
    "hail_id": "3756ca67-330f-4579-939d-3dae04838bb7",
    "hail_timestamp": "2018-09-24T11:21:33.981Z",
    "server_timestamp": "2018-09-24T11:21:33.981Z",
    "start": {
      "latitude": 52.56263999999999,
      "longitude": 13.20911,
      "address": "Streitstraße 32, 13587 Berlin, Germany",
      "requested_time": "2018-10-01T00:01:49+02:00",
      "estimated_time": null,
      "actual_time": null,
      "timezone": "Europe/Berlin",
      "estimated_delay_seconds": null
    },
    "end": {
      "latitude": 52.50523399999999,
      "longitude": 13.3931736,
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "requested_time": null,
      "estimated_time": null,
      "actual_time": null,
      "timezone": null,
      "estimated_delay_seconds": null
    },
    "passenger": {
      "mobile": "+491622920357",
      "email": "art@pumpk.in",
      "first_name": "art",
      "last_name": "richards"
    },
    "vehicle": {
      "vehicle_type": "ANY",
      "vehicle_class": "ANY",
      "passengers": 2,
      "luggage": 2,
      "sport_luggage": 0,
      "animals": 0,
      "children_seat_1": "",
      "children_seat_2": "",
      "special_instructions": ""
    }
  },
  "sentinel": "none",
  "sentinel_timestamp": "none"
}

Search for available rides
POST/search

The Client will be making a request using a simple set of information.

The returned rides represent the currently available rides from our partner providers. These available rides may change between requests, there are no guarantees to the availability of a ride until a hail is made.

The client_id specifies a unique software application client, this will be your application’s unique application ID.

The Authorization header will contain your customer key.

Request Object The following properties are marked required or optional:

Parent Object Property Name Description Type Required or Optional Default Value
.client_id UUIDv4 ID of software client String Required -
.hail Requested ride hail object Object Required -
.hail .start Starting point of the requested ride. Object Required -
.hail.start .latitude GPS Latitude coordinates of the requested starting point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail.start .longitude GPS latitude coordinates of the requested starting point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail.start .address Address of the requested starting point of the ride String Required either both Latitude & Longitude, or Address -
.hail.start .requested_time ISO UTC DateTime of the requested starting time of the ride String Required -
.hail .end This is the end point of the requested ride. Object Required For Pre-Booking, Optional for On-Demand -
.hail.end .latitude GPS Latitude coordinates of the requested ending point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail.end .longitude GPS latitude coordinates of the requested ending point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail.end .address Address of the requested ending point of the ride String Required either both Latitude & Longitude, or Address -
.hail .vehicle Requested vehicle(s) details. Object Required -
.hail.vehicle .vehicle_class Minimum Class of vehicle, can be one of: FIRST, BUSINESS, ECONOMY, TAXI, ANY Will provide matching or higher class vehicles. String Optional “ANY”
.hail.vehicle .vehicle_type Exact type of vehicle, can be one of: MINICAB, SEDAN, MINIBUS, MINIVAN, VAN, ANY Will provide only matching vehicles, or if ANY is selected, any type of vehicle String Optional “ANY”
.hail.vehicle .passengers Number of passengers for ride. Integer Required -
.hail.vehicle .luggage Number of pieces of luggage. Integer Optional 0
.hail.vehicle .sport_luggage Number of pieces of oversized luggage. Integer Optional 0
.hail.vehicle .animals Number of animals. Integer Optional 0
.hail.vehicle .driver_instructions Special instructions or requests for driver. String Optional “”

Hail a taxi, rideshare, private hire, business class or limo ride from around the world.

POST https://sandbox.pumpkinapi.com/hail
RequestsGPSAddress
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "hail": {
    "start": {
      "latitude": "52.53023",
      "longitude": "13.234548",
      "requested_time": "2018-09-26T07:00:00+01:00"
    },
    "end": {
      "latitude": "52.50668",
      "longitude": "13.33346"
    },
    "passenger": {
      "mobile": "+491622920357",
      "email": "help@pumpk.in",
      "first_name": "Art",
      "last_name": "Richards"
    },
    "vehicle": {
      "vehicle_class": "FIRST",
      "vehicle_type": "ANY",
      "passengers": 1,
      "luggage": 2,
      "sport_luggage": 0,
      "animals": 0,
      "children_seat_1": null,
      "children_seat_2": null,
      "driver_instructions": "Please perform a task."
    }
  },
  "payment": {
    "method": "invoice"
  }
}
Schema
{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "UUIDv4, Unique identifier of Client",
      "format": "uuidv4"
    },
    "hail": {
      "type": "object",
      "description": "Hail request details",
      "properties": {
        "start": {
            "type": "object",
            "description": "The Starting Origin Point of a ride",
            "properties": {
                "latitude": {
                    "type": "string",
                    "description": "Float, Latitude of origin point, requires associated origin Longitude" 
                },
                "longitude": {
                    "type": "string",
                    "description": "Float, Longitude of origin point, requires associated origin Latitude"
                },
                "address": {
                    "type": "string",
                    "description": "The Address of the origin point, will be overriden by a combined valid origin latitude & longitude"
                },
                "requested_time": {
                    "type": "string",
                    "description": "The requested start time of the ride at the origin.  A valid datetime, either including timezone as an ISO8601 string, or, if without timezone, the local time with respect to the starting point including date and time",
                    "pattern": "^([0-9]+)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]+)?(([Zz])|([\+|\-]([01][0-9]|2[0-3]):[0-5][0-9]))"
                }
            }
        },
        "end": {
            "type": "object",
            "description": "The End Destination Point of a ride",
            "properties": {
                "latitude": {
                    "type": "string",
                    "description": "Float, Latitude of destination point, requires associated destination Longitude" 
                },
                "longitude": {
                    "type": "string",
                    "description": "Float, Longitude of destination point, requires associated destination Latitude"
                },
                "address": {
                    "type": "string",
                    "description": "The Address of the destination point, will be overriden by a combined valid destination latitude & longitude"
                }
            }
        },
        "passenger": {
            "type": "object",
            "description": "The details of the primary passenger of the ride",
            "properties": {
                "mobile": {
                    "type": "string",
                    "description": "The Mobile Phone number of the passenger, including country code and prefix of +, for receiving SMS and Phone Calls if required" 
                },
                "email": {
                    "type": "string",
                    "description": "The Email Address of the passenger, for receiving ride notifications and confirmation"
                },
                "first_name": {
                    "type": "string",
                    "description": "The First Name of the primary passenger"
                }
                "last_name": {
                    "type": "string",
                    "description": "The Last Name of the primary passenger"
                }
            },
            "required": [
                "mobile",
                "email",
                "first_name",
                "last_name"
            ]
        },
        "vehicle": {
            "type": "object",
            "description": "The vehicle requirements for the requested ride",
            "properties": {
               "vehicle_class": {
                   "type": "string",
                   "description": "The Minimum Class required for the requested ride, note that the selected vehicle could be a higher class.  If ANY is selected, will return any class of vehicle.  FIRST > BUSINESS > ECONOMY > TAXI = ANY",
                   "enum": [
                    "FIRST",
                    "BUSINESS",
                    "ECONOMY",
                    "TAXI",
                    "ANY"
                   ]
               },
               "vehicle_type": {
                   "type": "string",
                   "description": "The Vehicle Type required for the requested ride, note that when specifying the selected vehicle type, ONLY THE SPECIFIED TYPE will be returned, if available.  If ANY is selected, will return any type of vehicle.",
                   "enum": [
                    "MINICAB", 
                    "SEDAN", 
                    "MINIBUS", 
                    "MINIVAN", 
                    "VAN", 
                    "ANY"
                   ]
               },
               "passengers": {
                   "type": "integer",
                   "description": "The number of passengers for the requested ride."
               },
               "luggage": {
                   "type": "integer",
                   "description": "The number of luggage for the requested ride."
               },
               "sport_luggage": {
                   "type": "integer",
                   "description": "The number of oversize sport luggage for the requested ride."
               },
               "animals": {
                   "type": "integer",
                   "description": "The number of animals for the requested ride."
               },                         
               "driver_instructions": {
                   "type": "string",
                   "description": "Any additional instructions for the driver."
               }
            },
            "required": [
                "passengers",
                "luggage"
            ]
        }
      }
    },
    "payment": {
      "type": "object",
      "description": "The payment details object."
      "properties": {
        "method": {
            "type": "string",
            "description": "Defaults to invoice.",
            "example": "invoice"
        }
      }
    }
  },
  "required": [
    "client_id",
    "hail",
    "payment"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "status": "BOOKED",
  "booking": {
    "end": {
      "address": "Torstraße 12, 10119 Berlin, Germany",
      "latitude": 52.5275669,
      "longitude": 13.4137808,
      "estimated_time": "2018-10-05T22:18:00.000Z",
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.505234,
      "longitude": 13.3931736,
      "estimated_time": "2018-10-05T22:01:00.000Z",
      "requested_time": "2018-10-05T22:01:49.000Z",
      "estimated_delay_seconds": -49
    },
    "pickup": {
      "distance": 4.029,
      "pickup_info": "Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you. In case you cannot reach the driver please call on +49 30 346 497 360.",
      "flight_number": "",
      "special_wishes": "",
      "passenger_validation": 9784,
      "included_waiting_time": "10 minutes"
    },
    "status": {
      "is_past": false,
      "booking_type": "PREBOOKING",
      "is_cancelled": false,
      "can_be_modified": true,
      "has_final_price": false,
      "can_be_cancelled": true
    },
    "payment": {
      "method": "invoice"
    },
    "vehicle": {
      "color": "black",
      "animals": 0,
      "luggage": 2,
      "car_model": "Toyota Prius",
      "passengers": 2,
      "wheelchair": null,
      "vehicle_type": "SEDAN",
      "sport_luggage": 0,
      "vehicle_class": "ECONOMY",
      "children_seat_1": "",
      "children_seat_2": "",
      "current_location": null
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "booking_id": "1745b05d-ef7c-40f0-869c-28b5e59f3cd6",
    "external_id": "MY15E4J",
    "estimated_price": {
      "amount": 103.5,
      "vat_rate": null,
      "currency_code": "EUR",
      "tolls_included": true,
      "gratuity_included": true
    },
    "booking_timestamp": "2018-10-01T14:26:46.156Z",
    "estimated_duration": 1020
  },
  "hail": {
    "end": {
      "address": null,
      "latitude": 52.5275669,
      "timezone": null,
      "longitude": 13.4137808,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.50523399999999,
      "timezone": "Europe/Berlin",
      "longitude": 13.3931736,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": "2018-10-06T00:01:49+02:00",
      "estimated_delay_seconds": null
    },
    "hail_id": "edcd90ec-fe8d-4c39-abca-3560daef0a41",
    "vehicle": {
      "animals": 0,
      "luggage": 2,
      "passengers": 2,
      "vehicle_type": "ANY",
      "sport_luggage": 0,
      "vehicle_class": "ANY",
      "children_seat_1": "",
      "children_seat_2": "",
      "special_instructions": ""
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "hail_timestamp": "2018-10-01T14:26:27.375Z",
    "server_timestamp": "2018-10-01T14:26:27.375Z"
  },
  "sentinel": "none",
  "sentinel_timestamp": "none"
}
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "hail": {
    "start": {
      "address": "Torstr. 12, Berlin, DE",
      "requested_time": "2018-09-26T07:00:00+01:00"
    },
    "end": {
      "address": "charlottenstr. 2, 10969, Berlin, DE"
    },
    "passenger": {
      "mobile": "+491622920357",
      "email": "help@pumpk.in",
      "first_name": "Art",
      "last_name": "Richards"
    },
    "vehicle": {
      "vehicle_class": "FIRST",
      "vehicle_type": "ANY",
      "passengers": 1,
      "luggage": 2,
      "sport_luggage": 0,
      "animals": 0,
      "children_seat_1": null,
      "children_seat_2": null,
      "driver_instructions": "Please perform a task."
    }
  },
  "payment": {
    "method": "invoice"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "status": "BOOKED",
  "booking": {
    "end": {
      "address": "Torstraße 12, 10119 Berlin, Germany",
      "latitude": 52.5275669,
      "longitude": 13.4137808,
      "estimated_time": "2018-10-05T22:18:00.000Z",
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.505234,
      "longitude": 13.3931736,
      "estimated_time": "2018-10-05T22:01:00.000Z",
      "requested_time": "2018-10-05T22:01:49.000Z",
      "estimated_delay_seconds": -49
    },
    "pickup": {
      "distance": 4.029,
      "pickup_info": "Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you. In case you cannot reach the driver please call on +49 30 346 497 360.",
      "flight_number": "",
      "special_wishes": "",
      "passenger_validation": 9784,
      "included_waiting_time": "10 minutes"
    },
    "status": {
      "is_past": false,
      "booking_type": "PREBOOKING",
      "is_cancelled": false,
      "can_be_modified": true,
      "has_final_price": false,
      "can_be_cancelled": true
    },
    "payment": {
      "method": "invoice"
    },
    "vehicle": {
      "color": "black",
      "animals": 0,
      "luggage": 2,
      "car_model": "Toyota Prius",
      "passengers": 2,
      "wheelchair": null,
      "vehicle_type": "SEDAN",
      "sport_luggage": 0,
      "vehicle_class": "ECONOMY",
      "children_seat_1": "",
      "children_seat_2": "",
      "current_location": null
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "booking_id": "1745b05d-ef7c-40f0-869c-28b5e59f3cd6",
    "external_id": "MY15E4J",
    "estimated_price": {
      "amount": 103.5,
      "vat_rate": null,
      "currency_code": "EUR",
      "tolls_included": true,
      "gratuity_included": true
    },
    "booking_timestamp": "2018-10-01T14:26:46.156Z",
    "estimated_duration": 1020
  },
  "hail": {
    "end": {
      "address": null,
      "latitude": 52.5275669,
      "timezone": null,
      "longitude": 13.4137808,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.50523399999999,
      "timezone": "Europe/Berlin",
      "longitude": 13.3931736,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": "2018-10-06T00:01:49+02:00",
      "estimated_delay_seconds": null
    },
    "hail_id": "edcd90ec-fe8d-4c39-abca-3560daef0a41",
    "vehicle": {
      "animals": 0,
      "luggage": 2,
      "passengers": 2,
      "vehicle_type": "ANY",
      "sport_luggage": 0,
      "vehicle_class": "ANY",
      "children_seat_1": "",
      "children_seat_2": "",
      "special_instructions": ""
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "hail_timestamp": "2018-10-01T14:26:27.375Z",
    "server_timestamp": "2018-10-01T14:26:27.375Z"
  },
  "sentinel": "none",
  "sentinel_timestamp": "none"
}

Hail a ride
POST/hail

The Client will be making a request using a simple set of information, on behalf of the rider.

This includes the contact of the lead passenger, the requested vehicle information, and the start and end point. The payment method should be set to “invoice” unless otherwise specified.

The client_id specifies a unique software application client, this will be your application’s unique application ID.

The Authorization header will contain your customer key.

Request Object The following properties are marked required or optional:

(please see the schema under each request for a detailed breakdown)

Parent Object Property Name Description Type Required or Optional Default Value
.client_id UUIDv4 ID of software client String Required -
.hail Requested ride hail object Object Required -
.hail .start Starting point of the requested ride. Object Required -
.hail .start .latitude GPS Latitude coordinates of the requested starting point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail .start .longitude GPS latitude coordinates of the requested starting point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail .start .address Address of the requested starting point of the ride String Required either both Latitude & Longitude, or Address -
.hail .start .requested_time DateTime of the requested starting point of the ride String Required -
.hail .end This is the end point of the requested ride. Object Required For Pre-Booking, Optional for On-Demand -
.hail .end .latitude GPS Latitude coordinates of the requested ending point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail .end .longitude GPS latitude coordinates of the requested ending point of the ride Floating Number Required Either both Latitude + Longitude, or Address -
.hail .end .address Address of the requested ending point of the ride String Required either both Latitude & Longitude, or Address -
.hail .passenger Contact information of lead passenger Object Required -
.hail .passenger .mobile Mobile phone number of lead passenger, including ‘+’ prefix & country code String Required -
.hail .passenger .email Email address of lead passenger for confirmation String Required -
.hail .passenger .first_name First Name of lead passenger String Required -
.hail .passenger .last_name Last Name of lead passenger String Required -
.hail .vehicle Requested vehicle(s) details. Object Required -
.hail .vehicle .vehicle_class Minimum Class of vehicle, can be one of: FIRST, BUSINESS, ECONOMY, TAXI, ANY Will provide matching or higher class vehicles. String Optional “ANY”
.hail .vehicle .vehicle_type Exact type of vehicle, can be one of: MINICAB, SEDAN, MINIBUS, MINIVAN, VAN, ANY Will provide only matching vehicles, or if ANY is selected, any type of vehicle String Optional “ANY”
.hail .vehicle .passengers Number of passengers for ride. Integer Required -
.hail .vehicle .luggage Number of pieces of luggage. Integer Optional 0
.hail .vehicle .sport_luggage Number of pieces of oversized luggage. Integer Optional 0
.hail .vehicle .animals Number of animals. Integer Optional 0
.hail .vehicle .driver_instructions Special instructions or requests for driver. String Optional “”
.payment Payment object for ride Object Required -
.payment .method Method of payment String Required “INVOICE”

Response Object

Parent Object Property Name Description Type Example or Enumeration
.client_id UUIDv4 ID of software client String (UUIDv4) “50fa099e-a924-5e96-b7b4-125b2923b778”
.status Current status of the hail String (Enum) “HAIL_PENDING”, “HAIL_FAILED”, “SEARCH_PENDING”, “SEARCH_COMPLETE”, “SEARCH_FAILED”, “DECISION_PENDING”, “DECISION_COMPLETE”, “DECISION_FAILED”, “BOOKING_PENDING”, “BOOKING_CANCEL_PENDING”, “BOOKING_COMPLETE”, “BOOKING_FAILED”, “EN_ROUTE”, “IN_TRANSIT”, “PROVIDER_CANCELLED”, “CLIENT_CANCELLED”, “COMPLETED”, “UNKNOWN_IN_PROGRESS”, “UNKNOWN_CANCELLED”,
.booking Booking object representing the booked ride with the provider Object -
.booking .booking_id UUIDv4 ID of the current booking, used for querying status information and cancellation String (UUIDv4) “f1b31e8f-5206-45aa-bb56-07de61504228”
.booking .external_id External ID for the current booking, in the system of the provider String “WW962YA”
.booking .booking_timestamp The system time in UTC that the current booking was placed with the provider String “2018-10-11T06:38:50.404Z”
.booking .estimated_duration The estimated duration of the booking ride in seconds Integer 1020
.booking .start Starting point of the booked ride. Object -
.booking .start .latitude GPS Latitude coordinates of the booked starting point of the ride Floating Number 52.5275669
.booking .start .longitude GPS latitude coordinates of the booked starting point of the ride Floating Number 13.4137808
.booking .start .address Address of the booked starting point of the ride String “Torstraße 12, 10119 Berlin, Germany”
.booking .start .requested_time ISO UTC DateTime of the requested starting time of the ride String “2018-10-20T22:01:49.000Z”
.booking .start .estimated_time ISO UTC DateTime of the estimated starting time of the ride, based on estimation from the provider String “2018-10-20T22:01:49.000Z”
.booking .start .estimated_delay_seconds Integer (positive or negative) of the difference in seconds between the requested time and the estimated time Integer -49
.booking .end This is the end point of the booked ride. Object -
.booking .end .latitude GPS Latitude coordinates of the booked ending point of the ride Floating Number 52.505234
.booking .end .longitude GPS latitude coordinates of the booked ending point of the ride Floating Number 13.3931736
.booking .end .address Address of the booked ending point of the ride String “Charlottenstraße 2, 10969 Berlin, Germany”
.booking .end .requested_time ISO UTC DateTime of the requested end time of the ride (can be null if not provided in booking) String null
.booking .end .estimated_time ISO UTC DateTime of the estimated end time of the ride, based on estimation from the provider String “2018-10-20T22:01:49.000Z”
.booking .pickup Passenger pickup information for the booking Object -
.booking .pickup .distance Distance (in km) of the trip from start to end Floating Number 4.029
.booking .pickup .pickup_info Information to inform the behavior of the passenger, including contact information of provider, and instructions for pickup String “Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you by Support. In case you cannot reach the driver please call Customer Support on +49 30 346 497 360.”
.booking .pickup .flight_number Flight number of passenger, if booking is an airport pickup String “IA 325”
.booking .pickup .special_wishes Instructions to the driver, for specific pickup instructions. These are provided verbatim to the driver, and cannot be guaranteed to be followed String “Please wait at the curb”
.booking .pickup .passenger_validation Validation information that the passenger must provide to the driver in order to validate their identity, this could be a pin code or password given in the cab upon pickup or arrival String “7230”
.booking .pickup .included_waiting_time Estimate of waiting time that is included in the price of the booking, additional waiting time could cost extra String “10 minutes”
.booking .status Details about status of booking, including ability to cancel, modify, and if the final price has been assigned Object -
.booking .status .is_past If the ride is in the past Boolean false
.booking .status .booking_type Type of booking, whether pre-booked or on-demand String (enum) “PREBOOKING”, “ONDEMAND”
.booking .status .is_cancelled If booking has been cancelled Boolean false
.booking .status .can_be_modified If the booking can be modified Boolean false
.booking .status .has_final_price If the booking has the final price assigned to it Boolean false
.booking .status .can_be_cancelled If the booking can be cancelled Boolean true
.booking .payment The payment object associated with this booking Object -
.booking .payment .method The payment method, defaults to “invoice” String (enum) “invoice”
.booking .vehicle The vehicle information associated with this booking Object -
.booking .vehicle .color The color of the vehicle for this booking String “black”
.booking .vehicle .animals The number of animals for this booking Integer 0
.booking .vehicle .luggage The number of pieces of luggage for this booking Integer 2
.booking .vehicle .sport_luggage The number of pieces of oversize sport luggage for this booking Integer 2
.booking .vehicle .car_model The car model of the vehicle for this booking String “Toyota Prius”
.booking .vehicle .passengers The number of passengers for this booking Integer 2
.booking .vehicle .wheelchair The wheelchair accessibility of the vehicle for this booking String null
.booking .vehicle .vehicle_type The type of vehicle for this booking String (enum) “MINICAB”, “SEDAN”, “MINIBUS”, “MINIVAN”, “VAN”
.booking .vehicle .vehicle_class The class of vehicle for this booking String (enum) “TAXI”, “ECONOMY”, “BUSINESS”, “FIRST”
.booking .vehicle .children_seat_1 The type of the first child seat in the vehicle String “”
.booking .vehicle .children_seat_2 The type of the second child seat in the vehicle String “II/III - 30-50kg”
.booking .vehicle .current_location The current location information of the vehicle if the vehicle is currently dispatched (will be null if vehicle is not dispatched or under way) Object -
.booking .vehicle .current_location .latitude GPS Latitude coordinates of the current location of the booked ride Floating Number 52.506234
.booking .vehicle .current_location .longitude GPS latitude coordinates of the current location of the booked ride Floating Number 13.3231736
.booking .passenger Contact information of the primary passenger of the booking Object -
.booking .passenger .mobile Mobile phone number of lead passenger, including ‘+’ prefix & country code String “+491622920357”
.booking .passenger .email Email address of lead passenger for confirmation String "help@pumpk.in"
.booking .passenger .first_name First Name of lead passenger String “Art”
.booking .passenger .last_name Last Name of lead passenger String “Richards”
.booking .estimated_price Estimated price object of the current booking Object -
.booking .amount Amount of the current estimated price of booking the current ride Floating Number 103.5
.booking .vat_rate VAT rate percentage of the booking for the current locality String “7%”
.booking .currency_code The ISO Currency Code of the current estimated price of the booking String “EUR”
.booking .tolls_included Whether tolls from toll roads are included in the price of booking Boolean true
.booking .gratuity_included Whether gratuity (tip) is included in the estimated price of the booking Boolean true

Get the status of your ride.

POST https://sandbox.pumpkinapi.com/status
Requestsexample 1
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "booking": {
    "booking_id": "f1b31e8f-5206-45aa-bb56-07de61504228"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "status": "BOOKING_COMPLETE",
  "booking": {
    "end": {
      "address": "Torstraße 12, 10119 Berlin, Germany",
      "latitude": 52.5275669,
      "longitude": 13.4137808,
      "estimated_time": "2018-10-05T22:18:00.000Z",
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.505234,
      "longitude": 13.3931736,
      "estimated_time": "2018-10-05T22:01:00.000Z",
      "requested_time": "2018-10-05T22:01:49.000Z",
      "estimated_delay_seconds": -49
    },
    "pickup": {
      "distance": 4.029,
      "pickup_info": "Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you. In case you cannot reach the driver please call on +49 30 346 497 360.",
      "flight_number": "",
      "special_wishes": "",
      "passenger_validation": 9784,
      "included_waiting_time": "10 minutes"
    },
    "status": {
      "is_past": false,
      "booking_type": "PREBOOKING",
      "is_cancelled": false,
      "can_be_modified": true,
      "has_final_price": false,
      "can_be_cancelled": true
    },
    "payment": {
      "method": "invoice"
    },
    "vehicle": {
      "color": "black",
      "animals": 0,
      "luggage": 2,
      "car_model": "Toyota Prius",
      "passengers": 2,
      "wheelchair": null,
      "vehicle_type": "SEDAN",
      "sport_luggage": 0,
      "vehicle_class": "ECONOMY",
      "children_seat_1": "",
      "children_seat_2": "",
      "current_location": null
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "booking_id": "1745b05d-ef7c-40f0-869c-28b5e59f3cd6",
    "external_id": "MY15E4J",
    "estimated_price": {
      "amount": 103.5,
      "vat_rate": null,
      "currency_code": "EUR",
      "tolls_included": true,
      "gratuity_included": true
    },
    "booking_timestamp": "2018-10-01T14:26:46.156Z",
    "estimated_duration": 1020
  },
  "hail": {
    "end": {
      "address": null,
      "latitude": 52.5275669,
      "timezone": null,
      "longitude": 13.4137808,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.50523399999999,
      "timezone": "Europe/Berlin",
      "longitude": 13.3931736,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": "2018-10-06T00:01:49+02:00",
      "estimated_delay_seconds": null
    },
    "hail_id": "edcd90ec-fe8d-4c39-abca-3560daef0a41",
    "vehicle": {
      "animals": 0,
      "luggage": 2,
      "passengers": 2,
      "vehicle_type": "ANY",
      "sport_luggage": 0,
      "vehicle_class": "ANY",
      "children_seat_1": "",
      "children_seat_2": "",
      "special_instructions": ""
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "hail_timestamp": "2018-10-01T14:26:27.375Z",
    "server_timestamp": "2018-10-01T14:26:27.375Z"
  },
  "sentinel": "none",
  "sentinel_timestamp": "none"
}

Ride status
POST/status

The client_id specifies a unique software application client, this will be your application’s unique application ID.

The Authorization header will contain your customer key.

Request Object The following properties are marked required or optional:

(please see the schema under each request for a detailed breakdown)

Parent Object Property Name Description Type Required or Optional Default Value
.client_id UUIDv4 ID of software client String Required -
.booking Booking object representing the booked ride with the provider Object -
.booking .booking_id UUIDv4 ID of the current booking, used for querying status information and cancellation String (UUIDv4) “f1b31e8f-5206-45aa-bb56-07de61504228”

Response Object

See Hail response.


Cancel a booked ride.

POST https://sandbox.pumpkinapi.com/cancel
Requestsexample 1
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "booking": {
    "booking_id": "f1b31e8f-5206-45aa-bb56-07de61504228"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "status": "CLIENT_CANCELLED",
  "booking": {
    "end": {
      "address": "Torstraße 12, 10119 Berlin, Germany",
      "latitude": 52.5275669,
      "longitude": 13.4137808,
      "estimated_time": "2018-10-05T22:18:00.000Z",
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.505234,
      "longitude": 13.3931736,
      "estimated_time": "2018-10-05T22:01:00.000Z",
      "requested_time": "2018-10-05T22:01:49.000Z",
      "estimated_delay_seconds": -49
    },
    "pickup": {
      "distance": 4.029,
      "pickup_info": "Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you. In case you cannot reach the driver please call on +49 30 346 497 360.",
      "flight_number": "",
      "special_wishes": "",
      "passenger_validation": 9784,
      "included_waiting_time": "10 minutes"
    },
    "status": {
      "is_past": false,
      "booking_type": "PREBOOKING",
      "is_cancelled": false,
      "can_be_modified": true,
      "has_final_price": false,
      "can_be_cancelled": true
    },
    "payment": {
      "method": "invoice"
    },
    "vehicle": {
      "color": "black",
      "animals": 0,
      "luggage": 2,
      "car_model": "Toyota Prius",
      "passengers": 2,
      "wheelchair": null,
      "vehicle_type": "SEDAN",
      "sport_luggage": 0,
      "vehicle_class": "ECONOMY",
      "children_seat_1": "",
      "children_seat_2": "",
      "current_location": null
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "booking_id": "1745b05d-ef7c-40f0-869c-28b5e59f3cd6",
    "external_id": "MY15E4J",
    "estimated_price": {
      "amount": 103.5,
      "vat_rate": null,
      "currency_code": "EUR",
      "tolls_included": true,
      "gratuity_included": true
    },
    "booking_timestamp": "2018-10-01T14:26:46.156Z",
    "estimated_duration": 1020
  },
  "hail": {
    "end": {
      "address": null,
      "latitude": 52.5275669,
      "timezone": null,
      "longitude": 13.4137808,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": null,
      "estimated_delay_seconds": null
    },
    "start": {
      "address": "Charlottenstraße 2, 10969 Berlin, Germany",
      "latitude": 52.50523399999999,
      "timezone": "Europe/Berlin",
      "longitude": 13.3931736,
      "actual_time": null,
      "estimated_time": null,
      "requested_time": "2018-10-06T00:01:49+02:00",
      "estimated_delay_seconds": null
    },
    "hail_id": "edcd90ec-fe8d-4c39-abca-3560daef0a41",
    "vehicle": {
      "animals": 0,
      "luggage": 2,
      "passengers": 2,
      "vehicle_type": "ANY",
      "sport_luggage": 0,
      "vehicle_class": "ANY",
      "children_seat_1": "",
      "children_seat_2": "",
      "special_instructions": ""
    },
    "passenger": {
      "email": "art@pumpk.in",
      "mobile": "+491622920357",
      "last_name": "richards",
      "first_name": "art"
    },
    "hail_timestamp": "2018-10-01T14:26:27.375Z",
    "server_timestamp": "2018-10-01T14:26:27.375Z"
  },
  "sentinel": "none",
  "sentinel_timestamp": "none"
}

Ride cancel
POST/cancel

Attention: This ride will only complete if the ride can be cancelled with the provider (.booking.status.can_be_cancelled field is set to true in the ride status).

The client_id specifies a unique software application client, this will be your application’s unique application ID.

The Authorization header will contain your customer key.

Request Object The following properties are marked required or optional:

(please see the schema under each request for a detailed breakdown)

Parent Object Property Name Description Type Required or Optional Default Value
.client_id UUIDv4 ID of software client String Required -
.booking Booking object representing the booked ride with the provider Object -
.booking .booking_id UUIDv4 ID of the current booking, used for querying status information and cancellation String (UUIDv4) “f1b31e8f-5206-45aa-bb56-07de61504228”

Response Object

See Hail response.


List the rides for your account.

POST https://sandbox.pumpkinapi.com/list/PENDING
Requestsexample 1
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "client_id": "a0dd2f62-54c7-52d5-9f1a-daf98fbf9e49",
  "booking": {
    "booking_id": "f1b31e8f-5206-45aa-bb56-07de61504228"
  }
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "client_id": "50fa099e-a924-5e96-b7b4-125b2923b778",
  "booking_list": [
    {
      "client_id": "50fa099e-a924-5e96-b7b4-125b2923b778",
      "status": "CLIENT_CANCELLED",
      "booking": {
        "booking_id": "f1b31e8f-5206-45aa-bb56-07de61504228",
        "booking_timestamp": "2018-10-11T06:50:04.647Z",
        "external_id": "WW962YA",
        "estimated_duration": 1020,
        "estimated_price": {
          "amount": 103.5,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "Toyota Prius",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "SEDAN",
          "color": "black",
          "luggage": 2,
          "passengers": 2,
          "animals": 0,
          "wheelchair": null,
          "sport_luggage": 0,
          "children_seat_1": "",
          "children_seat_2": "",
          "current_location": null
        },
        "start": {
          "latitude": 52.505234,
          "longitude": 13.3931736,
          "address": "Charlottenstraße 2, 10969 Berlin, Germany",
          "requested_time": "2018-10-20T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-10-20T22:01:00.000Z"
        },
        "pickup": {
          "pickup_info": "Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you by Talixo. In case you cannot reach the driver please call Talixo on +49 30 346 497 360.",
          "flight_number": "",
          "included_waiting_time": "10 minutes",
          "special_wishes": "",
          "distance": 4.029,
          "passenger_validation": 7230
        },
        "end": {
          "latitude": 52.5275669,
          "longitude": 13.4137808,
          "address": "Torstraße 12, 10119 Berlin, Germany",
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-10-20T22:18:00.000Z"
        },
        "passenger": {
          "first_name": "art",
          "last_name": "richards",
          "mobile": "+491622920357",
          "email": "art@pumpk.in"
        },
        "payment": {
          "method": "invoice"
        },
        "status": {
          "is_past": null,
          "is_cancelled": true,
          "has_final_price": null,
          "can_be_cancelled": false,
          "can_be_modified": false,
          "booking_type": null
        }
      },
      "hail": {
        "hail_id": "1b510c9b-4dd4-450b-8a8a-b80a777ed3a7",
        "hail_timestamp": "2018-10-11T06:38:43.761Z",
        "server_timestamp": "2018-10-11T06:38:43.761Z",
        "start": {
          "latitude": 52.50523399999999,
          "longitude": 13.3931736,
          "address": "Charlottenstraße 2, 10969 Berlin, Germany",
          "requested_time": "2018-10-21T00:01:49+02:00",
          "estimated_time": null,
          "actual_time": null,
          "timezone": "Europe/Berlin",
          "estimated_delay_seconds": null
        },
        "end": {
          "latitude": 52.5275669,
          "longitude": 13.4137808,
          "address": null,
          "requested_time": null,
          "estimated_time": null,
          "actual_time": null,
          "timezone": null,
          "estimated_delay_seconds": null
        },
        "passenger": {
          "mobile": "+491622920357",
          "email": "art@pumpk.in",
          "first_name": "art",
          "last_name": "richards"
        },
        "vehicle": {
          "vehicle_type": "ANY",
          "vehicle_class": "ANY",
          "passengers": 2,
          "luggage": 2,
          "sport_luggage": 0,
          "animals": 0,
          "children_seat_1": "",
          "children_seat_2": "",
          "special_instructions": ""
        }
      },
      "sentinel": "none",
      "sentinel_timestamp": "none",
      "payment": {
        "method": "invoice"
      }
    },
    {
      "client_id": "50fa099e-a924-5e96-b7b4-125b2923b778",
      "status": "CLIENT_CANCELLED",
      "booking": {
        "booking_id": "27462ba8-1da6-471a-afef-b0251b52d157",
        "booking_timestamp": "2018-10-05T09:49:41.163Z",
        "external_id": "TRQHSGH",
        "estimated_duration": 1020,
        "estimated_price": {
          "amount": 103.5,
          "currency_code": "EUR",
          "tolls_included": true,
          "gratuity_included": true,
          "vat_rate": null
        },
        "vehicle": {
          "car_model": "Toyota Prius",
          "vehicle_class": "ECONOMY",
          "vehicle_type": "SEDAN",
          "color": "black",
          "luggage": 2,
          "passengers": 2,
          "animals": 0,
          "wheelchair": null,
          "sport_luggage": 0,
          "children_seat_1": "",
          "children_seat_2": "",
          "current_location": null
        },
        "start": {
          "latitude": 52.505234,
          "longitude": 13.3931736,
          "address": "Charlottenstraße 2, 10969 Berlin, Germany",
          "requested_time": "2018-10-05T22:01:49.000Z",
          "estimated_delay_seconds": -49,
          "estimated_time": "2018-10-05T22:01:00.000Z"
        },
        "pickup": {
          "pickup_info": "Your driver will wait at the provided address. If you cannot locate your driver, please contact your driver using the contact number sent by SMS to you by Talixo. In case you cannot reach the driver please call Talixo on +49 30 346 497 360.",
          "flight_number": "",
          "included_waiting_time": "10 minutes",
          "special_wishes": "",
          "distance": 4.029,
          "passenger_validation": 8910
        },
        "end": {
          "latitude": 52.5275669,
          "longitude": 13.4137808,
          "address": "Torstraße 12, 10119 Berlin, Germany",
          "requested_time": null,
          "estimated_delay_seconds": null,
          "estimated_time": "2018-10-05T22:18:00.000Z"
        },
        "passenger": {
          "first_name": "art",
          "last_name": "richards",
          "mobile": "+491622920357",
          "email": "art@pumpk.in"
        },
        "payment": {
          "method": "invoice"
        },
        "status": {
          "is_past": null,
          "is_cancelled": true,
          "has_final_price": null,
          "can_be_cancelled": false,
          "can_be_modified": false,
          "booking_type": null
        }
      },
      "hail": {
        "hail_id": "39891de6-6c06-4f07-8ae9-c5df69711e80",
        "hail_timestamp": "2018-10-05T09:48:09.314Z",
        "server_timestamp": "2018-10-05T09:48:09.314Z",
        "start": {
          "latitude": 52.50523399999999,
          "longitude": 13.3931736,
          "address": "Charlottenstraße 2, 10969 Berlin, Germany",
          "requested_time": "2018-10-06T00:01:49+02:00",
          "estimated_time": null,
          "actual_time": null,
          "timezone": "Europe/Berlin",
          "estimated_delay_seconds": null
        },
        "end": {
          "latitude": 52.5275669,
          "longitude": 13.4137808,
          "address": null,
          "requested_time": null,
          "estimated_time": null,
          "actual_time": null,
          "timezone": null,
          "estimated_delay_seconds": null
        },
        "passenger": {
          "mobile": "+491622920357",
          "email": "art@pumpk.in",
          "first_name": "art",
          "last_name": "richards"
        },
        "vehicle": {
          "vehicle_type": "ANY",
          "vehicle_class": "ANY",
          "passengers": 2,
          "luggage": 2,
          "sport_luggage": 0,
          "animals": 0,
          "children_seat_1": "",
          "children_seat_2": "",
          "special_instructions": ""
        }
      },
      "sentinel": "none",
      "sentinel_timestamp": "none",
      "payment": {
        "method": "invoice"
      }
    },
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": "NotFound",
  "message": "No Records with Client_Id 50fa099e-a924-5e96-b7b4-125b2923b778 and status PENDING",
  "timestamp": "2018-10-11T10:32:51.831Z"
}

List rides
POST/list/{status_category}

Status Categories:

Category Description Statuses
IN_PROGRESS All rides which are currently in progress, have not been completed, and are still active ‘BOOKING_COMPLETE’, ‘EN_ROUTE’, ‘IN_TRANSIT’
COMPLETED All rides which have successfully completed ‘COMPLETED’
PENDING All rides which are currently in the process of being booked, searched for, or decided upon ‘HAIL_PENDING’, ‘SEARCH_PENDING’, ‘SEARCH_COMPLETE’, ‘DECISION_PENDING’, ‘DECISION_COMPLETE’, ‘DECISION_FAILED’, ‘BOOKING_PENDING’, ‘BOOKING_CANCEL_PENDING’, ‘BOOKING_FAILED’, ‘UNKNOWN_IN_PROGRESS’
CANCELLED All rides which have been cancelled by the client ‘CLIENT_CANCELLED’, ‘UNKNOWN_CANCELLED’
FAILED ‘HAIL_FAILED’, ‘SEARCH_FAILED’, ‘PROVIDER_CANCELLED’

The client_id specifies a unique software application client, this will be your application’s unique application ID.

The Authorization header will contain your customer key.

Request Object The following properties are marked required or optional:

(please see the schema under each request for a detailed breakdown)

Parent Object Property Name Description Type Required or Optional Default Value
.client_id UUIDv4 ID of software client String Required -
.booking Booking object representing the booked ride with the provider Object -
.booking .booking_id UUIDv4 ID of the current booking, used for querying status information and cancellation String (UUIDv4) “f1b31e8f-5206-45aa-bb56-07de61504228”

Response Object

Parent Object Property Name Description Type Required or Optional Default Value
.client_id UUIDv4 ID of software client String Required -
.booking_list List of booking objects which fit the specified category, See Hail response. Array -
URI Parameters
HideShow
status_category
string (optional) Example: PENDING

The category of statuses

  • Members:
    • PENDING
    • IN_PROGRESS
    • CANCELLED
    • COMPLETED
    • FAILED

Utility Endpoints

Get the timezone of a given address or latitude/longitude, and the associated ISO UTC time.

POST https://sandbox.pumpkinapi.com/timezone
RequestsGPSAddress
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "latitude": 31.775388,
  "longitude": -106.2857509,
  "requested_time": "2018-09-10 21:00"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "latitude": 31.775388,
  "longitude": -106.2857509,
  "requested_time": "2018-09-10T21:00:00-06:00",
  "timezone": "America/Denver"
}
Headers
Content-Type: application/json
Authorization: "81a26bac-23a7-4639-93bc-cf4e7c922c20"
Body
{
  "address": "11664 Tom Fiore, El Paso, Texas",
  "requested_time": "2018-09-10 21:00"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "address": "11664 Tom Fiore Ct, El Paso, TX 79936, USA",
  "requested_time": "2018-09-10T21:00:00-06:00",
  "latitude": 31.775388,
  "longitude": -106.2857509,
  "timezone": "America/Denver"
}

Timezone from Address or Lat/Lon
POST/timezone

Request Object The following properties are marked required or optional:

(please see the schema under each request for a detailed breakdown)

Parent Object Property Name Description Type Required or Optional
.address Address of the location of desired time zone String Required either both Latitude & Longitude, or Address
.latitude GPS Latitude coordinates of the requested timezone Floating Number Required Either both Latitude + Longitude, or Address
.longitude GPS Longitude coordinates of the requested timezone Floating Number Required Either both Latitude + Longitude, or Address
.requested_time Requested time in a format supported by Moment String Required

Response Object

Parent Object Property Name Description Type Example or Enumeration
.address Address of the location of desired time zone, if provided in request String “11664 Tom Fiore Ct, El Paso, TX 79936, USA”
.latitude GPS Latitude coordinates of the requested timezone Floating Number 31.775388
.longitude GPS Longitude coordinates of the requested timezone Floating Number -106.2857509
.requested_time ISO UTC DateTime of the requested timezone location, with timezone String “2018-09-10T21:00:00-06:00”
.timezone The timezone string for the requested timezone location String “America/Denver”

Generated by aglio on 20 Nov 2018