Track: Carrier Integration Guide

Overview link

Sorted provides simplistic integration methods to enable Sorted’s partner carriers to submit their delivery events directly to our package tracking platform.

This enables carriers to provide structured and timely package tracking data to Sorted so that tracking events can be accurately recorded, providing retailers with real-time visibility and consistent package tracking across their delivery network.

This guide explains the integration methods and the data specifications of how a partner carrier should submit their package tracking data to us for processing.

To begin, please view the following:

• The prerequisites required to start the integration
• The data specification of what can be submitted to us; and
• The integration method you want to use to send your package tracking data

Prerequisites link

Before an integration can begin, partner carriers and Sorted must provide the following:

Carriers link

Carrier must provide us:

• Event codes
  Provide a complete list of your tracking event codes and descriptions. These will be mapped to Sorted’s standard tracking states to ensure consistent behaviour across the platform.

• Company logo
  A high-quality version of your logo, preferably SVG or PNG format with a transparent background.

• Tracking URL
  A URL link to your website. This allows notifications to include an embedded link. Sorted will append the parcel number to this URL to create a direct link for customers.

Sorted link

Sorted will provide:

• Unique integration key
  A unique identifier that must be included in webhook submissions or used within the SFTP file naming convention. This ensures tracking data is correctly attributed and processed.

Data specification link

The following data specification is required for both Webhook and SFTP integration methods. Sample code and downloadable templates are available in each respective integration section below.

Tracking event fields link

Date Format Requirements link

All date/time fields must use ISO 8601 format including timezone offset.

Event sequencing link

For accurate tracking and correct behaviour, it is important to submit tracking events in the correct chronological sequence.

Sorted will always use the timestamp provided within the csv or json payload to determine the event order in the tracking timeline.

If events are provided out of sequence, Sorted may not trigger the expected state-change events and therefore associated triggers for webhooks or customer notifications may not be sent.

Final states link

Certain tracking states in our platform are considered final states. Once a shipment reaches a final state (e.g delivered), it cannot transition back to a previous operational state such as in_transit. Events attempting to move a shipment out of a final state will not trigger state changes. To view our mapped final states, please view the final state column of this table.

Integration methods link

1. Webhooks (Preferred) - See integration details below
2. SFTP (Batch File Transfer) - See integration details below

Webhook integration (preferred) link

Partner carriers can POST their tracking events in JSON format to a Sorted endpoint using an integration key provided by Sorted to authenticate.

Webhook endpoint:

    https://react.sorted.com/inbound/trackingevent/{UniqueIntegrationKey}
  

Example JSON Payload link

Please refer to the data specification section for full details of the required fields and data types.

  [
  {
    "code": "in_transit",
    "expected_delivery_date": "2025-01-28T17:00:00+00:00",
    "description": "At national hub",
    "timestamp": "2025-01-27T20:00:00+00:00",
    "reference": "TR-10012345678",
    "location": "West Midlands"
  },
  {
    "code": "out_for_delivery",
    "expected_delivery_date": "2025-01-28T17:00:00+00:00",
    "description": "On delivery vehicle",
    "timestamp": "2025-01-28T07:21:22+00:00",
    "reference": "TR-10012345678",
    "location": "Littleham depot",
    "delivery_slot": {
      "start": "2025-01-28T16:00:00+00:00",
      "end": "2025-01-28T18:00:00+00:00"
    }
  },
  {
    "code": "delivered",
    "description": "Delivery to customer",
    "timestamp": "2025-01-28T16:30:00+00:00",
    "reference": "TR-10012345678",
    "location": "Customer address",
    "signee": "J Smith",
    "lat_long": {
      "lat": 52.671397,
      "long": -2.098684
    }
  }
]
  

SFTP integration (bulk method) link

Sorted partner carriers can alternatively submit tracking files via SFTP, with CSV and JSON file formats collected at regular intervals every 5–10 minutes.

The partner carrier is responsible for hosting the SFTP server and creating an account that Sorted can use to connect to. If required, Sorted can provide a set of static IP addresses to support IP whitelisting for inbound connections.

Example CSV format link

Please refer to the data specification section for full details of the required fields and data types.

Download CSV template Download JSON example

Protocol, security and file management link

Our preference is to delete files immediately following successful download. If deletion is not possible (for example, due to a shared directory), we can support leaving files in place, in which case the partner carrier is responsible for clearing down old files.

The agreed approach must be clearly defined as either files being deleted immediately after download, or files never being deleted by Sorted and remaining under carrier management.

Testing & Go-Live link

Prior to production go-live, partner carriers must:

• Complete integration testing
• Validate event mapping
• Submit sample tracking data; and
• Receive confirmation from Sorted that integration requirements have been met

Production access will only be enabled following a successful testing.