Webhooks API 1.1
Important notice
This website does not contain documentation of the newest features.
If you are a new user of the Kiwi.com
APIs, we highly recommend using
tequila.kiwi.com.
To access Tequila documentation, create an account.
If you have any questions, use the Tequila support page.
Outdated version
New webhook features are no longer supported for this version of webhooks.
Please migrate to Webhooks 2.0 using this guide.
Welcome to Kiwi.com‘s PUSH API documentation which details how relevant information about the state of a reservation is delivered to the customers’ endpoint. Below, we describe all notifications that are sent from kiwi.com. Should you need any further information or detail, please contact your Kiwi.com line manager.
PUSH notifications ¶
The following json will be delivered to the specified API endpoint (POST method), which has to respond with an HTTP 200 status. Otherwise, the call will be repeated every 5 minutes.
PLEASE NOTE:
-
These notifications are sent to you from kiwi. com. There is no need to send these to us.
-
There is no need to download the content of the PUSH notifications you receive from us as these are permalinks that will be available to you for the entire time. All you need to save is the link.
-
The endpoints that you send to us MUST be HTTPS. If you send HTTP we have to send it back to you for amendments.
-
You can also use webhook notifications and tell us you do not want to receive emails/sms notifications from us. You will still have to put your email address in save_booking but you will not receive any email only webhook notification.
Callbacks and flow ¶
-
Basic flow : received — confirmed — bp_sent
-
Price change : received — price changes (if the customer pays the difference : confirmed — bp_sent)
-
Cancelled : received — technical_issue / sold_out / security_issue
The flow is simple. When a booking is received, a notification (with the status “RECEIVED”) is sent to the customer with their payment confirmation and more information about the next steps. After the booking is confirmed by all carriers, another notification is sent (now with the status “CONFIRMED”). This contains their e-ticket, PNRs and information about check-in and the next steps.
In cases where the booking is not being processed as expected, emails informing the customers are sent. If the booking process takes longer than expected and there is a minor delay, an email with the status “BEING PROCESSED” is sent. Price changes can occur. In such cases, customers can either choose whether they want to pay the price difference or be refunded instead. When all seats are sold out or there is a technical or security issue, we immediately refund the customer (an email with the status “REFUND” is sent).
When we do online check-in for our customers, an email is sent with their boarding passes attached.
Example calls ¶
The following are the statuses that can be assigned:
received, confirmed, bp_sent, price_changed, sold_out, technical_issue, cancelled_by_carrier, security_issue, refund, additional_service (additional baggage, additional extras, flights change)
received ¶
The customer receives the following email: “We are now processing your order and will send your booking confirmation and e-ticket within 30 minutes.”
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "received",
"data": []
}
receivedPOST/
confirmed ¶
The booking is confirmed and the PNRs are sent. When there are more than one PNR per flight, they are delimited by a semicolon “;” (see the example data below). “Just being issued” means that we are waiting for the PNR from the airline. We will send several notifications until all PNRs are sent. We send boarding passes as soon as online check-in becomes available (and online_check_in = true).
Our partners can receive the “confirmed” status several times due to a so called ticketing in process status, where the reservation is made but we are waiting for the issuance of the PNR. The only difference from the final confirmed
status is that one or more PNRs are still missing.
Parameters:
-
credit_card — our virtual card that was used for payment
-
eticket_link — in pdf, contains eticket_number = PNR which is necessary for check-in
-
passengers_data — array of passengers, index is pk (private key), you can get it from save_booking response.
-
gds_ticket_number — interval id for lc flights (same for some lcc flights and for those that don’t book on gds)
Headers
Content-Type: application/json
Body
{
"bid": 15469494,
"status": "confirmed",
"data": {
"pnr_list": [
"TESTPNR1",
"TESTPNR2"
],
"detail_field": [
{
"src": "KIV",
"dst": "LTN",
"iata": "W6",
"pnr": "TESTPNR1",
"pnr_availability": null,
"online_check_in": true,
"bp_availability": "2016-06-21 14:10:00 +02:00",
"bp_link": "https://skypicker-mailing-develop.s3.amazonaws.com/1027/Chisinau-London_SP21**************ddf60457319.pdf?v=1465985780",
"passengers_data": {
"1555656": {
"name": "test",
"surname": "test",
"birthday": "1985-01-01",
"pnr": "TESTPNR1",
"gds_ticket_number": "TESTPNR1"
}
}
},
{
"src": "LTN",
"dst": "KIV",
"iata": "W6",
"pnr": "TESTPNR2",
"pnr_availability": null,
"online_check_in": true,
"bp_availability": "2016-06-30 08:20:00 +02:00",
"bp_link": null,
"passengers_data": {
"1555656": {
"name": "test",
"surname": "test",
"birthday": "1985-01-01",
"pnr": "TESTPNR2",
"gds_ticket_number": "TESTPNR2"
}
}
}
],
"credit_card": null,
"eticket_link": "https://skypicker-mailing-develop.s3.amazonaws.com/1027/1465***************c7093de42d14b9398fddf60457319.pdf?v=1465986232",
"invoice": "https://booking.skypicker.com/api/v0.1/get_file/1027250?file_id=228160**********fb-4e4e-aed7-67a5ff399647"
}
}
confirmedPOST/
bp_sent ¶
This status is similar to ‘confirmed’, but instead of using pnr_list, bp_list is used with a list of HTTP links leading to the boarding passes. It is also in the detail_field. (Please note, that this is always per flight. Not per passenger!) When online_check_in = False, boarding passes will not be sent. Check-in will only be possible at the airport.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "bp_sent",
"data": {
"bp_list": [
"https://mailing-documents.s3.amazonaws.com/10/Santanderd-Londond_6944503_a9fad224c6dfb1df8e4230b8bdefb91d.pdf",
"https://mailing-documents.s3.amazonaws.com/10/London-Copenhagen_3808822_a9fad224c6dfb1df8e4230b8bdefb91d.pdf",
"https://mailing-documents.s3.amazonaws.com/10/Barcelona-Santander_68573201_a9fad224c6dfb1df8e4230b8bdefb91d.pdf"
],
"detail_field": [
{
"src": "SDR",
"dst": "STN",
"iata": "FR",
"bp_link": "https://mailing-documents.s3.amazonaws.com/10/Santanderd-Londond_6944503_a9fad224c6dfb1df8e4230b8bdefb91d.pdf",
"pnr": "F2KA19",
"online_check_in": true,
"bp_availability": "2015-05-12 14:56:35 +02:00"
},
{
"src": "STN",
"dst": "CPH",
"iata": "FR",
"bp_link": "https://mailing-documents.s3.amazonaws.com/10/London-Copenhagen_3808822_a9fad224c6dfb1df8e4230b8bdefb91d.pdf",
"pnr": "F4F51B",
"online_check_in": true,
"bp_availability": "2015-05-12 14:56:35 +02:00"
},
{
"src": "CPH",
"dst": "BCN",
"iata": "YB",
"bp_link": null,
"pnr": "8F4A4N",
"online_check_in": false,
"bp_availability": null
},
{
"src": "BCN",
"dst": "SDR",
"iata": "KK",
"bp_link": "https://mailing-documents.s3.amazonaws.com/10/Barcelona-Santander_68573201_a9fad224c6dfb1df8e4230b8bdefb91d.pdf",
"pnr": "V1A51F",
"online_check_in": true,
"bp_availability": "2015-05-12 14:56:35 +02:00"
}
],
"credit_card": "https://mailing.skypicker.com/images/eNettCards/enettCard_130455.png",
"eticket_link": "https://skypicker-mailing.s3.amazonaws.com/137/E-ticket_passenger_ddd0d5e705493dd953089e3fde314edc.pdf",
"invoice": "https://booking.skypicker.com/api/v0.1/podio_attachment?file_id=174285569"
}
}
bp_sentPOST/
price_changed ¶
Should the price of a booked flight change, details are to be handled by support. When customers do not want to pay the price difference, we refund them. If they pay the price difference, we immediately continue with the booking. CSC provides information about the customers’ decisions. In this response, we also send the original price, currency, new price, the difference and the date the price_changed occurred.
Headers
Content-Type: application/json
Body
{
"bid": 15469494,
"status": "price_changed",
"data": {
"occured": "2016-06-15 12:24:41 +02:00",
"currency": "EUR",
"original_price": 330,
"new_price": 340,
"price_difference": 10
}
}
price_changedPOST/
sold_out ¶
The flight cannot be booked anymore - > we provide a refund automatically. CSC must inform the customer.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "sold_out",
"data": []
}
sold_outPOST/
technical_issue ¶
A technical issue in the carrier’s reservation system occurred -> we provide a refund automatically. CSC must inform the customer.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "technical_issue",
"data": []
}
technical_issuePOST/
cancelled_by_carrier ¶
Should the airline cancel the flight, a full refund is given. CSC must inform the customer.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "cancelled",
"data": []
}
cancelled_by_carrierPOST/
security_issue ¶
Should we detect that the credit card used to pay for the booking may be fraudulent, we give a full refund (in case Reisegiganten is the credit partner it will not be sent). CSC must inform the customer.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "security_issue",
"data": []
}
security_issuePOST/
refund ¶
Should some other problems with the reservation occurre, a full refund is provided. CSC must inform the customer.
An email informing the customer about a succesful refund is sent to the customer.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "refund",
"data": []
}
refundPOST/
Additional services ¶
Several options for modifying a reservation are available to our customers. After each modification webhook data containing any additional_service statuses is sent.
Additional baggage ¶
Customer ordered and paid for additional checked baggage.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "additional_service",
"data": {
"additional_baggage": 2
}
additional baggagePOST/
Additional extras ¶
Additional extras or services (sports equipment, seating, in-flight meals) were added by the customer.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "additional_service",
"data": {
"additional_extras": “Selected seats - 2 seats together, one next to the window - for both flights in reservation”
}
}
additional extrasPOST/
Flights change ¶
Customer decided to change one or more flights in their reservation. A whole new itinerary is sent to the customer with a link to the newly generated e-ticket.
Headers
Content-Type: application/json
Body
{
"bid": 10390,
"status": "additional_service",
"data": {
"eticket_link": "https://skypicker-mailing.s3.amazonaws.com/137/E-ticket_passenger_ddd0d5e705493dd953089e3fde314edc.pdf",
"flights_change": [
{
"dtime": "2015-10-31 17:10:00",
"iata": "AZ",
"src_name": "Prague",
"atime": "2015-10-31 18:55:00",
"src": "PRG",
"atime_utc": "2015-10-31 17:55:00",
"dst_name": "Fiumicino",
"dst": "FCO",
"dtime_utc": "2015-10-31 16:10:00",
"airline": "Alitalia",
"flight_no": "6161"
},
{
"dtime": "2015-10-31 21:15:00",
"iata": "AZ",
"src_name": "Fiumicino",
"atime": "2015-10-31 22:25:00",
"src": "FCO",
"atime_utc": "2015-10-31 21:25:00",
"dst_name": "Milan",
"dst": "MXP",
"dtime_utc": "2015-10-31 20:15:00",
"airline": "Alitalia",
"flight_no": "910"
}
]
}
}
flights changePOST/
Schedule change ¶
Schedule change is a change of departures and arrivals. Please, provide our technical support with specific email for receiving detailed schedule change emails.
Headers
Content-Type: application/json
Body
{
"bid": 80852398,
"status": "schedule_change",
"data": []
}
schedule changePOST/
Generated by aglio on 22 Feb 2022