Dealer Listings API

Quickstart

A dealer creates a key in their dashboard under Settings → Integrations and gives it to whoever builds the connection. Send it on every request as a bearer token, from a server — never from a web page.

curl https://aircraftforsale.com/api/dealer/v1/me \
  -H "Authorization: Bearer $AFS_KEY"

curl -X PUT https://aircraftforsale.com/api/dealer/v1/listings/STK-1042 \
  -H "Authorization: Bearer $AFS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "2019 Cirrus SR22T G6 GTS",
    "make": "Cirrus",
    "model": "SR22T G6",
    "year": 2019,
    "price": 849000,
    "registration": "N219GT",
    "serialNumber": "1734",
    "totalTime": 640,
    "location": "Scottsdale, AZ, United States",
    "description": "One owner, hangared since new.",
    "sections": { "avionics": "Perspective+ by Garmin\nGFC 700 autopilot" },
    "images": ["https://yoursite.com/aircraft/1042/1.jpg"],
    "agentEmail": "[email protected]"
  }'

curl -X PUT https://aircraftforsale.com/api/dealer/v1/listings/STK-1042 … -d '{ …same fields…, "status": "sold" }'

curl -X DELETE https://aircraftforsale.com/api/dealer/v1/listings/STK-1042 \
  -H "Authorization: Bearer $AFS_KEY"

Try any PUT with ?dryRun=true first: it validates the body and tells you how we would file the make and model, without writing anything.

How it works

• Your id, in the URL. Each aircraft is addressed by your own externalId — a stock number or CMS post id. Keep it stable: it is how we know a second request is the same aircraft.
• Send the whole aircraft. PUT replaces the listing’s content with what you send; a field you leave out is cleared (except listingType). Sending the same body again changes nothing, so a nightly full sync is fine.
• No duplicates. If the dealer already has a listing with us for the same registration (or serial number), the first PUT adopts it — outcome: "adopted" — rather than creating a second.
• Review. New listings are checked by our team before they go live, usually within a business day. Updates to a live listing appear at once. If one is rejected, reviewNote says why; fix it and PUT again to resubmit. GET /me shows whether your account is reviewed or publishes directly.
• Photos. Send public JPEG, PNG or WebP URLs in display order; the first is the cover. We copy them to our own storage after the response, a few at a time, so photos.pending stays true for a few minutes on a large gallery. URLs we already hold are never downloaded again.
• Makes and models. Use the names from GET /makes to land in the right category. Anything else is filed under its make and flagged for our team, which shows as a reviewNote.
• Text. Description and section fields take plain text (line breaks kept) or simple HTML — paragraphs, lists, bold, links. Anything else is removed.

Listing statuses

Every response reports the listing’s status as one of these.

live

on the site

in_review

waiting for our team

rejected

see reviewNote, fix and PUT again to resubmit

sold

withdrawn

taken down (PUT for_sale to relist)

expired

removed

by our team

not_listed

we hold the record but never listed it (e.g. it was sold before you first sent it)

Limits

Every authenticated request counts as one call against the account’s monthly allowance, which resets on the 1st (UTC). Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. There is also a ceiling of 120 requests a minute.

A nightly sync of the whole inventory costs one call per aircraft. To save calls, send only what changed — and remember a resend of an unchanged aircraft still counts.

Errors

Errors are JSON: { "error": { "code", "message", "field"? } }. Branch on code, not on the message. Retry 5xx and 429 with backoff.

Endpoints

Base URL https://aircraftforsale.com/api/dealer/v1

Listing fields

The body of PUT /listings/{externalId}. Required: title, make, model. Unknown fields are refused, so a typo fails loudly.

sections

The spec sections on the listing page. Omit one to leave it empty.