GetTransfer API

This documentation outlines all the necessary data for successfully integrating the booking flow.
While responses may contain additional data, you should only consider the information specified in this
documentation and disregard any other data.

Rate Limit

If an application exceeds the rate limit for a specific API endpoint, the API will return an HTTP status code 429. The Retry-After header will specify the number of seconds to wait before attempting the same request again.

Access Token

Reach out to our support team at support@travelpayouts.com to obtain an access token.

To receive the token, provide the email address you used for registration in our web interface (both test and production environment). Once obtained, include the access token in every request by passing it in the X-ACCESS-TOKEN header.

X-ACCESS-TOKEN: <your_token>

Environments

Test Environment:
- Web Interface: https://gtrbox.org
- API: https://gtrbox.org/api
Production Environment:
- Web Interface: https://gettransfer.com
- API: https://gettransfer.com/api

Get Prices ("book_now" Offers)

Required Parameters:

Point From (coordinates)
Point To (coordinates)
Date and Time (local, use date_to and date_return for round-trip transfers)
Pax (number of passengers, including child seats)
with_prices (must always be true)

Additional Notes:

The date and time must be at least 6 hours after the request time.
Prices available for clients are found in the book_now field within the prices object.
If the book_now field is missing, the route is not available for booking.
Prices are updated once per day at night (UTC).

Request

GET /api/route_info?{points,with_prices,date_to,date_return,pax}

Example Request

GET /api/route_info?points[]=<lat,long>&points[]=<lat,long>&with_prices=true&pax=2&date_to=2025-11-15T18:30:00+07:00&currency=USD&distance_unit=km

Parameters

type Params = { 
  points: Point[], 
  with_prices: boolean, //always true 
  date_to: DateTime (local time at Point), 
  date_return: DateTime, //if roundtrip needed, 
  pax: number, //number of passengers, including child seats 
  currency: string, // ISO code, if you need a result in a currency different 
  from the account currency 
  distance_unit: string // “km” or “m”, if you need a result in a unit different 
  from the account unit 
}

Server Response

TransportTypePrice = {
  min_float: number,
  min: string,
  book_now: string
}

Response = {
  result: "success",
  data: {
    (limousine|premium|business|comfort|economy|suv|van|minibus|bus): TransportTypePrice,
    success: boolean,
    distance: number,
    distance_preferred: number,
    duration: number,
    prices: { [string]: TransportTypePrice }
  }
}

Example

{

  "Result": "success",
  "Data": {
    "status": "OK",
    "distance": 705,
    "duration": 468,
    "success": true,
    "prices": {
      "limousine": {
        "min": "€455",
        "min_float": 455
      },
      "premium": {
        "min": "€246",
        "min_float": 246
      },

      "business": {
        "min": "€213",
        "min_float": 213,
        "book_now": "€4,659"
      },
      "comfort": {
        "min": "€2,701",
        "min_float": 2701
      },
      "economy": {
        "min": "€191",
        "min_float": 191,
        "book_now": "€2,319"
      },
      "suv": {},
      "van": {
        "min": "€258",
        "min_float": 258
      },
      "minibus": {
        "min": "€346",
        "min_float": 346
      },
      "bus": {
        "min": "€807",
        "min_float": 807
      }
    }
  }
}

Create a Transfer Request

If the Route Info response contains "book_now" offers and your client selects one of these offers to book, you can proceed with creating a transfer request.

Required Parameters:

from, to — Provide either name and coordinates (both are required for correct processing) or a Google Place ID;
Date and Time (local);
Number of Passengers (including children requiring child seats).

Additional notes (Optional):

Flight Number;
Name Sign (for meet & greet services);
Comments (e.g., large luggage, snowboards, pets, special requests).

Request

 POST /api/transfers

Parameters

type Point = string;
type CityPoint = {
    name: string,
    point: Point,
    place_id: string // Google`s place_id
};
type TripParams = {
    date: DateTime (in `CityPoint` timezone ),
    flight_number: string
};
type TransportTypeId =
    | "economy"
    | "comfort"
    | "business"
    | "premium"
    | "limousine"
    | "suv"
    | "van"
    | "minibus"
    | "bus";
type Params = {
    transfer: {
        from: CityPoint,
        to: CityPoint,
        trip_to: TripParams,
        trip_return: TripParams, // if roundtrip needed
        transport_type_ids: TransportTypeId[], // Transport type ids, can be null
        pax: number, // Total number of passengers, including those, who need child seats, >= 1
        child_seats_infant: number, // >=0
        child_seats_convertible: number, // >=0
        child_seats_booster: number, // >=0
        name_sign: string,
        comment: string,
        partner_passenger: { // real passenger’s data, we will use it only in emergency cases to connect driver with passenger
            full_name: string,
            email: string,
            phone: string
        }
    }
}

Example Body

{
  "transfer": {
    "from": {
      "name": "Heathrow Airport (LHR)",
      "point": "(51.4679914,-0.455051)"
    },
    "to": {
      "name": "City of London",
      "point": "(51.5123443,-0.0909852)"
    },
    "trip_to": {
      "date": "2025-11-15T18:30:00+07:00"
    },
    "transport_type_ids": ["limousine", "economy"],
    "pax": 3,
    "child_seats_infant": "0",
    "child_seats_convertible": "1",
    "child_seats_booster": "0",
    "partner_passenger": {
      "full_name": "Sam Smith",
      "email": "email@example.com",
      "phone": "+18005553535"
    }
  }
}

Server Response

type Point = string;
type CityPoint = {
    name: string,
    point: Point,
    place_id: string // Google`s place_id
};

type DateTime = string
type TransferStatus =
    "new"
    | "performed"
    | "completed"
    | "canceled"
    | "not_completed"
    | "rejected"
    | "pending_confirmation"
    | "outdated";

type TransportTypeId =
    "economy"
    | "comfort"
    | "business"
    | "premium"
    | "limousine"
    | "suv"
    | "van"
    | "minibus"
    | "bus" ;

type Money = {
    default: string, // in base currency
    preferred: string // exchanged to preferred currency
};

type BookNowOffer = {
    TransportTypeId: {
        currency: string,
        amount: number,
        base: Money,
        refund_tariffs: Object // for partners only 24 hours before trip 
        free cancelation
    }
};

type PartnerPassenger = {
    id: number,
    full_name: string,
    email: string,
    phone: string
};

type Transfer = {
    id: number,
    created_at: DateTime,
    distance: number, // In km or miles depending on account settings 
    (distance_unit)
    status: TransferStatus,
    from: CityPoint,
    to: CityPoint, // may not present in per hour trips
    date_to_local: DateTime,
    date_return_local: DateTime, only for roundtrips
    flight_number: string,
    flight_number_return: string,
    transport_type_ids: TransportTypeId[],
    pax: number, // Total number of passengers, including those who need child seats
    book_now: TransportTypeId, // if “book now” offer was paid
    time: integer, // estimated time in minutes
    name_sign: string,
    comment: string,
    child_seats_infant: number,
    child_seats_convertible: number,
    child_seats_booster: number,
    price: Money, // if transfer was paid
    paid_sum: Money, // if transfer was paid
    watertaxi: boolean, // if watertaxi will be included (for example, for transfers in Venice)
    book_now_offers: { BookNowOffer },
    date_refund: DateTime, // Date before which refund may be done, In UTC, if transfer was paid
    refunded_price: Money, // if the transfer was paid and refunded
    refunded_date: DateTime // if the transfer was paid and refunded
    editable_fields: string[], // fields that can be updated in PUT request
    partner_passenger: PartnerPassenger,
    cancelable: boolean,
    refundable: boolean, // if transfer was paid
    book_now_expiration: DateTime //Until what time book now offers can be booked
};

type Response = {
    result: "success",
    data: {
        transfer: Transfer,
    }
};

Server response

{
    "result": "success",
    "data": {
        "transfer": {
            "id": 238893,
            "created_at": "2025-11-31T11:24:29+0300",
            "distance": 33,
            "status": "new",
            "from": {
                "name": "Heathrow Airport (LHR), Hounslow TW6 1QG, UK",
                "point": "(51.4679914,-0.455051)",
                "place_id": "ChIJ6W3FzTRydkgRZ0H2Q1VT548"
            },
            "to": {
                "name": "City of London, London, UK",
                "point": "(51.5123443,-0.0909852)",
                "place_id": "ChIJX4XfTlUDdkgRwISR0ciFEQo"
            },
            "date_to_local": "2023-12-11T03:24:00+0000",
            "date_return_local": null,
            "flight_number": null,
            "flight_number_return": null,
            "transport_type_ids": [],
            "pax": 2,
            "time": 65,
            "name_sign": null,
            "comment": null,
            "child_seats": 0,
            "child_seats_infant": 0,
            "child_seats_convertible": 0,
            "child_seats_booster": 0,
            "price": null,
            "paid_sum": {
                "default": "0",
                "preferred": "US$0.00"
            },
            "watertaxi": false,
            "book_now_offers": {
                "economy": {
                    "amount": 882.0,
                    "base": {
                        "default": "US$882.00"
                    },
                    "currency": "USD",
                    "refund_tariffs": [
                        {
                            "period": 24
                        }
                    ]
                }
            },
            "refunded_price": null,
            "refunded_date": null,
            "editable_fields": [
                "name_sign",
                "flight_number",
                "promo_code"
            ],
            "date_refund": null,
            "cancelable": true,
            "book_now_expiration": "2023-11-07T11:24:29+0300",
            "refundable": false
        }
    }
}

Errors description

{
    "Payment": {
    },
    "result": "error",
    "error": {
        "type": "unprocessable",
        "details": {
            "date": [
                "is too early" | "is earlier than departure date" | "is invalid"
            ] | "Chosen date is out of period available for booking.",
            "region": [
                "forbidden"
            ],
            "pax": [
                "is not in range or set: 1..1000"
            ],
            "date_end": [
                "is not present"
            ],
            "trip_to": [
                "is not present"
            ],
            "from": [
                "is not present"
            ]
        }
    }
}

Payment

If in response you receive values in book_now_offers, you can book it right after creation with the
Payment request. All transfers are paid from you account balance, ask you account manager about payment terms.

When submitting a transfer request, you must include the transport type in the book_now_transport_type field. The transport type should always be set to "ground".

Request

POST /api/payments

Parameters

type TransportTypeId =
    "economy"
    | "comfort"
    | "business"
    | "premium"
    | "limousine"
    | "suv"
    | "van"
    | "minibus"
    | "bus" ;

type Params = {
    transfer_id: number,
    gateway_type: "ground” //payment from your partner balance
    book_now_transport_type: TransportTypeId  // for book_now offers only
};

Example

{
  "transfer_id": "16456",
  "gateway_type": "ground",
  "book_now_transport_type": "economy"
}

Server response

type Response = {
    result: string,
    data: {}
};

Errors description

{
    "result": "error",
    "error": {
        "type": "unprocessable",
        "details": {
            "price": [
                "is_too_big" // if there is no sufficient balance
            ]
        }
    }
}

Receive carrier and vehicle data

You can set up a callback to receive updates on transfer statuses. It's important to track the "performed", status, which indicates that the driver and vehicle have been assigned to the booking. Please send URL for callbacks to support@travelpayouts.com

You will receive data in the following format:

{
  "event": "transfer_status_changed",
  "transfer_id": 16456,
  "new_status": string // possible statuses: ‘performed’, ‘pending_confiramtion’, 
‘canceled’, ‘completed’, ‘not_completed’, ‘rejected’ 
}

Once you receive the "performed" status, you can make a GET /api/transfers/:id/offers request
to retrieve detailed information about the driver and vehicle.

Request

GET /api/transfers/:id/offers

Example

 https://gtrbox.org/api/transfers/16456/offers

Server response

type DateTime = string // ISO 8601;
type Money = {
    default: string, // in base currency
    preferred: string // exchanged to passenger preferred currency
};
type Locale = {
    code: string,
    title: string
};
type TransportTypeId =
    "economy"
    | "comfort"
    | "business"
    | "premium"
    | "limousine"
    | "suv"
    | "van"
    | "minibus"
    | "bus" ;

type Offer = {
    id: number,
    wifi: boolean,
    refreshments: boolean, //water and snacks on board
    charger: boolean,
    safety_partition: boolean,
    with_name_sign: boolean,
    wheelchair: boolean,
    carrier: {
        id: number,
        title: string,
        email: string,
        phone: string,
        approved: boolean, // Special mark means that this carrier has good rating for a long time
        languages: Locale[], // Languages that driver know. Empty array means unknown
        rated_offers_count: number, //How many ratings on our platform carrier has
        years_of_work: number, //How many years carrier works on our platform
        ratings: {
            average: number,
            vehicle: number,
            driver: number,
            communication: number,
        }
    },

    vehicle: {
        id: number,
        name: string, // Brand, model and year made in one line
        model: string, // Brand, model in one line
        transport_type_id: TransportTypeId,
        year: string,
        color: string,
        registration_number: string, // available only if transfer was paid
        pax_max: number,
        luggage_max: number,
        brand_name: string,
        model_name: string,
        new_luxury: boolean, // vip new cars mark
        photos: string[],
    },
    driver: { //only if driver has already been assigned. If there is no driver assigned you can use carrier phone number
        full_name: string,
        Unset
        phone: string
    }
};

type Response = {
    result: "success",
    data: Offer[]
};

Example

{
    "result": "success",
    "data": {
        "offers": [
            {
                "id": 409761,
                "wifi": false,
                "refreshments": false,
                "safety_partition": false,
                "with_name_sign": false,
                "charger": false,
                "wheelchair": false,
                "carrier": {
                    "id": 143,
                    "approved": false,
                    "ratings": {
                        "driver": 3.0,
                        "vehicle": 3.1,
                        "communication": 3.4,
                        "average": 3.2
                    },
                    "rated_offers_count": 8,
                    "years_of_work": 4,
                    "languages": [
                        {
                            "code": "en",
                            "title": "English"
                        },
                        {
                            "code": "fr",
                            "title": "Français"
                        }
                    ]
                },
                "vehicle": {
                    "id": 4786,
                    "name": "Toyota Auris, 2020",
                    "model": "Toyota Auris",
                    "transport_type_id": "economy",
                    "year": 2020,
                    "color": "beige",
                    "registration_number": "HH67676",
                    "pax_max": 4,
                    "luggage_max": 4,
                    "brand_name": "Toyota",
                    "model_name": "Auris",
                    "new_luxury": false,
                    "photos": [
                        "/files/fc60bd204366e1132c8ca97e23dfcc1b",
                        "/files/c1949e43693f8369ac39b8b3b8545089"
                    ]
                }
            }
        ]
    }
}

Send passenger’s contacts

You can send the passenger's contact details (name, email, and/or phone) either before or after payment. Additionally, you can include the flight number if applicable.

Request

PUT /api/transfers/:id

Example

{
  "transfer": {
    "partner_passenger": {
      "full_name": "March",
      "phone": "+449087897987"
    }
  }
}

Only fields included in the editable_fields array of the transfer can be updated.

Parameters

// All these fields are optional and allowed when transfer[editable_fields] contains them
type Params = {
    transfer: {
        trip_to?: {
            flight_number: string
        },
        trip_return?: {
            flight_number: string
        },
        partner_passenger?: {
            full_name: string,
            email?: string,
            phone?: string
        }
    }
};

Server response

type Response = {
    result: string,
    data: {
        transfer: Transfer
    }
};

Cancel Unpaid Request

You can cancel the request if the transfer hasn’t been paid.

Request

 POST /api/transfers/:id/cancel

Example

https://gtrbox.org/api/transfers/14372/cancel

Server Response

type Response = {
    result: string,
    data: {
        transfer: Transfer
    }
};

Errors description

{
    "result": "error",
    "error": {
        "type": "unprocessable",
        "details": {
            "Action unavailable. Please contact support at info@gettransfer.com."
        }
    }
}

Cancel Paid Transfer (with Refund)

You can cancel the paid request if the transfer refund period hasn’t passed yet.

POST /api/transfers/:id/refund

Example

https://gtrbox.org/api/transfers/13425/refund

Server Response

type Response = {
    result: string,
    data: {
        transfer: Transfer
    }
};

Errors description

{

"result": "error",
"error": {
    "type": "unprocessable",
    "details": {
        "Action unavailable. Please contact support at info@gettransfer.com."
    }
}

Download Voucher

You can receive voucher for transfer

Request

GET /api/transfers/voucher/:id

Example

https://gtrbox.org/api/transfers/voucher/13425

Server Response

 type Response = {file link}