{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-subcontractor/docs.json","sidebar":"sidebar-sidebar.yaml__subcontractor_docs"},"props":{"definitionId":"subcontractor/docs.json","dynamicMarkdocComponents":[],"baseSlug":"/subcontractor/docs","seo":{"title":"Qargo TMS Subcontractor/fleet API","llmstxt":{"hide":true}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"Qargo TMS Subcontractor/fleet API","description":"Subcontractor/fleet dispatch API documentation\n<div style=\"border-left: 4px solid #00E85B; background: #F4FBF7; padding: 14px 18px; border-radius: 6px; margin: 20px 0;\">\n  <strong>What's new</strong> — see the <a href=\"/subcontractor/docs/section/changelog\">Changelog</a> for recent additions and changes to the API.\n</div>\n\n# Authentication\n\nThe api requires oauth2 authentication with client id/secret. This should only be used for service to service communication.\n\n## Creating application credentials\n\nApplication client credentials can be created by users with the `Super admin` role in the Qargo application.\nUsers can create and remove application clients by navigating to Configuration -> Organisation Settings (API clients sections).\n\nApplications need to be linked to a valid integration id, identifying the Qargo approved integrator.\nPlease contact [us](mailto:integrations@qargo.com) if you don't have an id yet.\n\n## Obtaining an access token\n\nTo 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.\n\nThe [/auth/token endpoint](/subcontractor/docs/section/authentication/the-api-call-to-request-tokens) can be used to generate an access token (JWT):\n\nThis token will need to be refreshed after expiration (we provide the 'expires_in' in the token response to check validity).\n\n### Understanding Basic Authentication\n\nBasic 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:\n\n- **Format**: `Authorization: Basic <base64-encoded-credentials>`\n- **Credentials Encoding**: The client ID and secret are concatenated with a colon (e.g., `client_id:secret_id`) and then Base64-encoded.\n\n### The API Call to Request Tokens\n\nThe `/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`.\n\n#### Request Details\n\n- **Method**: POST\n- **URL**: `https://api.qargo.com/v1/auth/token`\n- **Headers**:\n  - `Content-Type: application/json`\n  - `Authorization: Basic <base64-encoded-client_id:secret_id>`\n- **Body**: Empty.\n- **Parameters**: None.\n\nExample using `curl`:\n\n```\ncurl -XPOST https://api.qargo.com/v1/auth/token -H 'Content-type: application/json' -u '<client_id:secret_id>'\n```\n\n## Webhook authentication\n\n> **Important:** Webhook endpoints use a **different authentication method** than regular API endpoints. Do not use OAuth tokens for webhooks.\n\nQargo webhooks, such as those for order import and status updates, use **Basic Authentication** instead of OAuth. See [Understanding Basic Authentication](#understanding-basic-authentication) for details on the Basic Auth scheme.\n\nWebhook credentials (client id and secret id) are **provisioned by Qargo** when your webhook integration is configured — contact [integrations@qargo.com](mailto:integrations@qargo.com) to obtain them. They are **separate from your API credentials** and must be used exclusively for webhook endpoints.\n\n### API vs Webhook authentication summary\n\n| | **API endpoints** | **Webhook endpoints** |\n|---|---|---|\n| **Auth method** | OAuth2 (Client Credentials) | Basic Authentication |\n| **Credentials** | API client_id + secret_id → Bearer JWT token | Webhook client_id + secret_id (directly in header) |\n| **Header format** | `Authorization: Bearer <jwt_token>` | `Authorization: Basic <base64(client_id:secret_id)>` |\n| **Where to find credentials** | Configuration → Organisation Settings → API clients | Provisioned by Qargo — contact [integrations@qargo.com](mailto:integrations@qargo.com) |\n| **Token refresh needed?** | Yes (JWT expires) | No (credentials sent with each request) |\n\n### Common mistake\n\nWebhook 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.\n\n### Example webhook request\n\n```\ncurl -XPOST https://api.qargo.com/v1/webhook/order-import \\\n  -H 'Content-Type: application/json' \\\n  -u '<webhook_client_id>:<webhook_secret_id>' \\\n  -d '{ ... }'\n```\n\n# Rate Limits\n\nTo maintain API stability and prevent abuse, we enforce rate limits on a per-tenant basis.\n\n### Limits\n\nThe 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.\n\n| **Category** | **Scope** | **Limit** |\n| --- | --- | --- |\n| Authentication | `/auth/token` | 5 requests per hour |\n| General API Usage | All endpoints *except* authentication and webhooks | 2 requests per second (sustained); up to 3 per second (bursts) |\n\n### Enforcement\n\nRate 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.\n\nExample response:\n```http\nHTTP/1.1 429 Too Many Requests\nContent-Type: application/json\nRetry-After: 58\n\n{\"error\":\"Rate limit exceeded\"}\n```\n\nApplications must handle this response correctly by respecting the `Retry-After` header and retrying after the specified delay, regardless of whether the request appeared to be within the estimated limits.\n\nFor any concerns about these limits, please contact us at [integrations@qargo.com](mailto:integrations@qargo.com).\n\n# API Best Practices\n\nThis section outlines recommended practices for efficiently working with the Qargo API.\n\n## Pagination\n\nSome list endpoints support pagination. This means the endpoint offers a `next_cursor` in the response payload and accepts a `cursor` as query parameter. If pagination is supported and their response contains a `next_cursor` property, then you can use the `cursor` as a query parameter in a subsequent request to fetch the next page of results. Using query parameters is mutually exclusive with using the cursor.\n\n<br/>\n\n### How Pagination Works\n\n1. **Initial Request**: Make a request to a paginated endpoint without any cursor parameter\n2. **Check Response**: If the response includes a `next_cursor` field, more data is available\n3. **Subsequent Requests**: Use the `next_cursor` value as the `cursor` parameter in your next request\n4. **Continue**: Repeat until no `next_cursor` is returned\n\n<br/>\n\n### Example Usage\n\n```http\nGET /api/v1/orders\n```\n\nResponse:\n```json\n{\n  \"data\": [...],\n  \"next_cursor\": \"eyJpZCI6MTIzfQ==\"\n}\n```\n\nNext request:\n```http\nGET /api/v1/orders?cursor=eyJpZCI6MTIzfQ==\n```\n</br>\n\n### Recommendations\n\n- Always check for the presence of `next_cursor` before making additional requests\n- Store cursor values temporarily; they may expire after a certain period\n- Avoid using other query parameters when using cursor-based pagination\n\n## Backward compatibility\n\nThe Qargo API follows these backward compatibility principles:\n\n- **New fields may be added** to response payloads at any time. Adding new fields is **not** considered a breaking change.\n- **Integrators should ignore unknown fields** when parsing responses. Do not fail on unexpected properties.\n- **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.\n- **Existing fields will not be renamed or removed** without prior notice and a deprecation period.\n\n## Date and time formats\n\nAll date and time fields in the API follow ISO 8601:\n\n| Type | Format | Example | Description |\n|------|--------|---------|-------------|\n| Date | `YYYY-MM-DD` | `2024-12-31` | Calendar date without time component |\n| Datetime | `YYYY-MM-DDTHH:mm:ssZ` | `2024-12-31T14:30:00Z` | Timestamp in UTC (indicated by `Z` suffix) |\n| Time | `HH:mm` | `09:30` | Time of day in 24-hour format |\n\n- **Datetime fields are always in UTC.** Convert to local time on the client side.\n- **Date fields have no timezone.** They represent a calendar date (e.g. a planned delivery date).\n- **Time fields** are used for time windows (e.g. delivery windows) and are in 24-hour format without seconds.\n\n# Concepts\n\n## Company\n\nA company in Qargo can be both a customer as well as a subcontractor (supplier).\nThe entity will have a single id within Qargo. The api client can link companies by this id,\nor by the accounting code, which is a user defined code field.\n\n## Order\n\nTransport order to execute. Also called job in other TMS systems. It contains all transport details:\n\n- Order references\n- Customer [company](/subcontractor/docs/section/concepts/company)\n- Consigments, with their [stop](/subcontractor/docs/section/concepts/stop) locations, time windows, references\n- Definition of the goods to transport\n\n## Stop\n\n- A stop is a part of a transport, at a certain date, optional timeslot and location.\n  In addition to the planned times, it also tracks the actual times for a completed stop.\n  Stops can be linked to [orders](/subcontractor/docs/section/concepts/order), or can be defined standalone (for example a cleaning stop).\n  All stops are linked to a Trip.\n\n### Stop group\n\nStops can be grouped together according to their activity and location. This is called a stop group.\n\n## Trip\n\nA trip contains [stops](/subcontractor/docs/section/concepts/stop) from various [orders](/subcontractor/docs/section/concepts/order), or standalone [stops](/subcontractor/docs/section/concepts/stop). It tracks how a certain\ntransport is planned, and who will execute that transport.\n\n## Task\n\nA task is the primary workflow concept in Qargo. Users can define their own flow,\nusing both built-in tasks as well a custom defined ones. For the current accounting use case,\nwe only expose the `post invoice/credit note` task, that allows users to send invoices to an accounting system.\n\n## Resource\n\nA resource in Qargo is a vehicle, driver, trailer or other entity that can be assigned to a [trip](/subcontractor/docs/section/concepts/trip).\n\n## Unavailability\n\nAn unavailability indicates that a specific [resource](/subcontractor/docs/section/concepts/resource) is not available for use for a given time range. An unavailability has a reason to indicate why the resource is not available.\n\n## Status update\n\nA status update reflects a status change in an entity.\n\n## Document\n\nA 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).\n\n# Changelog\n\nRecent additions and changes to the API, newest first.\n\n## 2026-07-23\n\n**API**\n\n- **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.\n  - _Affects:_ [Resource](/subcontractor/docs/api-resource)\n  - _Endpoints:_ `POST /v1/resources/resource`, `PUT /v1/resources/resource/{resource_id}`, `PATCH /v1/resources/resource/{resource_id}`\n\n## 2026-07-06\n\n**API**\n\n- **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.\n  - _Affects:_ [Accounting](/subcontractor/docs/api-accounting), [Authentication](/subcontractor/docs/api-authentication), [Company](/subcontractor/docs/api-company), [Document](/subcontractor/docs/api-document), [Order](/subcontractor/docs/api-order), [Resource](/subcontractor/docs/api-resource), [Task](/subcontractor/docs/api-task), [Trip](/subcontractor/docs/api-trip)\n\n## 2026-06-15\n\n**Outgoing data**\n\n- **Added:** The location dispatch webhook now includes a per-consignment `tracking_link`.\n  - _Affects:_ [Location booking](/subcontractor/docs/use-case-location-booking)\n\n## 2026-06-03\n\n**Outgoing data**\n\n- **Added:** Operational order visibility now includes goods information.\n  - _Affects:_ [Customer portal](/subcontractor/docs/use-case-customer-portal), [Order](/subcontractor/docs/use-case-order), [Visibility](/subcontractor/docs/use-case-visibility)\n\n## 2026-05-18\n\n**API**\n\n- **Added:** The `TaskType` enum gains `DISPATCH`, returned by the available-tasks and task endpoints.\n  - _Affects:_ [Accounting](/subcontractor/docs/api-accounting), [Task](/subcontractor/docs/api-task)\n\n## 2026-03-23\n\n**Outgoing data**\n\n- **Added:** Fleet and subcontractor dispatch payloads now include `custom_fields`.\n  - _Affects:_ [Fleet dispatch](/subcontractor/docs/use-case-fleet-dispatch), [Subcontractor dispatch](/subcontractor/docs/use-case-subcontractor-dispatch)\n\n## 2026-03-11\n\n**Webhooks**\n\n- **Added:** Fleet status-update webhooks accept stop-group ETA windows via `eta_start` and `eta_end`.\n  - _Affects:_ Fleet dispatch\n  - _Endpoints:_ [POST /v1/webhook/fleet-status-update](/subcontractor/docs/operation/fleet-status-update-webhook)\n\n## 2026-03-10\n\n**Outgoing data**\n\n- **Added:** Operational order visibility now includes stop ETA times (`eta_start_time`, `eta_end_time`).\n  - _Affects:_ [Customer portal](/subcontractor/docs/use-case-customer-portal), [Order](/subcontractor/docs/use-case-order), [Visibility](/subcontractor/docs/use-case-visibility)\n\n## 2026-02-24\n\n**Webhooks**\n\n- **Added:** Fleet status-update webhooks accept stop ETA windows via `eta_start` and `eta_end`.\n  - _Affects:_ Fleet dispatch, Subcontractor dispatch\n  - _Endpoints:_ [POST /v1/webhook/fleet-status-update](/subcontractor/docs/operation/fleet-status-update-webhook), [POST /v1/webhook/subco-status-update](/subcontractor/docs/operation/subcontractor-status-update-webhook)\n\n## 2026-01-09\n\n**Outgoing data**\n\n- **Added:** Operational order visibility now includes the customer `id`.\n  - _Affects:_ [Customer portal](/subcontractor/docs/use-case-customer-portal), [Order](/subcontractor/docs/use-case-order), [Visibility](/subcontractor/docs/use-case-visibility)"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"api-docs.qargo.com","port":4000,"ipAddress":"216.73.217.86"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/subcontractor/docs","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}