Creating Trips

POST /api/v1/trips — Create one or more trips in a single request.

Request Format

Send a JSON body with a trips array containing one or more trip objects.

Field	Required	Type	Description
`tail_number`	Yes	string	Aircraft registration (e.g., `N236MJ`, `G-LUXE`, `VHVKX`)
`arrival_date`	No	string	Arrival date/time in UTC. ISO 8601 format (e.g., `2026-03-15T14:30:00Z`). Defaults to now if omitted.
`external_id`	No	string	Your system’s unique identifier for this trip. Used for duplicate prevention — sending the same `external_id` twice won’t create a duplicate. Auto-generated if omitted.
`departure_date`	No	string	Departure date/time in UTC. ISO 8601 format. Omit if departure is unknown — the trip will show as an open-ended stay.
`confirmation_code`	No	string	Your reference number for this trip
`operator`	No	string	Operating company name (e.g., `NetJets Aviation`)
`aircraft_type`	No	string	ICAO type designator (e.g., `GL6T`, `G280`, `C680`). If omitted, AirPlx looks it up automatically from the tail number.
`notes`	No	string	Free-text notes attached to the trip

All timestamps must be in UTC. Use ISO 8601 format with the Z suffix (e.g., 2026-03-15T14:30:00Z). Unlike the email integration, the API does not convert local times to UTC — you must do this yourself before sending. If you send 2026-03-15T08:00:00Z that means 8:00 AM UTC, not 8:00 AM in your local timezone.

Code Examples

curl


curl -X POST https://api.airplx.com/api/v1/trips \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "trips": [
      {
        "tail_number": "N236MJ",
        "arrival_date": "2026-03-15T14:30:00Z",
        "departure_date": "2026-03-17T10:00:00Z",
        "external_id": "ERP-2026-00142",
        "confirmation_code": "REF-001",
        "operator": "NetJets Aviation",
        "aircraft_type": "GL6T",
        "notes": "VIP handling requested"
      }
    ]
  }'

Python


import requests
 
response = requests.post(
    "https://api.airplx.com/api/v1/trips",
    headers={
        "Authorization": "Bearer ak_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "trips": [
            {
                "tail_number": "N236MJ",
                "arrival_date": "2026-03-15T14:30:00Z",
                "departure_date": "2026-03-17T10:00:00Z",
                "external_id": "ERP-2026-00142",
                "confirmation_code": "REF-001",
                "operator": "NetJets Aviation",
                "aircraft_type": "GL6T",
                "notes": "VIP handling requested",
            }
        ]
    },
)
 
data = response.json()
for result in data["results"]:
    print(f"{result['tail_number']}: {result['status']}")

Node.js


const response = await fetch("https://api.airplx.com/api/v1/trips", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ak_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    trips: [
      {
        tail_number: "N236MJ",
        arrival_date: "2026-03-15T14:30:00Z",
        departure_date: "2026-03-17T10:00:00Z",
        external_id: "ERP-2026-00142",
        confirmation_code: "REF-001",
        operator: "NetJets Aviation",
        aircraft_type: "GL6T",
        notes: "VIP handling requested",
      },
    ],
  }),
});
 
const data = await response.json();
data.results.forEach((result) => {
  console.log(`${result.tail_number}: ${result.status}`);
});

PowerShell


$headers = @{
    "Authorization" = "Bearer ak_your_api_key_here"
    "Content-Type"  = "application/json"
}
 
$body = @{
    trips = @(
        @{
            tail_number       = "N236MJ"
            arrival_date      = "2026-03-15T14:30:00Z"
            departure_date    = "2026-03-17T10:00:00Z"
            external_id       = "ERP-2026-00142"
            confirmation_code = "REF-001"
            operator          = "NetJets Aviation"
            aircraft_type     = "GL6T"
            notes             = "VIP handling requested"
        }
    )
} | ConvertTo-Json -Depth 3
 
$response = Invoke-RestMethod `
    -Uri "https://api.airplx.com/api/v1/trips" `
    -Method POST `
    -Headers $headers `
    -Body $body
 
$response.results | ForEach-Object {
    Write-Host "$($_.tail_number): $($_.status)"
}

Response

Response (200 OK):


{
  "results": [
    {
      "external_id": "ERP-2026-00142",
      "status": "created",
      "trip_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tail_number": "N236MJ"
    }
  ],
  "summary": {
    "total": 1,
    "created": 1,
    "skipped": 0,
    "quarantined": 0,
    "failed": 0
  }
}

Each trip in the results array gets one of these statuses:

Status	Meaning
`created`	Trip was successfully created and appears on your schedule
`duplicate`	A trip with the same `external_id` already exists — no new trip created
`quarantined`	Aircraft tail number not found in AirPlx — trip queued in Operations Inbox for review
`failed`	Processing error for this specific trip — see the `error` field for details

Sending Multiple Trips

Send multiple trips in a single request. Each trip is processed independently — one failure doesn’t affect others.


curl -X POST https://api.airplx.com/api/v1/trips \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "trips": [
      {
        "tail_number": "N236MJ",
        "arrival_date": "2026-03-15T14:30:00Z",
        "departure_date": "2026-03-17T10:00:00Z",
        "external_id": "BATCH-001"
      },
      {
        "tail_number": "N700GS",
        "arrival_date": "2026-03-16T09:00:00Z",
        "departure_date": "2026-03-16T18:00:00Z",
        "external_id": "BATCH-002"
      },
      {
        "tail_number": "UNKNOWN",
        "arrival_date": "2026-03-16T12:00:00Z",
        "external_id": "BATCH-003"
      }
    ]
  }'

Response:


{
  "results": [
    { "external_id": "BATCH-001", "status": "created", "trip_id": "...", "tail_number": "N236MJ" },
    { "external_id": "BATCH-002", "status": "created", "trip_id": "...", "tail_number": "N700GS" },
    { "external_id": "BATCH-003", "status": "quarantined", "tail_number": "UNKNOWN" }
  ],
  "summary": {
    "total": 3,
    "created": 2,
    "skipped": 0,
    "quarantined": 1,
    "failed": 0
  }
}

The summary object gives you a quick count without iterating through results. There is no limit on the number of trips per request — send as many as you need.

Duplicate Prevention

The external_id field serves as an idempotency key. If you send a request with an external_id that already exists for your FBO, the trip is not created again — the response returns duplicate status for that trip.

First request returns status: "created". Second request with the same external_id returns status: "duplicate".

This makes it safe to retry failed requests without worrying about creating duplicate trips. If your system isn’t sure whether a previous request succeeded, send it again.

Use whatever uniquely identifies a trip in your source system — an ERP record ID, a booking reference, a scheduling system key. As long as it’s unique within your FBO, it works. Two different FBOs can use the same external_id without conflict.

Aircraft Not Found

When the tail number in your request isn’t in the AirPlx database, the trip is not silently dropped. Instead, it’s queued in your Operations Inbox for review — the same flow as the email integration.

The response shows status: "quarantined" for that trip:


{
  "external_id": "ERP-2026-00199",
  "status": "quarantined",
  "tail_number": "ZK-NZE"
}

To resolve quarantined trips:

Go to Operations > Inbox in AirPlx
Find the queued item
Add the aircraft to AirPlx (or correct the tail number if it was a typo)
Process the item from the Inbox

Error Handling

There are two levels of errors to handle:

Request-level errors (HTTP 400, 401, 500) mean the entire request failed. No trips were processed. Fix the issue and retry the full request.

Per-trip errors (HTTP 200 with status: "failed" on individual trips) mean the request was accepted but specific trips couldn’t be processed. Other trips in the same batch may have succeeded. Check the error field on failed trips for details.

Status Code	Meaning
400 Bad Request	Missing `trips` array, invalid JSON, missing required fields
401 Unauthorized	Invalid, expired, or missing API key
500 Internal Server Error	Retry after a short delay

Recommended handling pattern:

Check the HTTP status code first
If 200, iterate through results and check each trip’s status
Log or alert on failed items
Retry failed items after fixing the data (use external_id so created items aren’t duplicated)

FAQ

What happens if I omit departure_date? The trip is created with an open-ended stay. You can update the departure time later in the AirPlx UI when it becomes known.

What happens if I omit aircraft_type? AirPlx looks up the aircraft type from the tail number in its database. If the tail number is found, the type is filled in automatically. If not, the trip is quarantined for review.

What format should timestamps be in? ISO 8601 in UTC with the Z suffix. Example: 2026-03-15T14:30:00Z. Subtract your UTC offset from local time — if you’re in US Eastern (UTC-5) and the arrival is 10:00 AM local, send 15:00:00Z.