SAMO·TRANS
Telegram
API documentation

Integrate the SAMO-TRANS exchange into your TMS or CRM

API documentation

Events

Overview and quick start

What the SAMO-TRANS API does, who can use it, how to get a key and make your first request.

The SAMO-TRANS API lets you work with the exchange directly from your TMS, CRM or in-house system: search cargo and transport, publish and update your own listings, and receive events about new offers matching your lanes.

It is the same engine the website runs on — a listing created through the API appears in search exactly like one created by hand.

Who can use it

The API is part of the PREMIUM plan. Keys are issued by the company owner in the dashboard under Settings → API. If the plan is downgraded, keys stop working and the company's webhooks are switched off automatically; everything resumes when PREMIUM is restored.

Base URL

https://api.samo-trans.com/api/public/v1

The public API lives outside the versioned /api/v1 prefix the website itself uses. The exact address for your environment is always shown on the API page in the dashboard.

Your first request

  1. Open Settings → API and click "Create key".
  2. Copy the key immediately — it is shown once and cannot be recovered.
  3. Send it in the Authorization header:
export SAMO_KEY="samo_live_XXXXXXXXXXXXXXXXXXXXXXXX"

curl "https://api.samo-trans.com/api/public/v1/reference/countries" \
  -H "Authorization: Bearer $SAMO_KEY"

Response:

[
  { "code": "UA", "name": "Ukraine" },
  { "code": "PL", "name": "Poland" }
]

If you get a 401, check that the key was copied in full including the samo_live_ prefix, and that the word Bearer precedes it.

Where to go next

  • Authentication — keys, scopes, IP restrictions.
  • Rate limits — per-minute and per-day budgets, how to react to 429.
  • Pagination and sync — the cursor, and the right way to keep your own copy of the data fresh.
  • Idempotency — safe retries for writes.
  • Webhooks — events instead of polling, including new listings matching your search.
  • Examples — ready-to-run curl for every endpoint group.
  • Errors — the response envelope and the full code list.
  • Endpoint reference — every method, parameter and schema.

Conventions

  • JSON over UTF-8. Send request bodies with Content-Type: application/json.
  • Dates are ISO 8601 strings (2026-08-12T00:00:00.000Z).
  • Money is returned as a string ("price": "24500") so no precision is lost to floating point.
  • Every error arrives in a stable envelope carrying a requestId — quote it when contacting support.