Tracking

Read the tracking of one shipment, look up several waybills at once or list recent tracking. You only see your own shipments and those of your network.

GET/tracking/{tracking_number}

Get tracking by waybill

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Tracking of a single waybill (LDV) number. Only shipments of the caller or of the caller's network are visible; anything else is 404 NOT_FOUND. Waybill numbers are guessable, so ownership is always checked.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    tracking_number
    Type
    string
    required
    Description

    Waybill (LDV) number.

  • Name
    include_parcel_history
    Type
    boolean
    Description

    For multi-parcel shipments return the full history of every parcel instead of its current state.

    Default: false.

Responses

  • 200Tracking of the shipment.Tracking
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/tracking/{tracking_number}
Loading...

Response 200

{
  "tracking_number": "EX0000000001",
  "status": {
    "code": "IN_TRANSIT",
    "description": "In transito"
  },
  "carrier": "SDA",
  "shipment_id": "1234567",
  "offer_code": "offer_example_0002",
  "client_reference": "REF-0001",
  "pickup_booking_code": "PK0000000002",
  "tracking_events": [
    {
      "id": 1,
      "timestamp": "2026-12-10T11:41:00+00:00",
      "carrier_status_code": "RIT",
      "description": "Collected",
      "note": "The shipment was collected from the sender",
      "location": "Example hub",
      "signature": null
    },
    {
      "id": 2,
      "timestamp": "2026-12-10T15:10:02+00:00",
      "carrier_status_code": "PPP",
      "description": "Departed",
      "note": "The shipment is in transit",
      "location": "Example hub",
      "signature": null
    }
  ],
  "carrier_tracking_url": "https://tracking.example.com/EX0000000001",
  "created_at": "2026-12-09T09:35:12+00:00",
  "last_update": "2026-12-10T15:10:02+00:00"
}
GET/tracking/lookup

Find tracking by waybill, reference or offer code

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Finds the tracking of one shipment by exactly one of tracking_number, client_reference or offer_code. Only shipments of the caller or of the caller's network are visible; anything else is 404 NOT_FOUND.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    tracking_number
    Type
    string
    Description

    Waybill (LDV) number.

  • Name
    client_reference
    Type
    string
    Description

    Your reference.

  • Name
    offer_code
    Type
    string
    Description

    Offer code.

  • Name
    include_parcel_history
    Type
    boolean
    Description

    For multi-parcel shipments return the full history of every parcel instead of its current state.

    Default: false.

Responses

  • 200Tracking of the shipment.Tracking
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/tracking/lookup
Loading...

Response 200

{
  "tracking_number": "EX0000000001",
  "status": {
    "code": "IN_TRANSIT",
    "description": "In transito"
  },
  "carrier": "SDA",
  "shipment_id": "1234567",
  "offer_code": "offer_example_0002",
  "client_reference": "REF-0001",
  "pickup_booking_code": "PK0000000002",
  "tracking_events": [
    {
      "id": 1,
      "timestamp": "2026-12-10T11:41:00+00:00",
      "carrier_status_code": "RIT",
      "description": "Collected",
      "note": "The shipment was collected from the sender",
      "location": "Example hub",
      "signature": null
    },
    {
      "id": 2,
      "timestamp": "2026-12-10T15:10:02+00:00",
      "carrier_status_code": "PPP",
      "description": "Departed",
      "note": "The shipment is in transit",
      "location": "Example hub",
      "signature": null
    }
  ],
  "carrier_tracking_url": "https://tracking.example.com/EX0000000001",
  "created_at": "2026-12-09T09:35:12+00:00",
  "last_update": "2026-12-10T15:10:02+00:00"
}
GET/tracking

Track several shipments

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Tracking of up to 50 waybills in one call. Only shipments of the caller or of the caller's network are visible: a waybill with no match, or that belongs to someone else, is returned with status NOT_FOUND and no events (the two cases are indistinguishable) instead of failing the call. Events are oldest first.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    tracking_numbers
    Type
    array of string
    required
    Description

    Waybill numbers, comma-separated, up to 50.

    items ≤ 50.

  • Name
    include_parcel_history
    Type
    boolean
    Description

    For multi-parcel shipments return the full history of every parcel instead of its current state.

    Default: false.

Responses

  • 200One item per waybill, in request order.TrackingList
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/tracking
Loading...

Response 200

{
  "data": [
    {
      "tracking_number": "EX0000000001",
      "status": {
        "code": "IN_TRANSIT",
        "description": "In transito"
      },
      "carrier": "SDA",
      "shipment_id": "1234567",
      "offer_code": "offer_example_0002",
      "client_reference": "REF-0001",
      "pickup_booking_code": "PK0000000002",
      "tracking_events": [
        {
          "id": 1,
          "timestamp": "2026-12-10T11:41:00+00:00",
          "carrier_status_code": "RIT",
          "description": "Collected",
          "note": "The shipment was collected from the sender",
          "location": "Example hub",
          "signature": null
        },
        {
          "id": 2,
          "timestamp": "2026-12-10T15:10:02+00:00",
          "carrier_status_code": "PPP",
          "description": "Departed",
          "note": "The shipment is in transit",
          "location": "Example hub",
          "signature": null
        }
      ],
      "carrier_tracking_url": "https://tracking.example.com/EX0000000001",
      "created_at": "2026-12-09T09:35:12+00:00",
      "last_update": "2026-12-10T15:10:02+00:00"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 50
  }
}
GET/shipments/{shipment_id}/tracking

Get tracking of a shipment

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Tracking of a shipment you know by id. Only your own or your network's shipments; anything else is 404 NOT_FOUND.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    shipment_id
    Type
    string
    required
    Description

    Shipment id.

  • Name
    include_parcel_history
    Type
    boolean
    Description

    For multi-parcel shipments return the full history of every parcel instead of its current state.

    Default: false.

Responses

  • 200Tracking of the shipment.Tracking
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/shipments/{shipment_id}/tracking
Loading...

Response 200

{
  "tracking_number": "EX0000000001",
  "status": {
    "code": "IN_TRANSIT",
    "description": "In transito"
  },
  "carrier": "SDA",
  "shipment_id": "1234567",
  "offer_code": "offer_example_0002",
  "client_reference": "REF-0001",
  "pickup_booking_code": "PK0000000002",
  "tracking_events": [
    {
      "id": 1,
      "timestamp": "2026-12-10T11:41:00+00:00",
      "carrier_status_code": "RIT",
      "description": "Collected",
      "note": "The shipment was collected from the sender",
      "location": "Example hub",
      "signature": null
    },
    {
      "id": 2,
      "timestamp": "2026-12-10T15:10:02+00:00",
      "carrier_status_code": "PPP",
      "description": "Departed",
      "note": "The shipment is in transit",
      "location": "Example hub",
      "signature": null
    }
  ],
  "carrier_tracking_url": "https://tracking.example.com/EX0000000001",
  "created_at": "2026-12-09T09:35:12+00:00",
  "last_update": "2026-12-10T15:10:02+00:00"
}

Models

Objects used by the requests and responses on this page.

ParceLabsVersion

CorrelationId

KeyLocale

Tracking

Only shipments of the caller or of the caller's network are visible.

  • Name
    tracking_number
    Type
    string
    required
    Italian alias: lettera_vettura
    Description

    Waybill (LDV) number.

  • Name
    status
    Type
    TrackingStatus
    required
    Italian alias: status
    Description

    Current status.

  • Name
    carrier
    Type
    string · nullable
    Italian alias: vettore
    Description

    Carrier family code.

  • Name
    shipment_id
    Type
    string · nullable
    Italian alias: id_ordine
    Description

    Shipment identifier, when known.

  • Name
    offer_code
    Type
    string · nullable
    Italian alias: codice_offerta
    Description

    Offer code.

  • Name
    client_reference
    Type
    string · nullable
    Italian alias: custom
    Description

    Your reference.

  • Name
    pickup_booking_code
    Type
    string · nullable
    Italian alias: codice_prenotazione
    Description

    Pickup booking code.

  • Name
    tracking_events
    Type
    array of TrackingEvent
    required
    Italian alias: dettagli
    Description

    Events, oldest first.

  • Name
    parcels
    Type
    array of TrackingParcel
    Italian alias: parcels
    Description

    Per-parcel status for multi-parcel shipments.

  • Name
    carrier_tracking_url
    Type
    string (uri) · nullable
    Italian alias: url_tracking
    Description

    Carrier public tracking page.

  • Name
    created_at
    Type
    string (date-time)
    Italian alias: creato_il
    Description

    When the shipment was created.

  • Name
    last_update
    Type
    string (date-time)
    Italian alias: ultimo_aggiornamento
    Description

    Last tracking update.

TrackingStatus

  • Name
    code
    Type
    string
    required
    Italian alias: codice
    Description

    Normalised status.

    Allowed values: PENDING, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, EXCEPTION, RETURNED, HELD, NOT_FOUND.

  • Name
    description
    Type
    string
    required
    Italian alias: descrizione
    Description

    Human-readable description.

TrackingEvent

  • Name
    id
    Type
    integer
    required
    Italian alias: id
    Description

    Progressive event id.

  • Name
    timestamp
    Type
    string (date-time)
    required
    Italian alias: data
    Description

    When it happened (carrier local time converted to UTC).

  • Name
    carrier_status_code
    Type
    string
    Italian alias: status
    Description

    Carrier event code (for example PPP, THE, 000). See the status-codes reference page.

  • Name
    description
    Type
    string
    required
    Italian alias: descrizione
    Description

    Event description.

  • Name
    note
    Type
    string · nullable
    Italian alias: note
    Description

    Carrier note.

  • Name
    location
    Type
    string · nullable
    Italian alias: filiale
    Description

    Branch or hub.

  • Name
    signature
    Type
    string · nullable
    Italian alias: firma
    Description

    Name of who signed for the delivery.

TrackingParcel

  • Name
    id
    Type
    string
    required
    Italian alias: id
    Description

    Parcel identifier (sticker).

  • Name
    status
    Type
    TrackingStatus
    required
    Italian alias: stato
    Description

    Current status of the parcel.

  • Name
    carrier_status_code
    Type
    string
    Italian alias: codice_stato_vettore
    Description

    Carrier code of the current state.

  • Name
    updated_at
    Type
    string (date-time)
    Italian alias: date
    Description

    Last update.

  • Name
    history
    Type
    array of object
    Italian alias: storico
    Description

    Complete history. Only with include_parcel_history=true.

Unauthorized

Forbidden

NotFound

Gone

TooManyRequests

ServerError

BadGateway

BadRequest

TrackingList

  • Name
    data
    Type
    array of Tracking
    required
    Description
  • Name
    meta
    Type
    PageMeta
    required
    Description

PageMeta

Pagination metadata.

  • Name
    total
    Type
    integer
    required
    Description

    Total number of items matching the filters.

  • Name
    page
    Type
    integer
    required
    Description

    Current page, starting at 1.

  • Name
    per_page
    Type
    integer
    required
    Description

    Items per page.

Was this page helpful?