API Examples

Request & Response Payloads

You need to request the PreETA information for each job.

Example request payload:

{
created:"2025-03-30T14:03:08.190+02:00",
parcelNumber: "00JI2G26",   (optional, if parcel data was sent to DGW before)
dateOfEstimatedDelivery:"2025-03-31",
address:{
street:"Oranienstr. 183",
postalCode:"10999",
locality:"Berlin",
province:null,
country:"DE",		 (either full address information or geo coordinates)
geoCoordinate:{              (either geo coordinates or full address information )
    type:"ROOFTOP",
    latitude:52.5002814,
    longitude:13.4211109 (minimum 4 decimal places)
  }
}

Example response payload (sync & async):

{
notificationType: "preETA",
created: "2025-03-30T14:03:20.190Z",
parcelNumber: ”00JI2G26”, (optional, if shipment already created)
dateOfEstimatedDelivery: "2025-03-31",
preETATimeFrameMin: "2025-03-31T14:15:00Z”,
preETATimeFrameMax: "2025-03-31T16:15:00Z”
}

All time values in PreETA responses are returned in ISO 8601 format using the UTC (Coordinated Universal Time) timezone, indicated by the trailing Z (e.g., 2025-03-31T14: 15:00Z). This ensures consistent time representation across systems and geographies. Clients consuming PreETA should convert the UTC time to their local timezone (e.g., CET or CEST) if local display or logic is required.

For Example:

UTC:    2025-03-31T14:15:00Z
Berlin: 2025-03-31T16:15:00+02:00 (if daylight saving time applies)

The predicted delivery time windows returned by PreETA are accurate to a 15-minute granularity. This means: The earliest and latest times of the window are aligned to the closest: 00, 15, 30, or 45 minute mark.

A window like 14:15 – 16:15 means that Bettermile predicts the delivery will most likely occur within that time frame, with the prediction rounded to the nearest quarter-hour.

This design ensures a consistent, interpretable format for downstream systems (e.g., checkout UIs, notifications, or customer service tools), simplifying time comparisons and formatting.

Note: The internal prediction model may operate on finer-grained data, but the returned result is locked to a 15-minute resolution for reliability and usability.

API Authentication & Security

All API requests require an API key for authentication. You can get the API key via Bettermiles Backoffice API Key Management, or please reach out to your Bettermile representative.

Please find additional information in our developer portal

Ensure secure transmission via HTTPS for all connections (also on tenant-provided webhook endpoints) and valid certificates. Do not expose API keys in frontend code.