Client LoginStart Shipping
Start ShippingClient Login
Navigate
SolutionsPlatformDrive with usTrack your shipment
Company
Who we areCareersContact us
Learn
LearnEmissions
All systems operational

/api/public/v3

The Airspace V3 API is an asynchronous RESTful API for shipment management. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and bearer token authentication.

Build integrations for order creation, quote generation, and active shipment monitoring.

V3 · Current · 3.4.2
Base URL
# Production
https://api.airspace.com/api/public/v3

# Test
https://apitest.airspace.com/api/public/v3

/authentication

All API requests require a bearer token in the Authorization header. Tokens are generated per account and never expire.

Contact integrations@airspace.com to request API keys.

Authorization Header
curl -X GET \
  https://api.airspace.com/api/public/v3/orders \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json"

/environments

Productionlive

For production use. Requires account configuration before first request.

Testsandbox

For development and testing. Behaves the same as production.

Environment URLs
# Production
BASE_URL=https://api.airspace.com/api/public/v3

# Test / Sandbox
BASE_URL=https://apitest.airspace.com/api/public/v3

/quick-start

  1. Get an account — Check with your Airspace Account Manager.
  2. Request a token — Email integrations@airspace.com. Tokens never expire.
  3. Configure test access — We'll set up your sandbox environment.
  4. Set up webhooks — Share your endpoint to receive status updates.
  5. Test end-to-end — Validate your integration in the test environment.
  6. Go live — After successful testing, we'll enable production access.
First Request
curl -X GET \
  https://apitest.airspace.com/api/public/v3/orders \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json"

# 200 OK
{
  "orders": [],
  "message": "Success"
}

/response-codes

Standard HTTP response codes used by the API.

2xx: Success

The request was successfully received, understood, and accepted.

4xx: Client errors

The request contains missing or invalid parameters.

5xx: Server errors

Rare. The server failed to fulfill a valid request.

HTTP Response Codes
// Success
200 OK
202 Accepted

// Client Error
401 Unauthorized
404 Not Found
409 Conflict
422 Unprocessable Entity

// Server Error
500 Internal Server Error
POST/orders

Create a new shipment order.

Request fields

company_idstring

GUID of child company (for multi-company accounts).

pickup_timestring

Scheduled pickup time. Format: "2022-02-25 02:25:00". Must be minimum 2 hours in the future for scheduled orders.

pickup_addressrequired, object

Pickup location. See Address Object below.

delivery_addressrequired, object

Delivery destination. See Address Object below.

referencesrequired, array

Array of reference objects for internal tracking. Each has reference (string, required) and context (string, label/name).

piecesrequired, array

Array of piece objects with dimensions and weight. See Piece Object below.

service_typestring, default "recommended"

One of: recommended, optimize_for_time, optimize_for_cost, optimize_for_green, drive_only.

has_dangerous_goodsrequired, boolean, default false

Whether shipment contains dangerous goods.

should_hold_at_airlinesboolean, default false

Hold at airline for pickup.

email_notificationsarray

Email notification recipients. See Email Notification Object.

airtrace_assignment_overrideboolean

Override existing AirTrace tracker assignment.

required_vehicle_typestring

One of: car, van, truck, flatbed.

custom_attributesarray

Custom attribute objects. See Custom Attributes Object.

shipment_viabilityobject

Viability window. See Shipment Viability Object.

Piece Object

piece_library_guidstring

Reference to saved piece template.

lengthrequired, number

Length of piece.

widthrequired, number

Width of piece.

heightrequired, number

Height of piece.

weightrequired, number

Weight of piece.

weight_unitstring

lb or kg.

dimension_unitstring

in or cm.

commodityrequired, string

Item type description.

do_not_rotateboolean

Prevent piece rotation during transit.

upidsarray

Unique piece identifiers. Each has type (string, required) and value (string, required).

barcodestring

Barcode value.

barcode_typestring

One of: upc_e, ean_13, ean_8, code_39, code_93, code_128, itf, qr, data_matrix, pdf_417.

Address Object

companyrequired, string

Company name.

streetrequired, string

Street address.

street2string

Additional address info.

street3string

Additional address info (non-US only).

cityrequired, string

City.

statestring

State abbreviation.

zipstring

Postal code.

countrystring

ISO 3166-1 alpha-2 code. Supported: US, CA, AU, GB, DE, BR, FR, JP, RU, IN, ID, IT, ES, MX, NO, SE, CO, CN, TR, NZ.

instructionsstring

Driver delivery instructions.

contactrequired, object

Contact details (see Contact Object).

custom_attributesarray

Custom attribute objects.

address_book_guidstring

Reference to saved address from address book.

Contact Object

namerequired, string

Contact name.

phone_numberrequired, string or integer

Phone number. Examples: "6198675309", "619-867-5309", "(619)867-5309".

phone_country_codestring

International dialing code. Default: "1".

Email Notification Object

emailrequired, string

Email address for notifications.

phone_numberstring or integer

Phone for SMS notifications.

phone_country_codestring

International country code for SMS.

exception_emailboolean

Receive exception notifications.

statusesarray

Status values to trigger notifications. Values: customer_completed, ops_acknowledged, auto_dispatch_started, in_route_to_pickup, arrived_at_pickup_location, in_route_to_tender, arrived_at_tender, accepted_by_airline, flight_departed, flight_arrived, reached_destination_airport, in_route_to_recovery, arrived_at_recovery_location, recovered_from_airline, in_route_to_destination, arrived_at_destination, package_accepted.

geofence_miles_deliveryinteger

Mile radius trigger from destination.

geofence_miles_pickupinteger

Mile radius trigger from pickup.

Custom Attributes Object

labelrequired, string

Attribute name.

optionstring or boolean

Configured option value.

weightnumber

Weight value.

weight_unitstring

lbs or kg.

amountnumber

Monetary amount.

currency_codestring

One of: USD, CAD, EUR, GBP, AUD, NZD, CHF, DKK, NOK, SEK, SGD, CNY.

Shipment Viability Object

started_atrequired, string

Start time. Format: "2024-07-10 09:46:00 -0700". If timezone omitted, pickup address timezone is assumed.

durationinteger

Hours of viability. Defaults to account configuration.

POST /orders
curl -X POST \
  $BASE_URL/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_time": "2026-03-20 09:00:00",
    "pickup_address": {
      "company": "Airspace HQ",
      "street": "100 Main St",
      "city": "Carlsbad",
      "state": "CA",
      "zip": "92008",
      "country": "US",
      "contact": {
        "name": "Jane Smith",
        "phone_number": "6195551234"
      }
    },
    "delivery_address": {
      "company": "SF Medical Center",
      "street": "200 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US",
      "contact": {
        "name": "John Doe",
        "phone_number": "4155559876"
      }
    },
    "pieces": [{
      "weight": 5.0,
      "length": 12,
      "width": 8,
      "height": 6,
      "weight_unit": "lb",
      "dimension_unit": "in",
      "commodity": "Medical Device"
    }],
    "references": [{
      "reference": "PO-12345",
      "context": "Purchase Order"
    }],
    "service_type": "recommended",
    "has_dangerous_goods": false
  }'

# 202 Accepted
{
  "message": "Incoming order received. See webhook for order updates.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
GET/orders

List orders with filtering by status, date, references, and commodities.

Query parameters

pageinteger, default 1

Page number.

page_limitinteger, default 10, max 25

Results per page.

from_created_atstring

Minimum creation date (ISO format).

to_created_atstring

Maximum creation date (ISO format).

order[status]string

Filter by status. Use "active" for all active orders.

order[references][reference]string

Filter by reference value.

order[references][context]string

Filter by reference label.

order[pieces][barcode]string

Filter by barcode.

order[pieces][commodity]string

Filter by commodity.

order[has_dangerous_goods]boolean

Filter by dangerous goods flag.

order[service_type]string

Filter by service type.

order[pieces][barcode_type]string

Filter by barcode type.

order[should_hold_at_airlines]boolean

Filter by hold at airlines flag.

GET /orders
curl -X GET \
  "$BASE_URL/orders?page=1&page_limit=10&order[status]=active" \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "orders": [
    {
      "tracking_id": "ATYFGD4P4J",
      "status": "en_route_to_pickup",
      "order_number": 72,
      "created_at": "2026-02-28T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "total_pages": 1,
    "page_limit": 10
  },
  "parameter_errors": {}
}
GET/orders/{tracking_id}

Retrieve details for a specific order by tracking ID.

Path parameters

tracking_idrequired, string

The tracking ID of the order.

Response fields

tracking_idstring

Unique tracking identifier.

tracking_urlstring

Live tracking page URL.

order_numberinteger

Numeric order ID.

statusstring

Current order status.

current_segmentstring

Current operation phase.

estimated_pickup_timestring

ISO 8601 estimated pickup.

estimated_pickup_time_localstring

Local pickup time.

estimated_delivery_timestring

ISO 8601 estimated delivery.

estimated_delivery_time_localstring

Local delivery time.

delivery_timestring

Actual delivery time (when completed).

company_namestring

Associated company name.

piecesarray

Piece objects with current_location (lat, lng, description).

podobject

Proof of delivery with signature_url, name, department, image_urls, documents.

flight_informationobject

Flight details including flights array (each with airline_name, airline_iata, flight_number, departure_airport, departure_airport_iata, departure_time, arrival_airport, arrival_airport_iata, arrival_time, status) and air_waybill_numbers array.

order_sourcestring

Origin: "public_api", "customer_facing", etc.

estimated_pickup_time_timezonestring

Timezone identifier for pickup estimate.

estimated_delivery_time_timezonestring

Timezone identifier for delivery estimate.

pickup_time_localstring

Actual pickup time in local timezone.

delivery_time_localstring

Actual delivery time in local timezone.

delivery_time_timezonestring

Timezone identifier for delivery.

created_atstring

Order creation timestamp.

will_call_activated_atstring

Timestamp when will-call order was activated.

cancelled_atstring

Cancellation timestamp (if applicable).

company_idstring

Associated company GUID.

order_contactsarray

Contact array with email, phone, and notification preferences.

imagesarray

Order images with filename, attachment_url, latitude, longitude, piece_guid.

shipment_viabilityobject

Viability window with viable_until timestamp.

GET /orders/{tracking_id}
curl -X GET \
  $BASE_URL/orders/ATYFGD4P4J \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "tracking_id": "ATYFGD4P4J",
  "tracking_url": "https://track.airspace.com/ATYFGD4P4J",
  "order_number": 72,
  "status": "en_route_to_pickup",
  "current_segment": "drive",
  "estimated_pickup_time": "2026-02-28T11:00:00Z",
  "estimated_delivery_time": "2026-02-28T16:30:00Z",
  "company_name": "Space Air Inc.",
  "pieces": [{
    "commodity": "Medical Device",
    "weight": 5.0,
    "current_location": {
      "lat": 33.1581,
      "lng": -117.3506,
      "description": "En route"
    }
  }],
  "pod": null,
  "flight_information": null,
  "order_source": "public_api"
}
PATCH/orders/{tracking_id}

Update an existing order. Updates are only allowed for orders in pending or customer_completed status. You cannot edit has_dangerous_goods after submission, and you cannot add or remove pieces after submission.

PATCH /orders/{tracking_id}
curl -X PATCH \
  $BASE_URL/orders/ATYFGD4P4J \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [{
      "reference": "PO-9876",
      "context": "Purchase Order"
    }]
  }'

# 202 Accepted
{
  "message": "Order update received.",
  "request_id": "660e8400-e29b-41d4-a716-446655440001"
}
DELETE/orders/{tracking_id}

Cancel an order by tracking ID.

DELETE /orders/{tracking_id}
curl -X DELETE \
  $BASE_URL/orders/ATYFGD4P4J \
  -H "Authorization: Bearer <token>"

# 202 Accepted
{
  "message": "Order cancellation received.",
  "request_id": "770e8400-e29b-41d4-a716-446655440002"
}
PUT/orders/{tracking_id}/activate

Activate a will-call or quote order for immediate dispatch.

Optional parameters

pickup_timestring

Optional scheduled pickup time.

shipment_viabilityobject

Optional viability window.

PUT /orders/{tracking_id}/activate
curl -X PUT \
  $BASE_URL/orders/ATYFGD4P4J/activate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_time": "2026-03-20 09:00:00"
  }'

# 202 Accepted
{
  "message": "Order activation received.",
  "request_id": "880e8400-e29b-41d4-a716-446655440003"
}
PUT/orders/{tracking_id}/test_order_progression

Test environment only. Simulate order status progression for integration testing.

Request fields

progressrequired, array

Array of progression steps.

Valid progress values:

available_for_pickup
in_route_to_pickup
arrived_at_pickup_location
recovered_from_airline
in_route_to_destination
arrived_at_destination
accepted_by_airline
verified_onboard
reached_destination_airport
held_at_warehouse
delivered
add_piece
remove_piece
return_to_sender
wait
error
PUT /orders/{tracking_id}/test_order_progression
curl -X PUT \
  $BASE_URL/orders/ATYFGD4P4J/test_order_progression \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "progress": [
      "available_for_pickup",
      "in_route_to_pickup",
      "arrived_at_pickup_location",
      "in_route_to_destination",
      "arrived_at_destination",
      "delivered"
    ]
  }'

# 202 Accepted
{
  "message": "Test progression initiated.",
  "request_id": "990e8400-e29b-41d4-a716-446655440004"
}
POST/orders/quotes

Generate a pricing estimate for a shipment. The quote uses the same request body structure as order creation.

POST /orders/quotes
curl -X POST \
  $BASE_URL/orders/quotes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pieces": [{
      "weight": 10.0,
      "length": 24,
      "width": 16,
      "height": 12,
      "weight_unit": "lb",
      "dimension_unit": "in",
      "commodity": "Semiconductor"
    }],
    "pickup_address": {
      "company": "LA Warehouse",
      "street": "500 Industrial Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US",
      "contact": {
        "name": "Pickup Contact",
        "phone_number": "2135551234"
      }
    },
    "delivery_address": {
      "company": "Chicago Office",
      "street": "100 Wacker Dr",
      "city": "Chicago",
      "state": "IL",
      "zip": "60601",
      "country": "US",
      "contact": {
        "name": "Delivery Contact",
        "phone_number": "3125559876"
      }
    },
    "references": [{
      "reference": "QUOTE-001"
    }],
    "has_dangerous_goods": false
  }'

# 202 Accepted
{
  "message": "Quote request received.",
  "request_id": "aa0e8400-e29b-41d4-a716-446655440005"
}
GET/orders/quotes/{tracking_id}

Retrieve quote details by tracking ID.

GET /orders/quotes/{tracking_id}
curl -X GET \
  $BASE_URL/orders/quotes/ATYFGD4P4J \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "quote": {
    "estimated_cost": {
      "amount": "359.56",
      "currency": "USD"
    },
    "estimated_delivery_time": "2026-03-01T14:00:00Z",
    "order_details": {
      "tracking_id": "ATYFGD4P4J",
      "service_type": "recommended",
      "pieces": [...]
    }
  }
}
POST/orders/will_call

Create a will-call order. Will-call orders are held until explicitly activated.

POST /orders/will_call
curl -X POST \
  $BASE_URL/orders/will_call \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pieces": [{...}],
    "pickup_address": {...},
    "delivery_address": {...}
  }'

# 200 OK
{
  "tracking_id": "AIR-2026-WC-9012",
  "status": "will_call"
}
PATCH/orders/will_call/{tracking_id}

Update an existing will-call order before activation.

PATCH /orders/will_call/{tracking_id}
curl -X PATCH \
  $BASE_URL/orders/will_call/AIR-2026-WC-9012 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_address": {
      "street": "300 Updated Ave"
    }
  }'
GET/invoices

List invoices for your account. Requires account configuration.

Query parameters

pageinteger, default 1

Page number.

page_limitinteger, default 10, max 25

Results per page.

from_created_atstring

Minimum creation date.

to_created_atstring

Maximum creation date.

order[from_created_at]string

Filter by minimum order creation date.

order[to_created_at]string

Filter by maximum order creation date.

GET /invoices
curl -X GET \
  "$BASE_URL/invoices?page=1&page_limit=10" \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "invoices": [...],
  "pagination": {
    "page": 1,
    "total_pages": 1,
    "page_limit": 10
  }
}
GET/address_books

List saved addresses from your address book. Returns array of address book entries with contact info, coordinates, and schedule blocks.

GET /address_books
curl -X GET \
  $BASE_URL/address_books \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "addresses": [
    {
      "id": 1,
      "name": "HQ Carlsbad",
      "street": "5640 Kearny Mesa Rd",
      "city": "Carlsbad",
      "state": "CA"
    }
  ]
}
GET/piece_libraries

List saved piece types for reuse across orders.

GET /piece_libraries
curl -X GET \
  $BASE_URL/piece_libraries \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "pieces": [
    {
      "id": 1,
      "name": "Standard Box",
      "weight": 5.0,
      "length": 12,
      "width": 8,
      "height": 6
    }
  ]
}
GET/orders/events
GET/orders/{tracking_id}/events

Retrieve order events. Use the global endpoint for all events with the same query parameters as List Orders, or filter by tracking ID.

GET /orders/{tracking_id}/events
curl -X GET \
  $BASE_URL/orders/ATYFGD4P4J/events \
  -H "Authorization: Bearer <token>"

# 200 OK
{
  "tracking_id": "ATYFGD4P4J",
  "company_name": "Space Air Inc.",
  "company_id": "ABCD123456",
  "order_number": 72,
  "events": [
    {
      "type": "status",
      "name": "customer_completed",
      "occurred_at_utc": "2026-02-28T10:00:00Z",
      "message": null,
      "delay_code": null,
      "delay_category": null,
      "delay_description": null
    }
  ]
}

/webhooks

Webhooks provide push notifications for order status updates rather than requiring polling. Configure your endpoint during onboarding.

Configuration Requirements

  • Your endpoint must accept POST requests with JSON payload.
  • Return a 2xx status code on successful receipt.
  • Handle dynamic payload structures based on order state.
  • Use order.tracking_id or order.order_number for identification.
  • Use request_id field to correlate with original API requests.

Setup Information

Contact integrations@airspace.com with:

  • Endpoint URL
  • Environment (test, production, or both)
  • Authentication method (username-password, bearer token, or OAuth)
  • Content type (JSON)
  • Request method (PUT or POST)

Event Types

Three webhook event types: milestone (status updates), delay, and cancellation.

Webhook payload fields

messagestring

Status description.

request_idstring

Matches initial API response request_id.

eventsarray

Event objects with milestone, occurred_at.

errorsobject or null

Error information.

updated_order_keysarray

Modified field names.

orderobject

Complete order object at time of event.

Webhook Payloads
// Status Update Webhook
{
  "message": "Order status is now en_route_to_destination",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "events": [{
    "milestone": {},
    "occurred_at": "2026-01-22T15:30:45.123Z"
  }],
  "errors": null,
  "updated_order_keys": ["status"],
  "order": { ... }
}

// Delay Event
{
  "events": [{
    "event_type": "delay",
    "problem": {
      "code": "2-001",
      "description": "Changed shipment parameters",
      "delivery_eta": "2026-01-23T16:00:00.000Z",
      "note": ""
    }
  }]
}

// Cancellation Event
{
  "events": [{
    "event_type": "cancellation",
    "problem": {
      "code": "2-007",
      "description": "Nothing to Pick Up",
      "delivery_eta": null,
      "note": "Shipment no longer needed"
    }
  }]
}

/reference/statuses

All possible order statuses in the V3 API.

will_callUnrouted order with expiration (typically 72 hours)
pendingQuote needing submission
customer_completedOrder created for fulfillment
ops_acknowledgedOperations team reviewed
available_for_pickupDriver assigned
en_route_to_pickupDriver traveling to pickup
arrived_at_pickup_locationDriver at pickup location
en_route_to_destinationDriver en route to airport (NFO only)
accepted_by_airlineDelivered to airline (NFO only)
verified_onboardBoarded on plane (NFO only)
reached_destination_airportArrived at destination (NFO only)
available_for_recoveryAvailable for airport pickup (NFO only)
in_route_to_recoveryEn route to airport (NFO only)
arrived_at_recovery_locationArrived at airport (NFO only)
recovered_from_airlinePicked up from airport (NFO only)
arrived_at_destinationDriver at destination (drive-only)
arrived_at_destination2Driver at destination (NFO only)
deliveredOrder delivered
admin_canceledOrder canceled
Status Flow
// Typical order lifecycle
will_call
  → pending
    → customer_completed
      → ops_acknowledged
        → available_for_pickup
          → en_route_to_pickup
            → arrived_at_pickup_location

// Drive-only path
  → en_route_to_destination
    → arrived_at_destination
      → delivered

// NFO (Next Flight Out) path
  → en_route_to_destination
    → accepted_by_airline
      → verified_onboard
        → reached_destination_airport
          → available_for_recovery
            → in_route_to_recovery
              → arrived_at_recovery_location
                → recovered_from_airline
                  → arrived_at_destination2
                    → delivered

// Terminal
  → delivered
  → admin_canceled

/reference/service-types

recommendedBest balance of speed and cost
optimize_for_timeFastest delivery option
optimize_for_costMost cost-effective option
optimize_for_greenLowest carbon footprint
drive_onlyGround transport only, no flights
Service Types
{
  "service_type": "recommended"
}

// Options:
// "recommended"
// "optimize_for_time"
// "optimize_for_cost"
// "optimize_for_green"
// "drive_only"

/reference/vehicle-types

carStandard sedan for small shipments
vanCargo van for medium shipments
truckBox truck for large shipments
flatbedFlatbed truck for oversized cargo

If a larger vehicle type is requested than required, additional charges may apply. If a smaller vehicle type is sent, Airspace will override with the system-determined vehicle based on piece count, dimensions, and weight.

Vehicle Types
{
  "required_vehicle_type": "van"
}

// Options:
// "car"
// "van"
// "truck"
// "flatbed"

/reference/error-codes

Standard error response formats by HTTP status code.

Error Responses
// 401 Unauthorized
{
  "error": "Unauthorized"
}

// 404 Not Found
{
  "error": "Not Found"
}

// 422 Unprocessable Entity
{
  "errors": {
    "bad_attribute": ["is not allowed"]
  }
}

Ready to integrate?

Contact our integrations team to get your API keys and start building with Airspace.

Request API Access