Webhooks API 1.1

API Endpoint

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

  1. Basic flow : received — confirmed — bp_sent

  2. Price change : received — price changes (if the customer pays the difference : confirmed — bp_sent)

  3. 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.”

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 10390,
  "status": "received",
  "data": []
}

received
POST/

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)

POST /
Responses200
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"
  }
}

confirmed
POST/

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.

POST /
Responses200
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_sent
POST/

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.

POST /
Responses200
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_changed
POST/

sold_out

The flight cannot be booked anymore - > we provide a refund automatically. CSC must inform the customer.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 10390,
  "status": "sold_out",
  "data": []
}

sold_out
POST/

technical_issue

A technical issue in the carrier’s reservation system occurred -> we provide a refund automatically. CSC must inform the customer.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 10390,
  "status": "technical_issue",
  "data": []
}

technical_issue
POST/

cancelled_by_carrier

Should the airline cancel the flight, a full refund is given. CSC must inform the customer.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 10390,
  "status": "cancelled",
  "data": []
}

cancelled_by_carrier
POST/

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.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 10390,
  "status": "security_issue",
  "data": []
}

security_issue
POST/

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.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 10390,
  "status": "refund",
  "data": []
}

refund
POST/

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.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
    "bid": 10390,
    "status": "additional_service",
    "data": {
    "additional_baggage": 2
}

additional baggage
POST/

Additional extras

Additional extras or services (sports equipment, seating, in-flight meals) were added by the customer.

POST /
Responses200
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 extras
POST/

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.

POST /
Responses200
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 change
POST/

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.

POST /
Responses200
Headers
Content-Type: application/json
Body
{
  "bid": 80852398,
  "status": "schedule_change",
  "data": []
}

schedule change
POST/

Generated by aglio on 24 Oct 2022