Skip to content

Automation and API tokens

An assistant connection is a person's: it acts for the signed-in user, inside a conversation. A scheduled job — a sync every hour, a watcher on arrivals, an invoice export — is not a conversation, and it does not go through this connector. It uses your personal API token, on the same two Freight Right APIs the connector reads.

One credential, both APIs

In Shipment Manager, Profile → API tokens makes a personal token (up to three per account). It is the service credential for your own jobs, on both APIs:

  • the Shipment Visibility API: your shipments in full, a shipment's billing and customs entries, its documents as short-lived download links, your invoices across shipments, and the events feed;
  • the rates API: prices, quote requests, quotes and requests to our team.

The same Authorization: Bearer <token> header serves both. A token sees exactly what your account sees in Shipment Manager, and it does not expire until you revoke it on that page. A Freight Right administrator's token is refused by the Visibility API, which serves customer accounts (an administrator reaches shipments through the connector).

Environment Shipment Visibility API documentation
Production https://api.freightright.com/api/public/v1/docs
Staging https://staging-backend.sm.freightright.com/api/public/v1/docs

The rates API documents itself on its own /docs page, linked from the API tokens page.

Polling for what changed

GET /api/public/v1/shipments/events is the change signal: one event per thing that happened to a shipment your account can see — created, a milestone recorded, an ETA changed, arrived, delivered, a last free day set, available for pickup, a document added, an invoice added or paid, archived, a booking cancelled — oldest first, paged by a cursor. A job polls it like this:

  1. Start once. Call without a cursor to begin at the oldest event still retained (about 90 days; history begins when the feed was switched on for the environment), or with since=<RFC 3339 UTC> to begin later. Keep the types filter you want for good: a cursor carries its filters, and a cursor replayed with other filters is refused.
  2. Keep the cursor. Every page answers next_cursor and has_more. Store the cursor after you have processed the page, and send it back on the next poll. Events are delivered at least once across retries: keep the event_ids you have seen and skip a repeat.
  3. Be polite. Poll every few minutes, not every second; a 429 answer carries Retry-After, honour it. Billing events need the billing permission of the token's account and document events the documents permission — without them those events are simply absent, never an error. 
curl -H "Authorization: Bearer $FR_TOKEN" \\
  "https://api.freightright.com/api/public/v1/shipments/events?limit=200&types=ARRIVED&types=DELIVERED"

Then ?cursor=<next_cursor> with the same types on every poll after that.

updated_since is not a change signal

The shipment list's updated_since filter is for a full resync only. Freight Right re-stamps every active shipment every night, so a recent updated_since returns all of them, changed or not. Use it when you need the current state of everything; use the events feed to learn what changed.

What an assistant does with the same data

The connector's freightright_list_shipment_events reads the same feed for the signed-in user, on request, inside a conversation ("what changed on my shipments since yesterday?"). It is the right tool for a person asking; it is not a way to run a job, because a connection belongs to the person who approved it and lives as long as they keep it.