Your First Check-in

This guide walks you through creating a complete check-in request, from verifying airline support to receiving the boarding pass.

Before You Start

Make sure you have:

  • A sandbox API key (get one here)
  • Flight details (PNR, airline, flight number, date)
  • Passenger information (name, optionally DOB and passport)
Sandbox vs. production base URL. The curl examples below use a portal-issued 1ci_live_ key at https://portal.1checkin.com/api/corp/v1/... with the placeholder YOUR_PRODUCTION_API_KEY. While testing with a sandbox key (prefix 1ci_test_), substitute the URL https://1checkin.com/api/sandbox/v1/... AND the placeholder YOUR_SANDBOX_KEY. The sandbox uses the same check-in request schema and simulates airline responses.

Step 1: Check Airline Availability

Before creating a check-in, verify that we support the airline and route. This prevents wasted API calls and helps you provide better feedback to users.

Check if a route is supported
curl
curl -X POST "https://portal.1checkin.com/api/corp/v1/checkAvailable" \
  -H "X-API-KEY: YOUR_PRODUCTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "airline_code": "BA",
    "departure_code": "LHR",
    "destination_code": "JFK"
  }'

If the response shows "result": true, the route is supported and you can proceed to create the check-in.

Availability response
json
{
  "result": true,
  "is_free_try_available": false
}
When does check-in open? Most airlines open check-in 24 hours before departure. After you create the check-in (next step), the response carries scheduled_checkin_time: the planned time our worker will attempt the check-in.

Step 2: Create the Check-in Request

Now submit the check-in request with all passenger and flight details:

Create check-in request
curl
curl -X POST "https://portal.1checkin.com/api/corp/v1/checkins" \
  -H "X-API-KEY: YOUR_PRODUCTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remote_id": "MY-BOOKING-001",
    "passengers": [{
      "first_name": "John",
      "last_name": "Smith",
      "remote_id": "pax_1",
      "date_of_birth": "1985-03-15"
    }],
    "flights": [{
      "booking_ref": "ABC123",
      "marketing_carrier_code": "BA",
      "operating_carrier_code": "BA",
      "flight_num": "178",
      "departure_date": "2026-02-15",
      "departure_time": "10:30",
      "departure_code": "LHR",
      "destination_code": "JFK"
    }],
    "seatStrategies": ["one_psg_window"]
  }'

Understanding the Response

The response is wrapped in a booking envelope: a booking_idplus an array of checkins (one per flight segment). Passenger and flight details are nested under each check-in's data.

POST /checkins response (HTTP 201)
json
{
  "booking_id": 980972996354,
  "checkins": [{
    "id": 504061687271,
    "booking_id": 980972996354,
    "remote_id": "MY-BOOKING-001",
    "data": {
      "remote_id": "MY-BOOKING-001",
      "passengers": [{
        "num": 1,
        "remote_id": "pax_1",
        "first_name": "John",
        "last_name": "Smith",
        "seat": null,
        "boarding_seat": null,
        "boarding_info": null
      }],
      "flights": [{
        "num": 1,
        "booking_ref": "ABC123",
        "marketing_carrier_code": "BA",
        "operating_carrier_code": "BA",
        "flight_num": "178",
        "departure_date": "2026-02-15",
        "departure_time": "10:30",
        "departure_code": "LHR",
        "destination_code": "JFK"
      }],
      "seatStrategies": ["one_psg_window"]
    },
    "files": [],
    "status": "idle",
    "fail_reason": null,
    "scheduled_checkin_time": "2026-02-14T10:30:00+00:00",
    "finished_time": null
  }]
}

Save the check-in id (e.g. 504061687271) and your own remote_id. You will need them to poll status and to look up the boarding pass.

Use the individual checkins[].id for GET /checkin/{id}. The response's booking_id identifies the booking and is a different resource ID.

Note: the scheduled_checkin_time field is the planned start of the check-in attempt (often 24 hours before departure; timing depends on the airline). It is not a completion timestamp. idle is a pending, nonterminal state and can remain while automation is working; reaching the scheduled time does not guarantee an immediate result. The eventual terminal status is success, failed, or aborted if you cancel it. When the automation needs more data first, it pauses in requested_extra_info — the Z0 test scenario 201 demonstrates that flow.

Step 3: Wait for Check-in

The check-in transitions through a small set of statuses:

idle

Pending: waiting for its scheduled start or still being processed

→
success

Checked in. Boarding pass is in files[]

On failure, status transitions to failed and fail_reason is populated with a numeric code (see Error handling). You can poll status or receive webhook notifications (see Webhook setup):

Check status
curl
curl -X GET "https://portal.1checkin.com/api/corp/v1/checkin/504061687271" \
  -H "X-API-KEY: YOUR_PRODUCTION_API_KEY"

Step 4: Get the Boarding Pass

Once status is success, the response from GET /checkin/{id} includes the boarding pass under files[]. Each entry is a direct download URL:

GET /checkin/{id} response after a successful check-in
json
{
  "id": 504061687271,
  "status": "success",
  "fail_reason": 100,
  "data": {
    "passengers": [{
      "num": 1,
      "remote_id": "pax_1",
      "first_name": "John",
      "last_name": "Smith",
      "boarding_seat": "14A",
      "boarding_info": {
        "pnr": "ABC123",
        "seat": "14A",
        "flight": "BA 178",
        "origin": "LHR",
        "destination": "JFK",
        "first_name": "John",
        "last_name": "Smith"
      }
    }],
    "flights": [/* ... */]
  },
  "files": [{
    "url": "https://files.example.com/boarding-pass.pdf?SIGNED_QUERY",
    "filetype": "boardingPass",
    "file_type": "boardingPass",
    "content_type": "application/pdf",
    "expires": 1809849600
  }],
  "scheduled_checkin_time": "2026-02-14T10:30:00+00:00",
  "finished_time": "2026-02-14T10:30:14+00:00"
}

In production, files[].url is the upstream signed, absolute download URL. Its host can differ from the API host. Use the exact returned URL, including its query string, in a plain GET without your API key; do not prepend the API base URL or replace its hostname. files.example.com above is illustrative, not a production hostname or an allowlist.

Sandbox downloads instead use the /api/sandbox/v1/files/... route on 1checkin.com. Do not construct production download URLs from that sandbox path.

Download the boarding pass
curl
"token-comment"># Pull the file URL from the response and GET it directly:
curl -sS -o boarding-pass.pdf "$BOARDING_PASS_URL"
One file per passenger. Multi-passenger bookings return one files[] entry per passenger; iterate the array to download each. Both PDF and Apple Wallet (.pkpass) formats appear as separate entries when both are produced; check filetype and content_type to distinguish.

Multiple Passengers

To check in multiple passengers on the same booking, include them all in the passengers array:

Multiple passengers
json
{
  "remote_id": "FAMILY-TRIP-001",
  "passengers": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "remote_id": "pax_1",
      "date_of_birth": "1985-03-15"
    },
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "remote_id": "pax_2",
      "date_of_birth": "1987-07-22"
    },
    {
      "first_name": "Jimmy",
      "last_name": "Smith",
      "remote_id": "pax_3",
      "date_of_birth": "2015-09-10"
    }
  ],
  "flights": [{
    "booking_ref": "ABC123",
    "marketing_carrier_code": "BA",
    "operating_carrier_code": "BA",
    "flight_num": "178",
    "departure_date": "2026-02-15",
    "departure_time": "10:30",
    "departure_code": "LHR",
    "destination_code": "JFK"
  }],
  "seatStrategies": ["three_psg_three_together"]
}

Multi-Segment Trips

For connecting flights or round trips, include multiple segments:

Multi-segment booking
json
{
  "remote_id": "ROUND-TRIP-001",
  "passengers": [{
    "first_name": "John",
    "last_name": "Smith",
    "remote_id": "pax_1",
    "date_of_birth": "1985-03-15"
  }],
  "flights": [
    {
      "booking_ref": "ABC123",
      "marketing_carrier_code": "BA",
      "operating_carrier_code": "BA",
      "flight_num": "178",
      "departure_date": "2026-02-15",
      "departure_time": "10:30",
      "departure_code": "LHR",
      "destination_code": "JFK"
    },
    {
      "booking_ref": "ABC123",
      "marketing_carrier_code": "BA",
      "operating_carrier_code": "BA",
      "flight_num": "179",
      "departure_date": "2026-02-22",
      "departure_time": "18:00",
      "departure_code": "JFK",
      "destination_code": "LHR"
    }
  ],
  "seatStrategies": ["one_psg_window"]
}

Common Issues

PNR Not Found

The booking reference wasn't found in the airline system. Check that:

  • The PNR is correct (no typos, correct case)
  • The booking exists with the airline (not just a travel agent reference)
  • The passenger names match exactly

Check-in Already Complete

Someone has already checked in for this flight. This can happen if:

  • The passenger checked in manually
  • You submitted a duplicate request

Passport Required

International flights require passport details. Add them to your request:

json
{
  "first_name": "John",
  "last_name": "Smith",
  "date_of_birth": "1985-03-15",
  "passport_number": "AB1234567",
  "passport_expiry_date": "2030-05-15",
  "citizenship": "GB"
}

Next Steps