Qargo

Qargo Use case / Trip import API

Required api role: `API_TRIP` Purpose: This interface allows an external system (e.g. a route optimisation tool) to send fully planned trips into Qargo. When a trip payload arrives, Qargo creates or updates a trip with the specified stops, sequence, timestamps, and resource assignments — without manual planning. The trip import is the last step of a larger planning flow: 1. The external system obtains the Qargo `id`s of the stops and resources to plan. Qargo can push this planning data to the external system (an optional export, configured per integration), or the external system fetches it via the API (e.g. orders and resources). 2. The external system computes trips and assigns each one a `trip_identifier`. 3. The external system pushes the planned trips to the trip import webhook. ![trip import flow](/docs/static/trip_import_flow.svg) ### Getting started A trip import pushes stop sequences, resource assignments, and timing information into Qargo so that the planning board reflects the externally computed plan. The `trip_identifier` is used to determine whether an incoming trip is new or an update to an existing one: - **Create** — a new trip is created when a payload arrives with a `trip_identifier` that has not been seen before. - **Update** — if a payload arrives with a `trip_identifier` that already exists, Qargo updates the original trip rather than creating a new one. - **Cancel** — setting `status = 'CANCELLED'` will remove the trip. A trip must have been created before it can be cancelled. ### Limitations - Stops must be referenced by their Qargo stop `id`. Location names, using location details or aliases are not supported. - Each stop must have a `sequence` value (starting from `0`) and a start/end timestamp. Missing either will cause the import to fail. - Resources can only be assigned by their Qargo resource `id` — not by license plate, name, or external reference. - All stops in the payload must be unplanned. Stops that are already assigned to another trip cannot be imported. - Trips are created automatically — there is no approval or review step before the trip appears on the planning board (unlike order import). - A cancelled trip cannot receive further updates. To re-import, use a new `trip_identifier`. - Stop timestamps must be logically consistent: the sequence order must match the chronological order, and a delivery stop cannot precede its corresponding pickup. - Trip import is asynchronous — the endpoint does not return trip data. - Splitting a trip into multiple trips is not supported via trip import - split the order first. - Each integration instance supports either webhook or EDI routing — not both simultaneously.

Documentation GitHub OpenAPI

Operations 1

POST /v1/webhook/trip-import Import Trip #

Documentation

📖

APIReference

https://api-docs.qargo.com/docs

Specifications

⚙

OpenAPI

https://raw.githubusercontent.com/api-evangelist/qargo/refs/heads/main/openapi/qargo-use-case-trip-import-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/qargo-use-case-trip-import-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Qargo TMS Use case / Trip import API
  description: For support, please contact integrations@qargo.com.
  version: 1.2.0
servers:
- url: https://api.qargo.com
tags:
- name: Use case / Trip import
  description: 'Required api role: `API_TRIP`


    Purpose: This interface allows an external system (e.g.'
paths:
  /v1/webhook/trip-import:
    post:
      tags:
      - Use case / Trip import
      summary: Import Trip
      description: 'Webhook for planning a list of stops on a trip and assigning resources.


        The documented schema is our default input format, but we can also map custom formats,

        keeping in mind the limitations that are documented under use cases.


        Note that this webhook uses Basic Auth instead of the OAuth credentials used for the api.

        Please contact integrations@qargo.com to request credentials.'
      operationId: trip-import-webhook
      security:
      - BasicAuthWebhookCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TripImportInput'
              - type: string
                format: binary
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/TripImportResponse'
                - type: 'null'
                title: Response Trip-Import-Webhook
        '400':
          description: Bad Request — invalid input or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized — missing or invalid authentication credentials
        '403':
          description: Forbidden — insufficient permissions for this operation
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests — rate limit exceeded. See the `Retry-After` header
        '500':
          description: Internal Server Error
        '503':
          description: Service Unavailable — temporarily unable to handle the request
components:
  schemas:
    FixedTimestampType:
      type: string
      enum:
      - ENFORCED_TIMEWINDOW
      - SET_BY_USER
      - CALCULATED
      title: FixedTimestampType
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationErrorDetail:
      properties:
        message:
          description: Human-readable summary of this validation failure
          title: Message
          type: string
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Name of the field that failed validation, if known
          title: Field
        path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: JSON path to the field within the request payload (e.g. '$.consignor.address.country')
          title: Path
        detail:
          anyOf:
          - type: string
          - type: object
          - type: 'null'
          default: null
          description: Additional structured context about the failure, if provided by the backend
          title: Detail
      required:
      - message
      title: ValidationErrorDetail
      type: object
    TripImportLocation:
      properties:
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
          description: ID of the location in Qargo
      type: object
      title: TripImportLocation
    ErrorStatus:
      properties:
        error_type:
          $ref: '#/components/schemas/ErrorType'
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
          description: (User visible) error message
      type: object
      required:
      - error_type
      title: ErrorStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TripImportResponse:
      properties:
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ErrorStatus'
            type: array
          - type: 'null'
          title: Errors
          description: List of errors that occurred during the webhook processing. If empty/omitted, the webhook was processed successfully.
          examples:
          - error_message: The payload is invalid.
            error_type: USER_INPUT_ERROR
          - error_message: Not supported.
            error_type: NOT_SUPPORTED
          - error_message: Unknown error.
            error_type: INTERNAL_ERROR
      type: object
      title: TripImportResponse
    TripImportStop:
      properties:
        sequence:
          type: integer
          title: Sequence
          description: Sequence number determining the order of stops
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
          description: ID of the stop in Qargo
        location:
          anyOf:
          - $ref: '#/components/schemas/TripImportLocation'
          - type: 'null'
          description: Location of the stop
        custom_fields:
          anyOf:
          - type: object
          - type: 'null'
          title: Custom Fields
          description: Custom fields for the stop
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
          description: Start timestamp of the stop in UTC
        end_timestamp:
          type: string
          format: date-time
          title: End Timestamp
          description: End timestamp of the stop in UTC
        fixed_timestamp_type:
          anyOf:
          - $ref: '#/components/schemas/FixedTimestampType'
          - type: 'null'
          description: Type of fixed timestamp constraint on the stop
        question_answers:
          anyOf:
          - type: object
          - type: 'null'
          title: Question Answers
          description: Question answers, format to be defined between Qargo and external party
      type: object
      required:
      - sequence
      - start_timestamp
      - end_timestamp
      title: TripImportStop
    TripImportStatus:
      type: string
      enum:
      - CANCELLED
      title: TripImportStatus
    ErrorType:
      type: string
      enum:
      - USER_INPUT_ERROR
      - INTERNAL_ERROR
      - NOT_SUPPORTED
      title: ErrorType
    TripImportUnassignedStop:
      properties:
        stop_id:
          type: string
          format: uuid
          title: Stop Id
          description: ID of the stop that couldn't be assigned
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Reason for not being able to assign the stop
      type: object
      required:
      - stop_id
      title: TripImportUnassignedStop
    TripImportResource:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: ID of the resource in Qargo
      type: object
      required:
      - id
      title: TripImportResource
    ValidationErrorResponse:
      properties:
        message:
          description: Human-readable summary of the validation failure
          title: Message
          type: string
        errors:
          description: One entry per validation failure. Always present and non-empty — a single failure yields a one-item array, so integrators can handle one and many the same way.
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          minItems: 1
          title: Errors
          type: array
      required:
      - message
      - errors
      title: ValidationErrorResponse
      type: object
    TripImportInput:
      properties:
        trip_identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Trip Identifier
          description: External identifier for the trip
        status:
          anyOf:
          - $ref: '#/components/schemas/TripImportStatus'
          - type: 'null'
          description: Status of the trip import
        planned_stops:
          items:
            $ref: '#/components/schemas/TripImportStop'
          type: array
          title: Planned Stops
          description: List of planned stops in the trip
        start_timestamp:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Start Timestamp
          description: Start timestamp of the trip in UTC
        primary_resources:
          anyOf:
          - items:
              $ref: '#/components/schemas/TripImportResource'
            type: array
          - type: 'null'
          title: Primary Resources
          description: List of primary resources assigned to the trip
        unassigned_stops:
          anyOf:
          - items:
              $ref: '#/components/schemas/TripImportUnassignedStop'
            type: array
          - type: 'null'
          title: Unassigned Stops
          description: List of stops that couldn't be assigned to any resource
        failure:
          anyOf:
          - $ref: '#/components/schemas/ErrorStatus'
          - type: 'null'
          description: Error details if the trip import failed upstream
      type: object
      required:
      - planned_stops
      title: TripImportInput
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /v1/auth/token
    BasicAuthWebhookCredentials:
      type: http
      scheme: basic
x-tagGroups:
- name: Use cases
  tags:
  - Use case / Accounting
  - Use case / Customer portal
  - Use case / Document import
  - Use case / E-invoicing
  - Use case / Fleet dispatch
  - Use case / Intermodal [partner]
  - Use case / Location booking
  - Use case / Master data sync
  - Use case / Order
  - Use case / Subcontractor dispatch
  - Use case / Tracking
  - Use case / Trip import
  - Use case / Visibility
- name: API
  tags:
  - API / Accounting
  - API / Authentication
  - API / Company
  - API / Document
  - API / Order
  - API / Resource
  - API / Task
  - API / Trip
- name: System
  tags:
  - System
- name: Webhooks
  tags:
  - Webhooks / Inbound
  - Webhooks / Outbound
- name: ''
  tags: []