Farecloud logo
API docs by Redocly

Farecloud API (1.0)

Farecloud Team: [email protected] URL: https://farecloud.io

Farecloud API allows you to search for flights and availability and book tickets.

Please note: All the request/response elements having small right arrow at the end of the name are expandable on click.

Concept

Farecloud allows you to search flights and prices for the lowcost carriers worldwide.

All our prices are total final prices that include all the fees and charges.

Cache

Most searches are performed on our database containing cached flight details & prices.

We do our best to update prices as fast as possible and to keep as many flight variants as possible at every single moment of time but due to cache the following problems may occur from time to time:

  • Price rise/flight unavailable at Validation (pre-booking) stage
  • Lack of some flight variants available at the airline website - please contact us in this case

Implementation details

Base URL for the requests is https://api.farecloud.io/v1/. You have to append method name to the base URL.

All the responses from Farecloud API are in JSON format.

Your implementation should allow any undocumented JSON fields in response as we may introduce new fields at anytime. Order of JSON fields in response is not guaranteed - please use order-independent JSON parsing.

It's required to pass accept-encoding: gzip in all HTTP requests. This will allow compressing HTTP responses for faster response time

General Flow

There are 4 main methods available via Farecloud at the moment:

  • Search - Should be called to get all the flights and prices available for the specified route and dates. Fast response (up to 10 seconds, normally 3-5 seconds.
  • Validation - Used to accurately check for the price & luggage option for a particular flight variant. Should be called when the customer visits the booking page and accurate price check is required. Request may take up to 40 seconds.
  • Book - Used to pass passenger details and all the information required to issue tickets. Calling book method launches the issue of the tickets and may not be cancelled. There is no way to hold the price/seats without issuing tickets for lowcost carriers. Issue process doesn't end when response is received. You need to call Details method or use webhooks to get issue status. May take up to 60 seconds.
  • Details - Used to get booking details (status, passengers, airline pnrs etc) after the booking was created (Book method called) Fast response.

Countries, Airports, Carriers data

We provide data using industry coding standards such as IATA and ICAO codes for carriers, airports and countries. There are some coding directory providers you can use in order to interpret these codes:

Name Data Quality Price
AirHex Full database + airline logos High $1080
Aviation Edge Full database High $199
Our Airports Airports + Countries Medium Free
Open Flights Full database Inaccurate Free

Authentication

Farecloud uses simple Basic HTTP authentication to for authenticating requests.

You can authorize requests even in:

  • your browser - browser will ask for login and password when you open farecloud API URL
  • curl - curl --user login:password https://api.farecloud.io/
  • Any programming language and HTTP library supports Basic HTTP authentication

httpBasic

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Error handling

Despite the HTTP status code returned by the farecloud API we recommend you to look at the status and message field of the response.

message will only appear in response in case of some problem. For example the search response may look like this:

{
  "status": "error",
  "message": "date1 cannot be in the past"
}

It might be a good idea to always check if message field is present.

Webhooks

Farecloud can send POST requests to your URL when any of your bookings have status update. Please provide Farecloud with your webhook URL. POST requests contains JSON with 2 fields: type and data.

Type can be one of:

  • issue_started
  • issued
  • failed
  • bp_avaialble (Boarding passes available for your flight - most of bookings wouldn't send boarding passes)

You should return any response for the webhook call with the OK HTTP status code (200). In case of webhook failure (Non-200 code or any other problem) webhook call will be repeated every minute for no longer than 2 hours.

Example:

{
    "type": "issued",
    "data": {
        "number": "29D2DF",
        "createdAt": "2019-09-17 09:58",
        "luggageAdded": "20",
        "locators": ["DAZYCX"],
        "pnrs": [{
            "id": 13857,
            "status": "issued",
            "airlinePnrs": ["DAZYCX"],
            "fareRules": null,
            "flights": [{
                "marketingCarrier": "PC",
                "marketingCarrierFull": "PC",
                "operatingCarrier": "PC",
                "departureDateTime": "2019-09-19 14:30",
                "arrivalDateTime": "2019-09-19 17:35",
                "cabin": "Y",
                "plane": "",
                "arrivalTerminal": "",
                "departureTerminal": "",
                "number": "389",
                "from": "DME",
                "to": "SAW",
                "bookingClass": "",
                "segmentIndex": 0,
                "includedLuggage": "",
                "handLuggage": {
                    "dimensions": "55x40x20",
                    "weight": 10
                },
                "charter": false
            }],
            "purchasedLuggage": {
                "code": "20",
                "price": {
                    "amount": 26,
                    "currency": "EUR"
                }
            },
            "ticketNumbers": [],
            "bpUrls": [],
            "creditCard": null
        }],
        "flights": [{
            "marketingCarrier": "PC",
            "marketingCarrierFull": "PC",
            "operatingCarrier": "PC",
            "departureDateTime": "2019-09-19 14:30",
            "arrivalDateTime": "2019-09-19 17:35",
            "cabin": "Y",
            "plane": "",
            "arrivalTerminal": "",
            "departureTerminal": "",
            "number": "389",
            "from": "DME",
            "to": "SAW",
            "bookingClass": "",
            "segmentIndex": 0,
            "includedLuggage": "",
            "handLuggage": {
                "dimensions": "55x40x20",
                "weight": 10
            },
            "charter": false,
            "planeName": null,
            "marketingCarrierName": "Pegasus Airlines",
            "operatingCarrierName": "Pegasus Airlines",
            "fromFull": {
                "iata": "DME",
                "airportName": "Moscow Domodedovo Airport",
                "cityName": "Moscow",
                "countryIso": "RU",
                "countryName": "Russia",
                "terminal": null
            },
            "toFull": {
                "iata": "SAW",
                "cityName": "Istanbul",
                "airportName": "Sabiha Gokcen International Airport",
                "countryIso": "TR",
                "countryName": "Turkey",
                "terminal": null
            },
            "pnrIndex": 0
        }],
        "passengers": [{
            "type": "A",
            "firstName": "ALEX",
            "lastName": "KOTIGOV",
            "sex": "M",
            "dateOfBirth": "1978-06-05",
            "nationality": "RU",
            "passportNumber": "720160495",
            "passportExpirationDate": "2021-10-20"
        }],
        "transactions": [{
            "partner": "jetcompass",
            "date": "2019-09-17 09:58",
            "amount": -163,
            "currency": "EUR",
            "comment": "Issue of 29D2DF",
            "type": "booking"
        }],
        "bpUrls": [],
        "price": 163,
        "email": "[email protected]",
        "phone": "+79851234567",
        "partnerId": "972X2NA",
        "status": "issued"
    }
}

Testing

Use "test=true" parameter for Issue method in order to test virtual ticket issuing. There are no dedicated test environment and all data is live and actual. Please note that no information is sent to the airline until the tickets issue is initiated.

API Methods

Search for flights

The result will contain number of bookable variants each consisting of price, signature and array of flights.

Authorizations:
httpBasic
query Parameters
from
required
string
Example: from=BKK

Origin IATA-code

to
required
string
Example: to=HKT

Destination IATA-code

date1
required
string <date>
Example: date1=2019-01-25

Date of departure.

Format is yyyy-mm-dd

date2
string <date>
Example: date2=2019-02-02

Date of return flight (for round trip flights).

Format is yyyy-mm-dd

adults
required
number [ 1 .. 9 ]
Example: adults=1

Number of adults flying

children
number
Default: 0
Example: children=0

Number of children flying

infants
number
Default: 0
Example: infants=0

Number of infants flying. Should be less or equal to number of adults

limit
number
Default: 300
Example: limit=200

Limit number of results

Responses

Search response containing bookable flight options (variants).

Response Schema: application/json
status
required
string (status)
Enum: "ok" "error"
Array of objects (Variant)

Response samples

Content type
application/json
Example
{
  • "status": "ok",
  • "variants": [
    ]
}

Validate price & availability

Use this method in order to accurately check flight price & availability as well as to get some details of the flights like possible extra luggage options and fare rules.

Authorizations:
httpBasic
query Parameters
signature
required
string
Example: signature=0_DMK_HKT_FD_3033_25JAN2019_1955_25JAN2019_2120

Signature of the variant you are checking price for

adults
required
number [ 1 .. 9 ]
Example: adults=1

Number of adults

children
number
Default: 0
Example: children=0

Number of children

infants
number
Default: 0
Example: infants=0

Number of infants

Responses

Response Schema: application/json
status
required
string (Validation status)
Enum: "available" "unavailable" "error"
signature
required
string

Used to proceed with booking

required
object

Total price for all passengers

required
Array of objects (Flight)

Flights

passportRequired
required
boolean

Shows if passport details (number and expiration date) is required to book tickets

object (Passengers count)
required
Array of objects (Luggage option)

Purchasable extra luggage options for this variant.

Response samples

Content type
application/json
{
  • "status": "available",
  • "signature": "string",
  • "price": {
    },
  • "flights": [
    ],
  • "passportRequired": true,
  • "passengers": {
    },
  • "luggageOptions": [
    ]
}

Booking

Create booking and launch issue process.

This method will charge money from your Farecloud balance and start the tickets issue process.

Method will return booking status (in most cases waiting) and empty airlinesPnr. If the response status field is not error - the booking created succesfully and should be issued soon.

In case of any result (even error or timeout) please use Details request to get actual booking status.

You should call Get booking details method periodically to update booking status or configure webhooks on your side.

Authorizations:
httpBasic
Request Body schema: application/json
required
email
required
string <email>

This email address will be used to send time change/cancellation emails from the airline

phone
required
string

Customer phone number

Required format: +(country phone code) (area code) (full number)

requestOrigin
required
string

Should contain the website domain / company name and locale used to book tickets

signature
required
string

Signature representing the flights (received from the validation step)

required
Array of objects (Passenger details)

List of passengers details.

Passengers count should be the same as in the validation request.

luggageCode
required
string

Should be empty string if no extra luggage is selected

localId
string

Your local booking id.

Used to find bookings at Farecloud hub easier and to match your bookings with Farecloud

expectedPrice
required
number

Amount of money in base currency you expect to pay for the tickets for this booking.

This is a parameter that allows you to set a threshold for currency and airfare fluctuations that might slightly change during the booking process. We recommend to add 0.5% to the total amount of booking as a safety threshold, however it's up to you and varies depending on time you need to complete the booking.

It should consist of ticket price + extra luggage price (if any).

If expectedPrice param is less than real price the booking process will fail and error is returned

test
boolean
Default: false

Use only for development/testing purposes

Set to true for free virtual tickets issue.

Farecloud will set status to issued after some time and will generate a fake airline PNRs.

Responses

Response Schema: application/json
status
required
string (Booking status)
Enum: "new" "waiting" "issued" "failed" "cancelled" "error"

Status description:

  • new - Booking created
  • error - Unable to create booking
  • waiting - We are issuing the tickets
  • issued - Tickets are issued
  • failed - Tickets issue failed
  • cancelled - Booking was created but cancelled due to no activity
bookingId
string

Unique farecloud booking id - save it for future use

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "phone": 12345678912,
  • "requestOrigin": "bestflights_com-en",
  • "signature": "nl5dqUgM5fMHOPKrAywuPaSJKOMIXq7t7AEFiRqzm3i6v9gKUD_LuZlBEqsTPKgBc-c4RE6sE55eDUbWQhUA7fsf6V4l-hTDA43DvtiDhCJkJCYL6QXQDc1TxgjGfBE4GDfatMG_hNLENy__SHl6xuxEArdtOjaupqNYeH3ZUsziD0JhU7CHbEcSUnUoEY5dKbSYaE_hemSGO-bIz_vuzyUYqRTHCBr8zTuH8htXyC5yTOvgZ20_9xxgSFnAXwFGmAOVa1wnq6oz2FDDOaJ_v2FAiCrEYDusuDB4xmnmWPgUa1_21y6Ch4gqpAlQnHI2OqYdEum-FqqIWOFdgaQlU97GBxAXFTxDRta_wnD-D7Y1",
  • "passengers": [
    ],
  • "luggageCode": 20,
  • "localId": 12853,
  • "expectedPrice": 120.53,
  • "test": false
}

Response samples

Content type
application/json
{
  • "status": "waiting",
  • "bookingId": "A7B312X"
}

Get booking details

Use this method to get actual booking status, airline PNRs and all the booking details.

Authorizations:
httpBasic
query Parameters
id
required
string
Example: id=DE0442

Id of the booking (returned from Book method)

Responses

Response Schema: application/json
number
required
string

Booking id

bookingStatus
required
string (Booking status)
Enum: "new" "waiting" "issued" "failed" "cancelled" "error"

Status description:

  • new - Booking created
  • error - Unable to create booking
  • waiting - We are issuing the tickets
  • issued - Tickets are issued
  • failed - Tickets issue failed
  • cancelled - Booking was created but cancelled due to no activity
airlinePnrs
required
Array of strings

List of airline booking numbers (PNRs) - 1 PNR for one way, 1 or 2 for round trip

required
object

Total price for all passengers

fareRules
required
string

Fare rules

required
Array of objects (Flight)

Flights

required
Array of objects (Passenger details)

List of passengers details.

required
object (Luggage)

Purchased luggage

test
required
boolean

Is test booking (in case test=true) or real (test=false)

required
Array of objects (Charge/refund/deposit to your deposit)

Charges to your deposit linked to this booking

Response samples

Content type
application/json
{
  • "number": "DE0442",
  • "bookingStatus": "waiting",
  • "airlinePnrs": [
    ],
  • "price": {
    },
  • "fareRules": "Non-refundable and non-changeable",
  • "flights": [
    ],
  • "passengers": [
    ],
  • "purchasedLuggage": {
    },
  • "test": false,
  • "transactions": [
    ]
}