Transfers API

Overview

The USA Caribbean Tours Transfers API lets travel agencies, OTAs and resellers sell our private airport and point-to-point transfers in their own website or booking system, with live prices and instant confirmation.

• Search returns fixed-price offers for a route, date and party size.
• Book confirms an offer at exactly the searched price.
• Status returns the order and, once assigned, the driver and vehicle.
• Cancel cancels an order and tells you the penalty, if any.

The API follows the ETG Transfers API v1 format, so partners already connected to that standard can reuse their integration. The same endpoints are also served under /api/v1/etg.

Getting access

Credentials are issued by our team for each partner. To request access, contact us or apply to our partner program. You will receive a username and password together with your agreed currency and cancellation terms.

Authentication

Every request uses HTTP Basic authentication with the username and password we issue you. Send it over HTTPS only and keep it on your server: never put it in a browser, mobile app or public repository.

Authorization: Basic base64(username:password)

Offers and orders are scoped to your account: you can only book, read or cancel what your own credentials created.

Conventions

• All endpoints are POST with a JSON body (Content-Type: application/json).
• Prices are decimal amounts in your account currency (default USD): { "amount": 95.0, "currency": "USD" }.
• Times are local to the pickup. Send start_date_time as the local wall-clock time of the pickup; a trailing Z is accepted but read as local time, not UTC. We answer with the same time and the pickup's real UTC offset, for example 2026-12-15T14:30:00-04:00.
• No availability is never an error: search returns { "offers": [] }.
• Errors always have the shape { "code": string, "error": string } (see Errors).

POST /search

Returns bookable offers for a route. Each offer has a fixed price and can be booked for up to 24 hours (or until the minimum advance time before the trip, whichever comes first).

curl -X POST https://usacaribbeantours.com/api/v1/transfers/search \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "passengers": 4,
    "children_seat_1": 1,
    "start_date_time": "2026-12-15T14:30:00Z",
    "start_point": { "type": "iata", "iata": "PUJ" },
    "end_point": {
      "type": "coordinates",
      "coordinates": { "lat": 18.6812, "lon": -68.4124 },
      "address": "Hotel Riu Palace, Bávaro"
    }
  }'

{
  "start_date_time": "2026-12-15T14:30:00-04:00",
  "offers": [
    {
      "id": "cmh2x8k1p0001qz8l3f9a7b2c",
      "service_type": "transfer",
      "transfer_category": "economy_van",
      "car_model": "Toyota Hiace",
      "seats": 7,
      "luggage_places": 7,
      "estimated_duration_minutes": 35,
      "distance": 24.6,
      "included_waiting_time_minutes": 60,
      "children_seat_0": 0,
      "children_seat_1": 1,
      "children_seat_2": 0,
      "children_seat_3": 0,
      "price": { "amount": 95.0, "currency": "USD" },
      "upsells": [
        { "id": "children_seat_1", "type": "children_seat_1", "price": 10, "count": 1, "max_count": 2 }
      ],
      "tolls_included": true,
      "gratuity_included": false,
      "free_cancel_until": "2026-12-14T14:30:00-04:00"
    }
  ]
}

• id is the offer_id you send to /book.
• distance is in kilometres. One offer per vehicle category and capacity (the cheapest).
• Empty results mean we don't cover the route, the trip is in the past or too soon, no vehicle fits the party, or a requested child seat is not available.

POST /book

Confirms an offer. The price is always the one returned by search. The booking must ask for the same child seats the offer was searched with.

{
  "offer_id": "cmh2x8k1p0001qz8l3f9a7b2c",
  "passengers": 4,
  "luggage_places": 4,
  "children_seat_1": 1,
  "flight_number": "AA1234",
  "shield_text": "SMITH FAMILY",
  "comment": "Arriving with a stroller",
  "main_passenger": {
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+15551234567",
    "email": "john.smith@example.com"
  },
  "start_point": { "type": "iata", "iata": "PUJ" },
  "end_point": {
    "type": "coordinates",
    "coordinates": { "lat": 18.6812, "lon": -68.4124 },
    "address": "Hotel Riu Palace, Bávaro"
  }
}

{
  "order_id": "T-7KQ4M2X",
  "pin_code": "4821",
  "supplier_link": "https://usacaribbeantours.com/admin/external-api/etg/orders/T-7KQ4M2X",
  "start_time": "2026-12-15T14:30:00-04:00",
  "distance": 24.6,
  "estimated_duration_minutes": 35,
  "included_waiting_time_minutes": 60,
  "buffer_time_minutes": 0,
  "passengers": 4,
  "luggage_places": 4,
  "sport_luggage_places": 0,
  "animals": 0,
  "wheelchairs_places": 0,
  "children_seat_0": 0,
  "children_seat_1": 1,
  "children_seat_2": 0,
  "children_seat_3": 0,
  "flight_number": "AA1234",
  "shield_text": "SMITH FAMILY",
  "comment": "Arriving with a stroller",
  "price": { "amount": 95.0, "currency": "USD" },
  "meeting_instructions": "Our driver waits at the arrivals exit holding a sign with your name."
}

• order_id is short and easy to read over the phone. Store it: you need it for /status and /cancel.
• pin_code lets the passenger identify themselves to the driver.
• supplier_link points to the order in our back office, for our support team.
• meeting_instructions and upsells are only present when they apply.

POST /status

Returns the current state of an order.

{
  "status": "completed",
  "order_id": "T-7KQ4M2X",
  "start_time": "2026-12-15T14:30:00-04:00",
  "free_cancel_until": "2026-12-14T14:30:00-04:00",
  "price": { "amount": 95.0, "currency": "USD" },
  "transfer_category": "economy_van",
  "main_passenger": { "first_name": "John", "last_name": "Smith", "phone": "+15551234567" },
  "passengers": 4,
  "luggage_places": 4,
  "sport_luggage_places": 0,
  "animals": 0,
  "included_waiting_time_minutes": 60,
  "buffer_time_minutes": 0,
  "comment": "Arriving with a stroller",
  "shield_text": "SMITH FAMILY",
  "driver_info": {
    "first_name": "Carlos",
    "last_name": "Pérez",
    "phone": "+18095551234",
    "carrier_company_name": "USA Caribbean Tours"
  },
  "car_info": { "car_model": "Toyota Hiace", "plate_number": "A123456", "color": "White" },
  "meeting_info": { "instructions": "Arrivals hall, exit B." }
}

• status is completed (confirmed and active) or cancelled.
• driver_info, car_info and meeting_info appear only after we assign them. Call /status again closer to the trip to pick them up.

POST /cancel

Cancels an order. It always succeeds, even when a driver is already assigned. Inside the free cancellation window (free_cancel_until) the penalty is 0; after it, the penalty agreed in your contract applies (never more than the order price).

{ "penalty": { "amount": 0, "currency": "USD" } }

Cancelling the same order again is safe and returns the same penalty.

Errors

{ "code": "validation_error", "error": "passengers must be an integer between 1 and 100" }

Vehicle categories

transfer_category uses these values. car_model gives the actual make and model (for example "Toyota Hiace"), and seats the real capacity.

Go-live checklist

1. Run a search for a route you sell and show the offers with their price, vehicle and cancellation deadline.
2. Book from the offer id within its validity; if you get offer_expired, search again.
3. Save order_id and pin_code and give the passenger the pin.
4. Call /status before the trip to show the driver and vehicle to your customer.
5. Handle cancellations through /cancel and charge or refund using the returned penalty.
6. Treat { "offers": [] } as "not available", not as a failure.

Questions about the integration? Contact us.