Scans and Status Events

Scans and status events describe physical scans of goods or events during the handling of the order.

Overview

Events happen during the delivery process, either through scans (for example: goods receipt scan at the warehouse) or events of the delivery (for example: confirmation of the planned delivery time via phone with the recipient).

When the information is received at parcelLab from the carrier scans, the process used ensures the best quality data is provided. The data is processed and communicated to your customers to keep them informed on the progress of their order. This involves matching the data against our internal triggers for emails, calculating transit times, and translating it to send the order updates via email to the customer and providing it on your Order Status page.

Structure of an Event

The structure of an event (this includes both scans and status events) is described in the following table.

Field	Value	Required?
Shipment	The shipment identifier (for example: barcode, order number or tracking number).	Required
Timestamp	The date and time of the event in format YYYY-MM-DD HH:mm:ss+-HH:mm.	Required
Location	The location of the event (for example: a depot or city).	Optional
StatusCode	The applicable status code.	Required
ReasonCode	The reason code for the Exception status code.	Required for Exception
Details	The details of the status, which is required for the Scheduled status code and optional for all others.	Required for Scheduled

Events can be transferred as .json and via SFTP or the parcelLab API. See our status model for the list of available status codes, exception reasons, delivery location codes, and next actions.

Status Model

Send Status Events

Details of how the webhook/{courier}/ endpoint can be used to update the status of an individual delivery are described below.

POST Send Status Events

You can update the status of a delivery using the webhook/{courier}/ endpoint (that is: this endpoint would be called on a specific status or scan event).

The details of the Send Status Events API are described in the following section.

API Details

POST https://webhooks-api.parcellab.com/webhook/{courier}/

Header

Name	Type	Description
content-type	string	'application/json' or 'application/xml'

Request Body

Name	Type	Description
Events	array	JSON or XML as described below

Responses

• 202 - accepted

• 400 - if data is ill formatted, the response will describe the issue with the payload (for example: Invalid events, every "Event" needs a key "Shipment")

• 401 - if no or an invalid token is provided

Status events can be transmitted as shown below in the .json example. The payload can alternatively be sent as a file via SFTP.

For further details on file transfers, see how you can send files to parcelLab.

events-info.json

{
    "shipment": "D000000000001",
    "event": {
        "timestamp": "02-02-2025 12:00:00.000",
        "location": "London",
        "status_code": "In Transit",
        "reason_code": "",
        "additional_details": "Weather"
    },
    "estimated_date_of_delivery": "02-02-2025 11:30:00"
}

Example Payload/File

In this example, the payloads/files in .json and show different events with different status codes with reason codes and optional details.

sample-event-message.json

{
  "tracking_number": "D000000000001",
  "events": [
    {
      "timestamp": "2025-01-01T00:00:00.000Z", // Timestamp in Zulu or with specified timezone
      "location": "New York, NY", // Location in clear text
      "status_code": "In Transit", // Any status code as per your status data model or as clear text
      "reason_code": "", // Optional reason code
      "additional_details": "" // Any further free text information that is not standardized
    },
    {
      "timestamp": "2025-01-02T00:00:00.000Z",
      "location": "New York, NY",
      "status_code": "Exception",
      "reason_code": "Misrouted in network",
      "additional_details": ""
    },
    {
      "timestamp": "2025-01-03T10:00:00.000Z",
      "location": "New York, NY",
      "status_code": "Out for delivery",
      "reason_code": "",
      "additional_details": ""
    },
    {
      "timestamp": "2025-01-03T10:00:00.000Z",
      "location": "New York, NY",
      "status_code": "Failed delivery attempt",
      "reason_code": "Customer not met",
      "additional_details": ""
    },
    {
      "timestamp": "2025-01-05T10:00:00.000Z",
      "location": "New York, NY",
      "status_code": "Delivered",
      "reason_code": "Signed by recipient",
      "additional_details": "Received by John Doe"
    }
  ],


  // POD as URL to image or PDF
  "proof_of_delivery": "https://example.com/pod/D000000000001.jpg",


  // POD as base64 encoded string
  "proof_of_delivery": "data:image/jpeg;base64,...base64encodedstring...",


  // EDD as date
  "estimated_date_of_delivery": "2025-01-05",


  // EDD as time window
  "estimated_date_of_delivery": {
    "start": "2025-01-05T09:00:00.000Z",
    "end": "2025-01-05T17:00:00.000Z"
  }
}