Skip to content

Qargo TMS Subcontractor/fleet API (1.2.0)

Subcontractor/fleet dispatch API documentation

What's new — see the Changelog for recent additions and changes to the API.

Authentication

The api requires oauth2 authentication with client id/secret. This should only be used for service to service communication.

Creating application credentials

Application client credentials can be created by users with the Super admin role in the Qargo application. Users can create and remove application clients by navigating to Configuration -> Organisation Settings (API clients sections).

Applications need to be linked to a valid integration id, identifying the Qargo approved integrator. Please contact us if you don't have an id yet.

Obtaining an access token

To interact with the API, you need a valid access token in JWT (JSON Web Token) format. This token authenticates your requests and authorizes access to protected endpoints. The process involves using Basic Authentication to request the token via the /auth/token endpoint.

The /auth/token endpoint can be used to generate an access token (JWT):

This token will need to be refreshed after expiration (we provide the 'expires_in' in the token response to check validity).

Understanding Basic Authentication

Basic Authentication is a simple HTTP authentication scheme that allows clients to provide credentials (such as a client ID and secret) directly in the request header. It works by encoding the credentials in Base64 and including them in the Authorization header of the HTTP request. For example:

  • Format: Authorization: Basic <base64-encoded-credentials>
  • Credentials Encoding: The client ID and secret are concatenated with a colon (e.g., client_id:secret_id) and then Base64-encoded.

The API Call to Request Tokens

The /auth/token endpoint is a POST request used to generate a JWT access token. You authenticate this request using Basic Auth with your provided client_id and secret_id.

Request Details

  • Method: POST
  • URL: https://api.qargo.com/v1/auth/token
  • Headers:
    • Content-Type: application/json
    • Authorization: Basic <base64-encoded-client_id:secret_id>
  • Body: Empty.
  • Parameters: None.

Example using curl:

curl -XPOST https://api.qargo.com/v1/auth/token -H 'Content-type: application/json' -u '<client_id:secret_id>'

Webhook authentication

Important: Webhook endpoints use a different authentication method than regular API endpoints. Do not use OAuth tokens for webhooks.

Qargo webhooks, such as those for order import and status updates, use Basic Authentication instead of OAuth. See Understanding Basic Authentication for details on the Basic Auth scheme.

Webhook credentials (client id and secret id) are provisioned by Qargo when your webhook integration is configured — contact integrations@qargo.com to obtain them. They are separate from your API credentials and must be used exclusively for webhook endpoints.

API vs Webhook authentication summary

API endpointsWebhook endpoints
Auth methodOAuth2 (Client Credentials)Basic Authentication
CredentialsAPI client_id + secret_id → Bearer JWT tokenWebhook client_id + secret_id (directly in header)
Header formatAuthorization: Bearer <jwt_token>Authorization: Basic <base64(client_id:secret_id)>
Where to find credentialsConfiguration → Organisation Settings → API clientsProvisioned by Qargo — contact integrations@qargo.com
Token refresh needed?Yes (JWT expires)No (credentials sent with each request)

Common mistake

Webhook credentials can technically be used to obtain an OAuth token via the /auth/token endpoint, but this token will not work for authenticating webhook requests. Always use Basic Authentication with your webhook credentials directly in the Authorization header.

Example webhook request

curl -XPOST https://api.qargo.com/v1/webhook/order-import \
  -H 'Content-Type: application/json' \
  -u '<webhook_client_id>:<webhook_secret_id>' \
  -d '{ ... }'

Rate Limits

To maintain API stability and prevent abuse, we enforce rate limits on a per-tenant basis.

Limits

The limits below are estimates based on normal operating conditions. Under increased system load, these limits may be tightened without prior notice to protect API stability.

CategoryScopeLimit
Authentication/auth/token5 requests per hour
General API UsageAll endpoints except authentication and webhooks2 requests per second (sustained); up to 3 per second (bursts)

Enforcement

Rate limits are enforced by tracking requests over several sliding time windows-per second, per 10 minutes, and per hour. Exceeding any of these limits will result in an HTTP 429 Too Many Requests response. The response includes a Retry-After header specifying the number of seconds your application should wait before making a new request.

Timeline showing how to pace API requests, wait with jitter after a 429 response, and retry successfully

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 58

{"error":"Rate limit exceeded"}

Applications must handle this response correctly by treating Retry-After as the minimum delay, regardless of whether the request appeared to be within the estimated limits. If multiple workers or processes can make requests for the same tenant, add a small positive random delay (jitter) after Retry-After before retrying. Never subtract jitter or retry earlier than indicated. If another 429 response is returned, repeat this process using the latest Retry-After value.

For any concerns about these limits, please contact us at integrations@qargo.com.

API Best Practices

This section outlines recommended practices for efficiently working with the Qargo API.

Pagination

Some list endpoints support cursor-based pagination. Paginated responses contain items and next_cursor. When next_cursor is not null, pass its value unchanged as the cursor query parameter in the next request. Do not combine cursor with other query parameters.


How pagination works

  1. Initial request: Make a request to a paginated endpoint without a cursor parameter.
  2. Process the response: Read the current page from items.
  3. Subsequent requests: If next_cursor is not null, pass its value as the cursor parameter in the next request.
  4. Stop: Repeat until next_cursor is null.

Example usage

GET /v1/resources/resource

Response:

{
  "items": [
    {
      "name": "Truck 142",
      "row_id": "3f9e6b1c-3333-4d2e-b1a4-7c8f9e0a1b03"
    }
  ],
  "next_cursor": "eyJwYXJhbWV0ZXJzIjp7fSwic3RhdGUiOiJhYmMxMjM0NSIsImN1cnNvcl9zb3J0IjoiMjAyNi0wOC0xMlQxMDowMDowMFoiLCJjdXJzb3JfaWQiOiIzZjllNmIxYy0zMzMzLTRkMmUtYjFhNC03YzhmOWUwYTFiMDMifQ=="
}

Next request:

GET /v1/resources/resource?cursor=eyJwYXJhbWV0ZXJzIjp7fSwic3RhdGUiOiJhYmMxMjM0NSIsImN1cnNvcl9zb3J0IjoiMjAyNi0wOC0xMlQxMDowMDowMFoiLCJjdXJzb3JfaWQiOiIzZjllNmIxYy0zMzMzLTRkMmUtYjFhNC03YzhmOWUwYTFiMDMifQ==

The next page can be empty. Continue until the response returns next_cursor as null.

Recommendations

  • Check that next_cursor is not null before making another request.
  • Treat cursors as opaque. Do not parse, modify, or construct them.
  • Do not combine cursor with other query parameters.

Backward compatibility

The Qargo API follows these backward compatibility principles:

  • New fields may be added to response payloads at any time. Adding new fields is not considered a breaking change.
  • Integrators should ignore unknown fields when parsing responses. Do not fail on unexpected properties.
  • Deprecated fields and endpoints are marked as deprecated in this specification. They continue to work but may be removed in a future version. Migrate to the recommended replacement as soon as possible.
  • Existing fields will not be renamed or removed without prior notice and a deprecation period.

Date and time formats

All date and time fields in the API follow ISO 8601:

TypeFormatExampleDescription
DateYYYY-MM-DD2024-12-31Calendar date without time component
DatetimeYYYY-MM-DDTHH:mm:ssZ2024-12-31T14:30:00ZTimestamp in UTC (indicated by Z suffix)
TimeHH:mm09:30Time of day in 24-hour format
  • Datetime fields are always in UTC. Convert to local time on the client side.
  • Date fields have no timezone. They represent a calendar date (e.g. a planned delivery date).
  • Time fields are used for time windows (e.g. delivery windows) and are in 24-hour format without seconds.

Concepts

Company

A company in Qargo can be both a customer as well as a subcontractor (supplier). The entity will have a single id within Qargo. The api client can link companies by this id, or by the accounting code, which is a user defined code field.

Order

Transport order to execute. Also called job in other TMS systems. It contains all transport details:

  • Order references
  • Customer company
  • Consigments, with their stop locations, time windows, references
  • Definition of the goods to transport

Stop

  • A stop is a part of a transport, at a certain date, optional timeslot and location. In addition to the planned times, it also tracks the actual times for a completed stop. Stops can be linked to orders, or can be defined standalone (for example a cleaning stop). All stops are linked to a Trip.

Stop group

Stops can be grouped together according to their activity and location. This is called a stop group.

Trip

A trip contains stops from various orders, or standalone stops. It tracks how a certain transport is planned, and who will execute that transport.

Task

A task is the primary workflow concept in Qargo. Users can define their own flow, using both built-in tasks as well a custom defined ones. For the current accounting use case, we only expose the post invoice/credit note task, that allows users to send invoices to an accounting system.

Resource

A resource in Qargo is a vehicle, driver, trailer or other entity that can be assigned to a trip.

Unavailability

An unavailability indicates that a specific resource is not available for use for a given time range. An unavailability has a reason to indicate why the resource is not available.

Status update

A status update reflects a status change in an entity.

Document

A document in Qargo can be identified by a unique id. It has a type and is linked to a certain entity (for example an order).

Changelog

Recent additions and changes to the API, newest first.

2026-09-04

Outgoing data

2026-08-19

API

  • Added: PaymentTermCode gains END_OF_MONTH_0_NET_20, for a payment term of end of this month plus 20 days.

Webhooks

2026-08-11

Outgoing data

  • Added: VisibilityOrderStatus in operational visibility payloads gains BLOCKED, for an order that is blocked or on hold. Treat the order status as an open set and ignore values you do not recognise rather than rejecting the event.

2026-08-05

Outgoing data

  • Added: ResourceType in operational visibility payloads gains HANDLING, for handling equipment such as a forklift assigned to a stop, and SUBCONTRACTOR, which the payload has been able to carry for some time but was undocumented. Treat the resource type as an open set and ignore values you do not recognise rather than rejecting the event.

2026-07-29

Outgoing data

  • Changed: location.name is no longer guaranteed in operational visibility payloads. A location without a name, such as an address-only one created automatically by an order import, previously blocked the entire visibility event from being sent; it is now sent with name omitted. Treat the field as optional and fall back to address and city when it is absent.

2026-07-23

API

  • Fixed: Updating a resource no longer returns a server error when note or external_id is omitted; the value is now stored as an empty string, matching create. Sending an explicit null for note, external_id, name, or locale is now rejected with a validation error (422) instead of failing with a server error on update, or being silently ignored on create.
    • Affects: Resource
    • Endpoints: POST /v1/resources/resource, PUT /v1/resources/resource/{resource_id}, PATCH /v1/resources/resource/{resource_id}

Outgoing data

2026-07-06

API

  • Changed: Validation error responses now return an errors array instead of the flat detail, field and path fields. Each item is a ValidationErrorDetail with message, field, path and detail; the array is always present and non-empty, so a single failure is a one-item array and integrators can handle one and many failures the same way.

2026-06-15

Outgoing data

  • Added: The location dispatch webhook now includes a per-consignment tracking_link.

2026-06-03

Outgoing data

2026-05-18

API

  • Added: The TaskType enum gains DISPATCH, returned by the available-tasks and task endpoints.

2026-03-23

Outgoing data

2026-03-11

Webhooks

2026-03-10

Outgoing data

2026-02-24

Webhooks

2026-01-09

Outgoing data

Download OpenAPI description
docs.json
docs.yaml
Languages
Servers
https://api.qargo.com