Connect Terminal49: track containers by container, bill of lading or booking number

Get a free Developer Key yourself at app.terminal49.com/developers/api-keys, paste it as the single api_key field in Integration, test, map and activate — container milestones, vessel schedules and terminal availability then feed your drayage tracking.

The Terminal49 connector does one job: container tracking for drayage. You start tracking with a container number, a bill of lading number or a booking number, and the connector brings back milestones, vessel schedules and terminal availability — including the Last Free Day, holds and fees reported by the terminal. That is the whole scope: it does not pull orders, does not create shipments or dispatches, does not book terminal appointments, and does not write anything back to Terminal49. One connection works with one Terminal49 API Key.

Prerequisites#

• A Terminal49 account you can sign in to at app.terminal49.com, so you can open the developer API keys page yourself. The key is self-service: no sales call and no approval wait are needed to start.
• At least one container, bill of lading or booking number you actually want to track, so you can check the first results against a shipment you know.
• Know your tracking volume before you rely on the free key: a free Developer Key tracks up to 100 containers. That is plenty to evaluate the connection, but plan the key you will use in production around the number of containers you track at the same time.

Get your credentials#

1. Sign in at app.terminal49.com and open the developer API keys page: app.terminal49.com/developers/api-keys.
2. Create a key there. A free Developer Key is enough to connect and evaluate: it tracks up to 100 containers.
3. Copy the full API Key at once and keep it ready to paste. Do not shorten it and do not add any prefix to it — the key on its own is the whole credential.
4. There is only this one credential. There is no separate username, password, sandbox key or second key to collect, and test and production use the same Terminal49 address — the same key is what you test with and what you run with.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Terminal49 → New connection.
2. api_key — required, Terminal49 API Key: paste the full key you copied from app.terminal49.com/developers/api-keys. It is the only field on this connection. It is a password-type field and is stored as a secret. Paste the key only, with no "Token" or "Bearer" word in front of it — the system adds the header form itself.
3. Save the connection, then run the test before you change anything else — with one field, a failing test is about that key, not about finding which of many fields is wrong.

Test the connection#

Click Test connection. With your key filled in, the test sends one real, read-only request: GET https://api.terminal49.com/v2/tracking_requests?page[size]=1, with your key sent as "Authorization: Token <API_KEY>", with a 12-second timeout. It only reads the first page of your existing tracking requests, so it changes nothing in Terminal49. A passing answer comes back as "Terminal49 authentication passed". If the key is refused, the test reports HTTP_401. If api_key is empty, it stops with MISSING_CREDENTIALS. A request that cannot be completed reports CONNECTION_FAILED. Fix the cause named by the result, then test again.

Mapping / pick a template#

Pick the Terminal49 standard mapping. It takes each tracking result Terminal49 returns — milestones, vessel schedule, and terminal availability such as Last Free Day, holds and fees — and lines it up with the container record you follow in drayage tracking here. After the test passes, start tracking for one container, bill of lading or booking you know, and compare the milestones and the terminal dates side by side with what Terminal49 shows for the same shipment. If they match, the mapping is right and you can activate.

Activate#

After activation, you can start tracking from a container number, a bill of lading number or a booking number — give one of the three, plus the carrier SCAC when you have it — and the connection keeps the milestones, vessel schedule and terminal availability for those containers updated here. Tracking requests are limited to 100 per minute on the Terminal49 side, so very large bulk starts are spread out rather than fired all at once. Watch the first tracking results in Runs / Logs and compare a few containers with Terminal49 before leaving the connection unattended.

What this connection does not do: it does not pull orders or shipments from any other system, it does not create dispatches or loads, it does not book or change terminal appointments, and it does not send tracking data back to Terminal49. It also only tracks containers you start tracking for — it does not discover or import your whole shipment history from Terminal49.

FAQ#

Test fails with HTTP_401

Terminal49 refused the key you sent. The usual causes are a key that was trimmed while copying, an extra word pasted in front of it, or a key that was deleted or replaced in your Terminal49 account after you copied it. The address and the connection are fine — this code is only about the key itself.

Open app.terminal49.com/developers/api-keys, create a fresh key, copy it in full with nothing in front of it, paste it into the api_key field, save, and test again. If you were checking the API by hand, remember the header form is "Authorization: Token <API_KEY>" — a Bearer-style check fails even with the right key.

Test stops with MISSING_CREDENTIALS

The api_key field is empty, so there is no key to send and the test cannot check anything. This connection has exactly one field, so there is nowhere else the credential could be hiding.

Paste the full key from app.terminal49.com/developers/api-keys into api_key, save the connection, and test again.

Test fails with CONNECTION_FAILED, or times out after 12 seconds

The read-only request to the Terminal49 API could not be completed in time. That is a reachability problem on the way to api.terminal49.com, or a temporary Terminal49 slowdown — it is not proof that the key is wrong, because the key is only judged once the API actually answers.

Wait a short while and test again without changing the key. If it keeps failing, note the failing time from Runs / Logs when you ask for help, so the window can be checked against the Terminal49 side.

Starting tracking fails with INVALID_REQUEST

No identifier was given for the tracking request. Terminal49 starts tracking from one identifier — a container number, a bill of lading number or a booking number — and with none of the three there is nothing to start.

Start the tracking again with one of the three numbers for that shipment, and add the carrier SCAC when you have it — it helps Terminal49 match the request to the right carrier.

Starting tracking fails with HTTP_429 when many containers are started at once

You hit the Terminal49 rate limit: tracking requests are capped at 100 per minute. Nothing is wrong with the key or with the containers that failed — they were simply sent faster than Terminal49 accepts them.

Start the failed containers again in smaller batches, spread over more than a minute, instead of retrying the whole set at once. The ones that already started keep tracking normally.

New containers stop being tracked after about 100

You are on the free Developer Key, which tracks up to 100 containers. The connection and the key are working — the first hundred prove that — but the free key has no room for more containers at the same time.

Move the connection to a Terminal49 key with a container allowance that fits your live volume: create or obtain that key in your Terminal49 account, paste it into api_key in place of the free key, save and test. Tracking already started under the free key is not a setting in this system — check the key allowance first whenever volume grows.