Trip Creation API

Push trip data from any external system — ERPs, custom scheduling tools, other FBO software — directly into AirPlx. One POST request creates trips on your schedule, with the same data quality and aircraft matching as the email integration, but without the email.

How It Works

  External System        POST /api/v1/trips        AirPlx
  (ERP, scheduler,   ----------------------->    processes request,
   custom tool)          with Bearer token         matches aircraft,
                                                   creates trips
                         JSON response
                    <-----------------------     returns per-trip
                                                   status

1. You generate an API key in AirPlx Settings
2. Your system sends a POST request with one or more trips
3. AirPlx matches aircraft, validates data, and creates the trips
4. Each trip gets an individual status in the response (created, duplicate, quarantined, or failed)
5. Trips appear on your schedule immediately

Quick Start

curl -X POST https://tm.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"
      }
    ]
  }'

Authentication

All requests require a Bearer token in the Authorization header. API keys are generated in Settings > Integrations.

Authorization: Bearer ak_your_api_key_here

Each API key is scoped to a single FBO. Requests are authenticated against the FBO that owns the key.

Endpoint Reference

GET /api/v1/auth/verify

Verify your API key is valid and see which FBO it’s scoped to. No data is created — use this to test your credentials before sending trips.

curl https://tm.airplx.com/api/v1/auth/verify \
  -H "Authorization: Bearer ak_your_api_key_here"

Response (200 OK):

{
  "valid": true,
  "fbo_id": "d3b07384-d113-4ec8-...",
  "fbo_name": "Hailey Air Center",
  "key_prefix": "ak_3f7c8a9b",
  "label": "ERP Integration"
}

If the key is invalid, revoked, or disabled, you’ll get a 401.

POST /api/v1/trips

Create one or more trips.

Full curl example:

curl -X POST https://tm.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"
      }
    ]
  }'

Field Reference:

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
  }
}

Per-Trip Statuses:

Error Responses:

400 Error Response Example:

{
  "error": "validation_error",
  "message": "trips[0].tail_number is required"
}

401 Error Response Example:

{
  "error": "unauthorized",
  "message": "Invalid or expired API key"
}

Examples

curl -X POST https://tm.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"
      }
    ]
  }'

import requests
 
response = requests.post(
    "https://tm.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",
            }
        ]
    },
)
 
data = response.json()
for result in data["results"]:
    print(f"{result['tail_number']}: {result['status']}")

const response = await fetch("https://tm.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",
      },
    ],
  }),
});
 
const data = await response.json();
data.results.forEach((result) => {
  console.log(`${result.tail_number}: ${result.status}`);
});

$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"
        }
    )
} | ConvertTo-Json -Depth 3
 
$response = Invoke-RestMethod `
    -Uri "https://tm.airplx.com/api/v1/trips" `
    -Method POST `
    -Headers $headers `
    -Body $body
 
$response.results | ForEach-Object {
    Write-Host "$($_.tail_number): $($_.status)"
}

Batch Requests

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

curl -X POST https://tm.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.

Idempotency

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.

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:

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

Error Handling

There are two levels of errors to handle:

Request-level errors (HTTP 400, 401, 413, 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.

{
  "results": [
    { "external_id": "ERP-001", "status": "created", "trip_id": "...", "tail_number": "N236MJ" },
    { "external_id": "ERP-002", "status": "failed", "tail_number": "N67890", "error": "Invalid arrival_date format" }
  ],
  "summary": {
    "total": 2,
    "created": 1,
    "skipped": 0,
    "quarantined": 0,
    "failed": 1
  }
}

Recommended pattern:

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

API Key Management

API keys are managed in Settings > Integrations.

Generating a key:

1. Click Generate New Key
2. Enter a descriptive label (e.g., “ERP Production”, “Staging Test”)
3. Copy the key immediately — it is only shown once

Revoking a key:

1. Find the key in the API Keys list
2. Click the delete icon
3. Confirm revocation — the key stops working immediately

Enabling/disabling a key:

1. Find the key in the API Keys list
2. Toggle the enabled/disabled switch
3. Disabled keys return 401 Unauthorized — re-enable anytime without generating a new key

FAQ

What format should timestamps be in? ISO 8601 in UTC. The timestamp must end with Z to indicate UTC. Examples: 2026-03-15T14:30:00Z, 2026-03-15T09:00:00Z. The API does not convert local times — always send UTC.

How do I convert my local time to UTC? Subtract your UTC offset. For example, if you’re in US Eastern (UTC-5) and the arrival is 10:00 AM local, send 15:00:00Z. Most programming languages have built-in UTC conversion functions.

Can I update an existing trip via the API? Not currently. The API is create-only. To update a trip, use the AirPlx UI. Update support is planned for a future release.

Can I delete a trip via the API? Not currently. Use the AirPlx UI to remove trips.

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 happens if I omit operator? The trip is still created. Operator is informational only — it helps your team identify who’s operating the aircraft but isn’t required for trip creation.

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.

Is there a rate limit? No. Send as many trips as you need, as often as you need.

Can I test the API without creating real trips? Use a staging environment if one is available for your FBO. Contact AirPlx support to discuss testing options.

What if my external_id values aren’t unique across systems? external_id uniqueness is scoped to your FBO. Two different FBOs can use the same external_id without conflict. Within a single FBO, each external_id must be unique.

Where do quarantined trips go? They appear in your Operations > Inbox. See Aircraft Not Found for the resolution workflow.