GGT WORLDWISE Booking API

Overview

One call creates a job request in GGT WORLDWISE and gives you back a ggt_id — the booking reference that appears on every confirmation, notice, brief and invoice for that trip. Quote it to us and we both mean the same piece of work.

Eight fields are required: who the job is for, what service you want, where it starts and ends, what kind of place each end is, and when. Everything else is optional and can be filled in by a GGT operator afterwards.

A job created here lands on Needs Quote/Confirm. An operator reviews it before anything reaches a supplier. Nothing is dispatched, and no email goes to a traveller or a vendor, on the strength of an API call alone — so a bad call is a tidy-up, never a car at the wrong airport.

Getting access

1. Register at api.ggtinternal.com and confirm your email.
2. A test key is issued straight away. It authenticates and reads, but will not create a job.
3. GGT links your account to the customer accounts you book for. This is a person's decision, not an automatic one.
4. Once linked, create a live key in the portal. That key creates real jobs.

Authentication

Send your key in an X-API-Key header on every request. Authorization: Bearer <key> works too, if your HTTP client prefers it.

X-API-Key: ggt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Conventions

• HTTPS only. Plain HTTP is redirected; do not follow the redirect with a key attached.
• JSON in, JSON out. Send Content-Type: application/json on a POST.
• Dates are YYYY-MM-DD. Times are HH:MM, 24-hour, local to the pick-up — not UTC. A car arrives at a kerb at a local time, and that is the only time anybody involved uses.
• Every reply carries ok and request_id. Quote the request_id when you ask us about a call.
• Unknown fields in a request body are ignored, so we can add fields without breaking you.

Create a job

The smallest call that works — the eight required fields:

curl -X POST https://api.ggtinternal.com/v1/jobs \
  -H "X-API-Key: ggt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": 1054,
    "serviceTypeId": 1,
    "pickup": "Fairmont Monte Carlo, 12 Avenue des Spelugues, 98000 Monaco",
    "pickup_type": "address",
    "dropoff": "LFMN/NCE - Nice Cote d Azur",
    "dropoff_type": "fbo",
    "service_date": "2026-11-02",
    "service_time": "08:50"
  }'

A fuller one

Everything below is optional. The more you send, the less an operator has to ask you for.

{
  "cid": 1054,
  "serviceTypeId": 1,
  "customer_ref": "PO-44821",
  "pickup": "Fairmont Monte Carlo, 12 Avenue des Spelugues, 98000 Monaco",
  "pickup_type": "address",
  "dropoff": "LFMN/NCE - Nice Cote d Azur",
  "dropoff_type": "fbo",
  "service_date": "2026-11-02",
  "service_time": "08:50",
  "passenger_first": "Masaya",
  "passenger_last": "Kaji",
  "pax_count": 2,
  "bag_count": 3,
  "vehicle_id": "11",
  "icao": "LFMN",
  "city": "Nice",
  "country": "France",
  "tail_no": "N811TM",
  "flight_no": "BAW327",
  "etd": "11:35",
  "meeting_point": "Lobby",
  "stops": ["Hotel Metropole, Monte Carlo"],
  "notes": "Two child seats. Driver to wait if the flight slips.",
  "booker_name": "Alex Rowe",
  "booker_email": "alex@example.com",
  "booker_phone": "+1 713 555 0134"
}

Fields

serviceTypeId — what you are asking for

GGT runs other services — aircraft guard, security briefs, meet and greet, tour guides — but those are arranged with us directly rather than booked through the API.

pickup_type and dropoff_type

Vehicles

Send vehicle_id as the id or the name — both are accepted.

What gets checked

Every field is validated before anything is written, and you are told about all the problems at once rather than one refusal at a time. The same rules apply when you change a job.

Addresses

Pick-ups and drop-offs go through Google's geocoder. Three outcomes:

• Found. Accepted, and the response carries a resolved object showing what we understood it as — worth logging, so you can see when a caller's address was understood as somewhere surprising.
• Found approximately. Accepted, with a warnings entry naming what it matched. GGT's own airport style — LFMN/NCE - Nice Cote d Azur — matches approximately and is perfectly fine.
• Not found at all. Refused with address_not_found. A driver cannot be sent to a string that is not a place.

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "3 fields need attention.",
    "fields": [
      { "field": "service_date", "code": "bad_date",
        "message": "Must look like 2026-11-04 (YYYY-MM-DD, four-digit year first).", "got": "04/11/2026" },
      { "field": "icao", "code": "unknown_icao",
        "message": "Not an airport we have on file. Use the ICAO (EGLL) or the IATA (LHR).", "got": "XXXX" },
      { "field": "dropoff", "code": "address_not_found",
        "message": "We could not find that location. Give a place name, street and town — or for an airport, the ICAO and name, like \"LFMN/NCE - Nice Cote d Azur\".",
        "got": "asdkjh 99999" }
    ]
  },
  "request_id": "c41e7a09b2d85f36"
}

What comes back

201 Created, and the booking number.

{
  "ok": true,
  "ggt_id": 368952,
  "cid": 1054,
  "customer": "Your Company Ltd",
  "customer_ref": "PO-44821",
  "status": "Needs Quote/Confirm",
  "status_id": 11,
  "service_date": "2026-11-02",
  "service_time": "08:50",
  "serviceTypeId": 1,
  "service": "Executive Transport",
  "trip_type": "Departure",
  "pickup": "Fairmont Monte Carlo, 12 Avenue des Spelugues, 98000 Monaco",
  "dropoff": "LFMN/NCE - Nice Cote d Azur",
  "message": "Created. A GGT operator reviews it before anything is sent to a supplier.",
  "request_id": "a3f91c20d4e8b771"
}

Store the ggt_id. It is how GGT refers to the trip in every later conversation, email and invoice.

Change a job

Correct a job you created. You can only touch jobs belonging to a cid your key is linked to — anything else answers 404, exactly as if it did not exist.

Two required things: the ggt_id, and what to change.

curl -X PATCH https://api.ggtinternal.com/v1/jobs \
  -H "X-API-Key: ggt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "ggt_id": 368950, "field": "service_time", "value": "09:15" }'

Several at once, if you prefer:

{
  "ggt_id": 368950,
  "fields": {
    "service_time": "09:15",
    "pax_count": 3,
    "passenger_last": "Kajiyama"
  }
}

What comes back

{
  "ok": true,
  "ggt_id": 368950,
  "cid": 1054,
  "mode": "live",
  "changed": ["service_time"],
  "before":  { "service_time": "08:50" },
  "after":   { "service_time": "09:15" },
  "message": "Updated service_time.",
  "request_id": "b8c4e1d79a2f0356"
}

You get before and after so your own audit trail can record what actually moved, rather than what you intended to move.

What can be changed, and when

Only these fields. The customer, the status, the vendor, the booking number and anything to do with money are set by GGT and are not reachable from here.

Read a job back

Returns the job as it now stands, including the status an operator has moved it to. Works for jobs belonging to any customer your key is linked to — however the job was created, so a trip somebody booked by email shows up here too.

curl "https://api.ggtinternal.com/v1/jobs?ggt_id=368952" \
  -H "X-API-Key: ggt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A job belonging to a customer you are not linked to answers 404 not_found — the same as one that does not exist. Whether a booking exists is not something this API will confirm to somebody with no business knowing.

Your customers

The customer accounts this key may create jobs for. Only yours — this is not a directory of GGT's clients.

{
  "ok": true,
  "count": 2,
  "customers": [
    { "cid": 1054, "company": "Your Company Ltd", "department": null },
    { "cid": 1180, "company": "Another Account", "department": "Trip Support" }
  ],
  "request_id": "7bd0115ac9e34428"
}

Check a key

Creates nothing. Run it first, and run it again whenever something stops working — it tells you whether the key is good, which environment it is, and whether the account is allowed to create jobs yet.

{
  "ok": true,
  "account":  { "company": "Your Company Ltd", "email": "alex@example.com", "status": "approved" },
  "key":      { "label": "Production server", "environment": "live" },
  "can_create_jobs": true,
  "why": "This key creates real jobs.",
  "customer_ids": [ { "cid": 1054, "company": "Your Company Ltd" } ],
  "server_time_utc": "2026-10-19T13:06:52Z",
  "request_id": "19c7a84be0d2f563"
}

Sandbox

A test key puts every call in the sandbox. Same URLs, same validation, same errors, same shape of answer — but jobs are written to a test table and never reach the reservation system, and the booking number starts at 9,000,001 so it is obviously not a real one.

Try it without writing any code

The portal has a live console: pick an endpoint, edit the JSON, press send, read the real response. Useful for seeing what a validation failure looks like before you have to handle one.

Your key is not on that page. The console posts to a server-side helper that holds the key — the same rule as everywhere else, applied to our own screen.

What is different

Every reply carries mode. Assert on it in your test suite and you can never ship a build that was quietly pointing at production.

{
  "ok": true,
  "mode": "sandbox",
  "ggt_id": 9000001,
  "cid": 1054,
  "status": "Needs Quote/Confirm",
  "message": "Created in the sandbox. Nothing real was booked and no car exists. Use a live key when you are ready.",
  "request_id": "0d7e4f1a93b6c258"
}

Errors

A failure is JSON too, with a stable error.code worth branching on and an error.message for a human. Where it helps, the error carries the detail that makes it fixable — which field, which cid, what was allowed.

{
  "ok": false,
  "error": {
    "code": "cid_not_allowed",
    "message": "This key is not linked to customer 999. GET /api/dev/v1/customers lists the ones it may book for.",
    "cid": 999,
    "allowed_cids": [1054, 1180]
  },
  "request_id": "5f2ab8c17d904e36"
}

Retrying safely

A timed-out create is the normal way a duplicate booking happens: your side gives up, you send it again, and two cars turn up. Send an Idempotency-Key header — any string you generate per booking attempt — and a repeat returns the first job rather than making a second.

curl -X POST https://api.ggtinternal.com/v1/jobs \
  -H "X-API-Key: ggt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-44821-leg1" \
  -d '{ "cid": 1054, "pickup": "…", "dropoff": "…",
        "service_date": "2026-11-02", "service_time": "08:50" }'

The replay answers 200 rather than 201, carries "idempotent_replay": true and an Idempotent-Replay: true header. Use one key per booking you intend to make — not one per process, or your second genuine booking will be swallowed.

Rate limits

60 requests per minute per key, counted over the trailing minute. Over it you get 429 rate_limited and a Retry-After header.

If you need more for a bulk load, write to us rather than spreading the work over several keys — we would rather raise the limit than guess why one account has eleven keys.

Going live

When the sandbox is doing what you want, this is the whole list:

1. Make a live key on the keys page. It only appears once your account is linked to customer accounts.
2. Swap the key in your config. Nothing else changes — not the URL, not the body, not your error handling.
3. Call GET /v1/ping and check "mode": "live".
4. Create one real job, and look at it in GGT with us on the phone the first time.

What we do not store

• No payment details, ever. This API has no card, bank or payment field, and anything of the sort in notes is a mistake — send it to us another way. Billing runs on the account, not on the booking call.
• Request bodies are kept against your account and shown on your usage page, so you can see what you sent when a call fails. Treat them as you would your own logs: no card numbers, no passport numbers, nothing you would not want kept.
• Passenger names are kept because the driver needs them. Send an alias instead where a principal would rather not be named — GGT uses the alias throughout if one is set.