GuidesAPI Reference
Guides

Pick-up time vs Flight departure time

When booking transfers via the API, the way you provide the flight/pickup time reference depends on how your agency account is configured.
There are two different modes:

  1. Flight (or Ship/Train) departure time based (System calculates pickup time)
  2. Pick-up time based (You specify exact pickup time)

Understanding the difference is important to avoid errors or passengers missing their transfers.

🔹 Flight departure time based (default)

  • Instead of telling us when to pick up the passengers, you provide the arrival/departure time of their flight/ship/train.
  • Our system automatically calculates the best pick-up time based on:
    • Distance to the arrival/departure point
    • Service rules (e.g. check-in windows, required arrival buffer at airports)

Key points

  • Use the field flight_date_time, ship_date_time, or train_date_time depending on the type of service.
  • The pick-up time is not required in your request – it will be calculated automatically..

Example:

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN",
      "flight_date_time": "2025-09-03T15:35:00"
    }
  }
}
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
    }
  },
  "destination": {
    "train": {
      "train_number": "FRT-345",
      "train_date_time": "2025-09-03T15:35:00"
    }
  }
}
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
    }
  },
  "destination": {
    "cruise": {
      "cruise_line": "Carnival Cruise Line",
      "ship_name": "A-Rosa Aqua",
      "cruise_terminal": "TERMINAL-1",
      "ship_date_time": "2025-09-03T15:35:00"
    }
  }
}
📘

Special feature for Flight departure time based accounts

Pick-up time override — private vehicles only

Even if your account is Flight departure time based, you may explicitly set the pick-up time for private vehicles by including pickup_date_time together with the relevant departure time field.

Rules

  • ✅ Allowed only for private transfers with destination to gateways
  • ❌ Not allowed for shuttles (shared services).
  • Required fields in the same request:
    • pickup_date_time (your exact desired pick-up time)
    • flight_date_time / ship_date_time / train_date_time (kept for validation, routing, and comms)
  • Responsibility: when you override pick-up time, you must ensure sufficient buffer for check-in/security.

Example

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T13:15:00"
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN",
      "flight_date_time": "2025-09-03T15:35:00"
    }
  }
}
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T13:15:00"
    }
  },
  "destination": {
    "train": {
      "train_number": "FRT-345",
      "train_date_time": "2025-09-03T15:35:00"
    }
  }
}
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T13:15:00"
    }
  },
  "destination": {
    "cruise": {
      "cruise_line": "Carnival Cruise Line",
      "ship_name": "A-Rosa Aqua",
      "cruise_terminal": "TERMINAL-1",
      "ship_date_time": "2025-09-03T15:35:00"
    }
  }
}

🔹 Pick-up time based

  • Optional configuration that must be requested through our B2B commercial team before use.
  • In this case, agencies must provide the exact pick-up date and time (pickup_date_time) in the request.
  • The driver will be scheduled to arrive at the exact time provided.
  • No automatic calculation of pick-up time is done by the system.

Example

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T15:35:00"
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN"
    }
  }
}
🚧

Shuttle to a gateway (airport/port/station)

Even when your account is pick‑up time based, if you are booking a shuttle vehicle and the destination is a gateway (airport, port or train station), you must always also provide the departure date/time for the gateway service:

  • Send pickup_date_time and the corresponding flight_date_time / ship_date_time / train_date_time.
  • Rationale: shared services require a verified departure time to allocate routeing and arrival buffers.

Example (pick‑up based + shuttle to airport — both values required)

{
  "outward": {
    "accommodation": {
      "name": "Hotel Barbarà",
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T14:05:00"
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN",
      "flight_date_time": "2025-09-03T18:35:00"
    }
  }
}

Summary

  • Agencies can configure transfers using either flight/ship/train departure time (default) or exact pick-up time (on request).
  • In departure time-based mode, only the departure time is needed; the system calculates the optimal pick-up time.
  • A manual override for pick-up time is allowed for private transfers in departure time-based mode, but both pick-up and departure times must be provided.
  • In pick-up time-based mode, agencies must supply the exact pick-up time; no automatic calculation is done.
  • For shuttles to gateways, even in pick-up time-based mode, the departure time is always required to ensure proper routing.

If you are unsure which mode your agency account uses, please check with your Suntransfers B2B commercial contact.