Liftago Public API API documentation version v1
https://api.liftago.com/v1/partners/{partnerId}
Delivery API for external integration.
- partnerId: required(string)
/deliveryRides
Creates a new delivery ride
post /deliveryRides
Creates a new delivery ride
Body
Media type: application/json
Type: object
Properties- id: required(string - maxLength: 40 - pattern: [a-zA-Z0-9-_]+)
Unique ID provided by the partner which will be used in reports and to detect duplicate POSTs
- productSettingId: (string)
identifies various delivery ride settings, such as prize per leg, proof of identity requirements, etc. ProductSettings are managed by the account operator.
- stops: required(array of Stop)
must start an element with the kind "pickup", followed by 1+ elements with the kind "destination" and followed by 0+ "fallback_destinations".
Items: Stop
- stopId: required(string)
Provided by the partner. Unique within the ride.
- location: required(object)
- coordinates: (object)
- lat: (number)
- lon: (number)
- address: (object)
- street: required(string)
- houseNumber: required(string)
- city: required(string)
- zipCode: required(string)
- country: required(string)
- description: (string)
- coordinates: (object)
- contact: required(object)
Contact person assuming the role of a sender (for "pickup") or a recipient (for "destination" or "fallback destination").
- name: required(string)
- email: (string)
- company: (string)
- phoneNumber: required(string)
Phone number with international prefix
- noteForDriver: required(string)
Localized message for the driver.
- kind: required(string)
PICKUP | DESTINATION | FALLBACK_DESTINATION
- arrivalTime: (object)
Requested time to arrive at this stop. It must be specified on the PICKUP stop only, or all DESTINATION stops, or on no stop at all.
- from: required(datetime)
The beginning of the interval. Must be in UTC.
- to: required(datetime)
The end of the interval. Must be in UTC.
- from: required(datetime)
- verificationCode: (string - minLength: 4 - maxLength: 10)
Code (PIN, Password) to be used to proof the identity of a recepient. Always has to be null for PICKUP stops.
- stopId: required(string)
- webHook: (object)
If present, Liftago will send POST request to this URI, with given headers and body containing StatusChangedEvent on every relevant ride change.
- url: required(string)
URI to be called
- headers: required(array of Header - maxItems: 10)
Items: Header
- name: required(string)
- value: required(string)
- url: required(string)
- webHookV2: (object)
If present, Liftago will send POST request only to this
url, with givenheadersand body containingWebHookPayloadon every relevant ride or stop change.WebHookPayloadis of typeWebHookPayload: type: object properties: action: WebHookAction eventId: string rideId: string stopId?: string links: RideLinkwhere
WebHookActionis one ofSTOP_DELIVERED,STOP_UNDELIVERED,RIDE_PROCESSING,RIDE_ACCEPTED,RIDE_WAITING,RIDE_ON_BOARD,RIDE_COMPLETED,RIDE_CANCELLEDorRIDE_REJECTED.and
RideLinkis of typeRideLink: type: object properties: ride: type: string description: URI of the ride- url: required(string)
URI to be called
- headers: required(array of Header - maxItems: 10)
Items: Header
- name: required(string)
- value: required(string)
- url: required(string)
HTTP status code 201
Headers
- Location: required(string)
URI of created delivery ride
Example:
/deliveryRides/30dd67cc-b596-11e8-96f8-529269fb1459
Body
Media type: application/json
Type: object
Properties- id: required(string - maxLength: 40 - pattern: [a-zA-Z0-9-_]+)
Unique ID provided by the partner which will be used in reports and to detect duplicate POSTs
- rideStatus: required(one of PROCESSING, ACCEPTED, WAITING, ON_BOARD, COMPLETED, CANCELLED, REJECTED)
- PROCESSING - ride is being processed, driver not found yet. Transitions to ACCEPTED, REJECTED or CANCELLED BY SENDER
- ACCEPTED - driver found and selected. Transitions to WAITING or CANCELLED (either by DRIVER OR SENDER)
- WAITING - driver is waiting on pickup location. Transitions to ON_BOARD or CANCELLED (either by DRIVER or SENDER)
- ON_BOARD - passenger on board. Transitions to COMPLETED
- COMPLETED - ride finished
- CANCELLED - ride cancelled
- REJECTED - could not find taxi in time
- deliveryStatus: required(object)
- nextStop: (string)
StopId
- nextStop: (string)
- cancelledBy: (one of DRIVER, SENDER)
- driver: (object)
Will be present once the ride is ACCEPTED
- name: required(string)
- phoneNumber: (string)
Phone number to driver (goes through exchange)
- image: (string)
- car: (object)
Will be present once the ride is ACCEPTED
- color: required(one of BLACK, BLUE, BROWN, GREEN, ORANGE, PURPLE, RED, SILVER, WHITE, YELLOW)
- brand: required(string)
- model: required(string)
- licencePlate: required(string)
- taxiPosition: (object)
Last known taxi position. Will be available when the DRV starts comming for the package (can be null even if the ride is ACCEPTED). Position can be also tracked via Ridesharing location url in the links.
- lat: (number)
- lon: (number)
- price: required(object)
Total fixed price - available immediatelly - will change if the driver has to travel back to the sender or the fallback depot.
- amount: required(number)
- ccy: required(string)
ISO-4217 (EUR, CZK)
- pickupArrivalEstimateAt: (datetime)
Estimate of the taxi arrival to the pickup point. Not updated in case of delay. Updated in case of a driver cancellation. (available when the ride is ACCEPTED)
- destinationArrivalEstimateAt: (datetime)
Estimate of the taxi arrival to the destination point. Not updated in case of delay. Updated in case of a driver cancellation. (NULL while we're looking for a new driver and new ETA once we find him) Updated if the driver has to travel back to the sender or the fallback depot. (available when the ride is ACCEPTED)
- completedAt: (datetime)
When was the ride finished/cancelled
- stops: required(array of StopInfo)
Items: StopInfo
- id: required(string)
- lastDeliveryAttempt: (datetime)
- state: required(one of IN_QUEUE, DELIVERED, UNDELIVERED)
- IN_QUEUE - no delivery attempt yet
- DELIVERED - delivered attempt succeeded
- UNDELIVERED - last delivery attempt failed
- kind: required(string)
PICKUP | DESTINATION | FALLBACK_DESTINATION
- links: required(object)
- self: required(string)
- position: (string)
- cancel: required(string)
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "malformed_json_request",
"message": "Malformed json request"
}HTTP status code 404
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "PARTNER_NOT_FOUND",
"message": "Partner 'UNKNOWN' does not exist"
}HTTP status code 409
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "CURRENT_RIDE_EXISTS",
"message": "Ride '52b4f17d-cb60-41a5-a1c5-f901167e5bdc' already exists"
}Gets info about the delivery ride
get /deliveryRides/{rideId}
Gets info about the delivery ride
URI Parameters
- rideId: required(string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- id: required(string - maxLength: 40 - pattern: [a-zA-Z0-9-_]+)
Unique ID provided by the partner which will be used in reports and to detect duplicate POSTs
- rideStatus: required(one of PROCESSING, ACCEPTED, WAITING, ON_BOARD, COMPLETED, CANCELLED, REJECTED)
- PROCESSING - ride is being processed, driver not found yet. Transitions to ACCEPTED, REJECTED or CANCELLED BY SENDER
- ACCEPTED - driver found and selected. Transitions to WAITING or CANCELLED (either by DRIVER OR SENDER)
- WAITING - driver is waiting on pickup location. Transitions to ON_BOARD or CANCELLED (either by DRIVER or SENDER)
- ON_BOARD - passenger on board. Transitions to COMPLETED
- COMPLETED - ride finished
- CANCELLED - ride cancelled
- REJECTED - could not find taxi in time
- deliveryStatus: required(object)
- nextStop: (string)
StopId
- nextStop: (string)
- cancelledBy: (one of DRIVER, SENDER)
- driver: (object)
Will be present once the ride is ACCEPTED
- name: required(string)
- phoneNumber: (string)
Phone number to driver (goes through exchange)
- image: (string)
- car: (object)
Will be present once the ride is ACCEPTED
- color: required(one of BLACK, BLUE, BROWN, GREEN, ORANGE, PURPLE, RED, SILVER, WHITE, YELLOW)
- brand: required(string)
- model: required(string)
- licencePlate: required(string)
- taxiPosition: (object)
Last known taxi position. Will be available when the DRV starts comming for the package (can be null even if the ride is ACCEPTED). Position can be also tracked via Ridesharing location url in the links.
- lat: (number)
- lon: (number)
- price: required(object)
Total fixed price - available immediatelly - will change if the driver has to travel back to the sender or the fallback depot.
- amount: required(number)
- ccy: required(string)
ISO-4217 (EUR, CZK)
- pickupArrivalEstimateAt: (datetime)
Estimate of the taxi arrival to the pickup point. Not updated in case of delay. Updated in case of a driver cancellation. (available when the ride is ACCEPTED)
- destinationArrivalEstimateAt: (datetime)
Estimate of the taxi arrival to the destination point. Not updated in case of delay. Updated in case of a driver cancellation. (NULL while we're looking for a new driver and new ETA once we find him) Updated if the driver has to travel back to the sender or the fallback depot. (available when the ride is ACCEPTED)
- completedAt: (datetime)
When was the ride finished/cancelled
- stops: required(array of StopInfo)
Items: StopInfo
- id: required(string)
- lastDeliveryAttempt: (datetime)
- state: required(one of IN_QUEUE, DELIVERED, UNDELIVERED)
- IN_QUEUE - no delivery attempt yet
- DELIVERED - delivered attempt succeeded
- UNDELIVERED - last delivery attempt failed
- kind: required(string)
PICKUP | DESTINATION | FALLBACK_DESTINATION
- links: required(object)
- self: required(string)
- position: (string)
- cancel: required(string)
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "RIDE_NOT_FOUND",
"message": "Ride '52b4f17d-cb60-41a5-a1c5-f901167e5bdc' does not exist"
}Cancels ride
post /deliveryRides/{rideId}/cancel
Cancels ride
URI Parameters
- rideId: required(string)
Body
Media type: application/json
Type: object
Properties- reason: (string)
- comment: (string)
Text comment about cancallation reason
HTTP status code 204
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "malformed_json_request",
"message": "Malformed json request"
}HTTP status code 404
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "RIDE_NOT_FOUND",
"message": "Ride '52b4f17d-cb60-41a5-a1c5-f901167e5bdc' does not exist"
}HTTP status code 409
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "INCOMPATIBLE_STATE",
"message": "Ride '52b4f17d-cb60-41a5-a1c5-f901167e5bdc' is not in the state compatible with the requested action"
}Updates the stop
post /deliveryRides/{rideId}/stops/{stopId}/update
Updates the stop
URI Parameters
- rideId: required(string)
- stopId: required(string)
Body
Media type: application/json
Type: object
Properties- update: required(string)
POSTPONE_TO_END | CANCEL
HTTP status code 204
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "malformed_json_request",
"message": "Malformed json request"
}HTTP status code 403
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "UPDATE_NOT_ALLOWED",
"message": "Updates not allowed"
}HTTP status code 404
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "STOP_NOT_FOUND",
"message": "Stop '33d6953e-f533-4d1b-bb69-3092e0b51f23' does not exist for ride 'f9852152-1754-438e-a5ab-9a614339875a'"
}HTTP status code 409
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "INCOMPATIBLE_STATE",
"message": "Ride '52b4f17d-cb60-41a5-a1c5-f901167e5bdc' is not in the state compatible with the requested action"
}Returns expected availability of Liftago drivers at a specified time and place.
post /deliveryRides/availability
Returns expected availability of Liftago drivers at a specified time and place.
Body
Media type: application/json
Type: object
Properties- pickup: required(object)
- coordinates: (object)
- lat: (number)
- lon: (number)
- address: (object)
- street: required(string)
- houseNumber: required(string)
- city: required(string)
- zipCode: required(string)
- country: required(string)
- description: (string)
- coordinates: (object)
- destination: (object)
- coordinates: (object)
- lat: (number)
- lon: (number)
- address: (object)
- street: required(string)
- houseNumber: required(string)
- city: required(string)
- zipCode: required(string)
- country: required(string)
- description: (string)
- coordinates: (object)
- expectedTimeOfTakeOver: required(datetime)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- pickup: required(object)
- coordinates: (object)
- lat: (number)
- lon: (number)
- address: (object)
- street: required(string)
- houseNumber: required(string)
- city: required(string)
- zipCode: required(string)
- country: required(string)
- description: (string)
- coordinates: (object)
- destination: (object)
- coordinates: (object)
- lat: (number)
- lon: (number)
- address: (object)
- street: required(string)
- houseNumber: required(string)
- city: required(string)
- zipCode: required(string)
- country: required(string)
- description: (string)
- coordinates: (object)
- expectedTimeOfTakeOver: required(datetime)
- guaranteed: required(boolean)
True if Liftago confirms that it will provide a driver for a delivery requested at the specified time and place.
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- code: required(string)
- message: required(string)
Example:
{
"code": "malformed_json_request",
"message": "Malformed json request"
}