Connect your operator business with GrabJet

This page is for operators who want to work with GrabJet. If you do not have your own software, you can use the GrabJet operator portal. If you already manage aircraft, availability, or dispatch in another tool, you can connect by webhook or API after onboarding.

This page is intentionally focused on small operators using GrabJet's simple API or webhook flow.

If you are a local operator, start here. You can become operational in GrabJet through the portal first, then add API/webhook automation only when your team is ready.

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/aircraft" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gj_sandbox_..." \
  -H "Idempotency-Key: evt_aircraft_1001" \
  -H "X-GrabJet-Event: aircraft.updated" \
  -d @aircraft.updated.json

If your operator system is ready to integrate, use this order. It covers what you send to GrabJet, what GrabJet sends back, and what your admin reviewer needs before production access.

GrabJet issues sandbox access before production access. Production credentials are issued only after sandbox testing and admin review are complete.

The operator integration service supports intake, authentication, idempotency, normalization, validation, staging, and review for all data areas below. Valid records can then be reviewed and applied through GrabJet's controlled core-service workflow.

Operators do not need to choose only one integration style. GrabJet supports a practical hybrid model: portal for human workflows, API for direct pushes, inbound webhooks for operator events, and outbound webhooks for GrabJet events sent back to the operator.

Third-party data never writes straight into GrabJet's core aircraft, booking, dispatch, payout, or customer-facing systems. Every external event first passes through staging, validation, conflict checks, and audit. This protects both the operator and GrabJet from bad payloads, duplicate events, and booking conflicts.

Not every operator enables every module. During onboarding, GrabJet confirms which modules are enabled, who owns conflicts, and how often data should arrive. Critical operational events should be webhook-first; master data can usually sync on change or by schedule.

GrabJet tracks operators by origin and operating model. Some operators are created directly by GrabJet operations, some arrive through the public request flow, and local third-party operators can connect through API or signed webhook once sandbox access is issued.

Prepare these items before onboarding. Some fields can be completed later, but faster verification depends on clear company, fleet, document, and operations data.

1. 1Submit the operator application or contact the GrabJet partnership team.
2. 2GrabJet verifies company, AOC/operating certificate, documents, region, fleet, and contacts.
3. 3GrabJet admin creates or approves the operator profile.
4. 4Operator admin users are invited to the GrabJet operator portal.
5. 5Operator adds or confirms aircraft, routes, empty-leg rules, payout details, and operational contacts.
6. 6GrabJet reviews aircraft readiness, airport compatibility, documents, and commercial setup.
7. 7Operator starts receiving and managing bookings in the portal.
8. 8API/webhook automation is enabled later only if the operator needs it.

For most local operators, this is the real starting point. The portal gives the operator a full workflow without requiring any API build.

For most local operators, no API is required at the beginning. GrabJet can onboard you through the operator portal first. API key and signed webhook modes are used only when your team wants automated sync.

After sandbox approval, GrabJet issues environment-specific credentials. Keep these values server-side only. Never put API keys or webhook secrets in browser JavaScript, mobile apps, public Git repositories, screenshots, or client-side logs.

# .env
GRABJET_ENV=sandbox
GRABJET_BASE_URL=https://api.grabjet.com/
GRABJET_OPERATOR_ID=op_123
GRABJET_API_KEY=gj_sandbox_...
GRABJET_WEBHOOK_SECRET=whsec_...

# Never commit these values.
# Store production credentials in a server-side secret manager.

GrabJet keeps integration changes stable and versioned. Developers should safely ignore unknown optional fields and pin integrations to the documented API version.

Sandbox limits protect the shared onboarding environment. Production limits are adjusted after expected module volume and sync frequency are reviewed.

This section applies only if the operator uses API or webhook automation. Portal-only operators do not need these headers.

Inbound endpoints are used when an operator sends data to GrabJet from its own system. These endpoints are sandbox-first and require authentication plus idempotency.

Most public operator endpoints are write-first. If a future endpoint returns lists, use this standard pagination shape so client code stays consistent across API versions.

GET /api/v1/integrations/operators/op_123/sync-runs?page=1&page_size=25&direction=desc

{
  "success": true,
  "data": [],
  "metadata": {
    "total": 124,
    "page": 1,
    "page_size": 25,
    "total_pages": 5,
    "has_next": true
  }
}

Every write request follows the same pattern: send JSON to the module endpoint, include your sandbox API key, include a unique idempotency key, and set the event name in X-GrabJet-Event. Use the language tab that matches your operator system.

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/aircraft" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_aircraft_1001" \
  -H "X-GrabJet-Event: aircraft.updated" \
  -d @aircraft.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/availability" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_availability_1002" \
  -H "X-GrabJet-Event: availability.updated" \
  -d @availability.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/crew" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_crew_1003" \
  -H "X-GrabJet-Event: crew.updated" \
  -d @crew.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/maintenance" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_maintenance_1004" \
  -H "X-GrabJet-Event: maintenance.release.updated" \
  -d @maintenance.release.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/pricing" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_pricing_1005" \
  -H "X-GrabJet-Event: pricing.updated" \
  -d @pricing.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/bookings" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_booking_response_2001" \
  -H "X-GrabJet-Event: booking.accepted" \
  -d @booking.accepted.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/empty-legs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_empty_leg_1006" \
  -H "X-GrabJet-Event: empty_leg.updated" \
  -d @empty_leg.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/flight-status" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_flight_status_1007" \
  -H "X-GrabJet-Event: flight.status_changed" \
  -d @flight.status_changed.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/dispatch-compliance" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_dispatch_1008" \
  -H "X-GrabJet-Event: dispatch.readiness.updated" \
  -d @dispatch.readiness.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/dispatch-compliance" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_compliance_1011" \
  -H "X-GrabJet-Event: dispatch.compliance.updated" \
  -d @dispatch.compliance.updated.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/finance-payouts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_payout_1009" \
  -H "X-GrabJet-Event: payout.status_changed" \
  -d @payout.status_changed.json

curl -X POST "https://api.grabjet.com//api/v1/integrations/operators/op_123/notifications" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRABJET_API_KEY" \
  -H "Idempotency-Key: evt_notification_1010" \
  -H "X-GrabJet-Event: notification.delivery.updated" \
  -d @notification.delivery.updated.json

Outbound events are sent by GrabJet to the operator system when GrabJet needs acceptance, cancellation sync, dispatch visibility, or finance visibility.

GrabJet outbound delivery is queue-based. That means core booking and dispatch work can continue even if an operator endpoint is temporarily unavailable. Operators should build receivers that are fast, duplicate-safe, and easy to retry.

If GrabJet sends events to your system, your receiver must be reliable, quick to acknowledge, and safe against duplicates.

These are the practical integration flows most operators implement first. Treat each row as a real-world sandbox workflow before going live.

Local operators should send GrabJet's generic contract. Canonical IDs are welcome, but stable local references such as booking_reference, empty_leg_reference, payout_reference, notification_reference, crew_reference, and flight_reference are also accepted.

Every endpoint uses a shared event envelope plus module-specific fields inside data. During onboarding, GrabJet can map small additional operator fields into this structure.

Use these examples to understand the expected event envelope. The exact field mapping can be adjusted during onboarding, but every event should include a stable event reference and operator reference.

{
  "event_id": "evt_aircraft_1001",
  "event_type": "aircraft.updated",
  "operator_reference": "OP-ACME-001",
  "occurred_at": "2026-06-29T10:30:00Z",
  "data": {
    "tail_number": "N900GJ",
    "aircraft_type": "Gulfstream G650",
    "seats": 14,
    "max_range_nm": 7000,
    "current_airport": "OMDB",
    "status": "available",
    "maintenance_release_status": "released",
    "mel_cdl_restricted": false
  }
}

Idempotency prevents duplicate bookings, duplicated aircraft updates, and repeated webhook side effects when networks timeout or operators retry requests.

Operators should retry safely based on response status. When retrying a write request after a timeout or 5xx, use the same idempotency key.

Failed requests return a stable error envelope. Validation errors do not apply data into core systems; they are recorded for review.

{
  "success": false,
  "error": {
    "code": "invalid_payload",
    "message": "tail_number is required",
    "field": "data.tail_number",
    "request_id": "req_01J..."
  }
}

Use this table when a sandbox request fails. Most failures are caused by wrong environment credentials, missing module permissions, duplicate idempotency keys, or payload mapping differences.

Use status codes to decide whether to retry, fix the payload, or contact GrabJet support. Always retry write requests with the same idempotency key.

Successful responses confirm whether GrabJet accepted the event immediately or staged it for manual review. A 2xx response does not always mean the data was directly applied to production core records.

{
  "success": true,
  "data": {
    "event_id": "evt_aircraft_1001",
    "operator_id": "op_123",
    "module": "aircraft",
    "status": "accepted",
    "stage": "validated",
    "duplicate": false,
    "request_id": "req_01J...",
    "received_at": "2026-06-29T10:30:02Z"
  }
}

{
  "success": true,
  "data": {
    "event_id": "evt_availability_1002",
    "status": "staged_for_review",
    "attention_required": true,
    "reason": "availability conflicts with active GrabJet booking hold",
    "conflict_reference": "conflict_789"
  }
}

Use these values where applicable. If your system has different values, map them during onboarding instead of sending unknown statuses directly.

For API/webhook operators, GrabJet expects signed payloads. Sign the raw JSON request body with the webhook secret issued during onboarding.

signature = HMAC_SHA256(
  secret = webhook_secret,
  message = raw_request_body
)

Header:
X-GrabJet-Signature: sha256=<hex_digest>

import crypto from "node:crypto"

export function verifyGrabJetSignature(rawBody, signatureHeader, webhookSecret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", webhookSecret)
    .update(rawBody, "utf8")
    .digest("hex")

  const expectedBuffer = Buffer.from(expected)
  const receivedBuffer = Buffer.from(signatureHeader || "")

  return expectedBuffer.length === receivedBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
}

GrabJet can provide a sandbox Postman collection or OpenAPI file after operator approval. Until credentials are issued, use the files below to prepare payloads and environment variables.

GRABJET_BASE_URL = https://api.grabjet.com/
GRABJET_OPERATOR_ID = op_123
GRABJET_API_KEY = gj_sandbox_...
GRABJET_WEBHOOK_SECRET = whsec_...

These starter files make the docs easier to test locally. Replace sample values with sandbox credentials after GrabJet approves your operator access.

GrabJet does not require a heavy SDK. Many operators can use a tiny server-side helper around fetch or requests. Keep credentials on the server.

class GrabJetClient {
  constructor({ baseUrl, apiKey, operatorId }) {
    this.baseUrl = baseUrl.replace(/\/$/, "")
    this.apiKey = apiKey
    this.operatorId = operatorId
  }

  async postModule(modulePath, eventName, idempotencyKey, payload) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/integrations/operators/${this.operatorId}/${modulePath}`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-Key": this.apiKey,
          "Idempotency-Key": idempotencyKey,
          "X-GrabJet-Event": eventName,
        },
        body: JSON.stringify(payload),
      }
    )

    if (!response.ok) throw new Error(await response.text())
    return response.json()
  }
}

Before asking for live access, run these tests in sandbox. This protects the operator and GrabJet from duplicate events, bad payloads, booking conflicts, and broken webhook retry behavior.

Use this checklist before asking GrabJet for production access. It gives both teams a simple pass/fail view of whether sandbox worked.

Production access requires basic integration security controls. GrabJet may request screenshots, logs, or implementation notes for these items during go-live review.

GrabJet can pause integration traffic without shutting down the operator's core portal workflow. These controls are designed for safety incidents, bad data, endpoint failures, credential exposure, or supervised go-live decisions.

Portal-only operators can go live after business verification, fleet readiness, payout setup, and portal training. API-connected operators need the additional technical checks below.

Shared language for operators, developers, and operations teams during integration work.

Track public integration doc and API contract changes here. Operators should review changelog entries before production credential upgrades.

Common questions from operators and engineering teams during onboarding.

During onboarding, GrabJet separates business, operations, technical, and finance support so each issue reaches the right team quickly.