Integration fundamentals

Tracking

Look up a parcel's tracking events, and turn them into clear statuses for your customers.

Overview

Every scan, status change, communication, and delivery attempt for a parcel is recorded as a discrete event. A tracking lookup returns a shipment, which contains one or more items (parcels), each carrying its own ordered list of events. Events are identified by a unique apiKey, so your integration can react to specific milestones without depending on free-text descriptions.

How to use this page

Start with Event structure to see how a response is built up. Use Recommended UI states to map events to customer-facing statuses, and the Event catalogue to look up a specific event code.

Request

Path parameter Description
identifier The shipmentId or trackingReference without the (401) / (00) prefix, or a returnCode.
locale The language of the event descriptions: EN (English), NO (Norwegian) or SE (Swedish).
onlyLastEvent true returns only the newest event. false returns the full history.

Example request

curl -X GET "https://api.pre.helthjem.no/parcels/v1/tracking/fetch/70724763243779244/EN/false" \
  -H "Authorization: Bearer your_token" \
  -H "Accept: application/json"

Response

The response can contain events for more than one parcel. This happens when the shipment has several items, or when a parcel changes delivery method and gets a new tracking reference linked to the original.

Build your integration to handle these cases:

  • Duplicate events can occur, but rarely (less than 0.001% of events). Remove duplicates by apiKey and eventTimeUtc.
  • New event codes and fields can be added at any time. Ignore codes and fields you don't recognise, instead of failing.
  • An unknown identifier returns 200 with an empty array, not an error.

Event structure

A lookup returns an array of shipments. Each shipment has one or more items (parcels) — most shipments have exactly one. Each item carries its own parcelStatus and an ordered array of events. Events are returned newest first; sort explicitly by eventTime if you need chronological order.

Envelope: shipment → item → event

[
  {
    "shipmentNumber": "70724763243779244",
    "shopName": "Test shop",
    "shopId": 16,
    "consigneeReference": null,
    "consignorReference": null,
    "properties": {},
    "items": [
      {
        "trackingNumber": "370724763243779252",
        "returnCode": null,
        "freightProductId": 1,
        "freightProductName": "helthjem",
        "parcelStatus": "WAITING_FOR_PACKAGE",
        "linkedParcelNumbers": [],
        "events": []
      }
    ]
  }
]

Event object shape

Each entry in events looks like this, newest first:

{
  "eventTime": "2026-08-11 03:04:50",
  "eventTimeUtc": "2026-08-11T01:04:50.000904Z",
  "lat": null,
  "lon": null,
  "locationContext": "OSLO",
  "locationContextId": null,
  "eventType": {
    "apiKey": "013",
    "description": "Parcel delivered",
    "i18nKey": "event.type.distr.shipment.delivered"
  },
  "additionalInfo": {
    "apiKey": "012",
    "description": "in the mailbox",
    "i18nKey": "event.type.ai.distr.shipment.delivered.mailbox"
  },
  "eventGroup": {
    "id": 4,
    "name": "event.type.group.status"
  },
  "comChannelType": null,
  "changeUserId": null,
  "changeUsername": "flow-bud",
  "regSystem": { "id": 2, "name": "eBudbok" },
  "message": null,
  "eventData": null
}

Event groups

ID GROUP DESCRIPTION
1 import Information on shipments received/imported
2 transportation Information on transportation
3 communication Information on communication
4 status Information on status updates
5 scanner Information on scanning of shipments
6 export Information for shipments transported by others
7 external Information from/relating to external systems
8 internal Information on internal processing
9 images Information on extra image data on booking

Recommended UI states

Most integrations don't need to show every event. Map each apiKey to one of the customer-facing states below, and show the state of the newest event that maps to a state. Skip informational events when you work out the current state.

  • Not complete
UI state Meaning apiKey
Booked The parcel is registered but has not been handed over to Helthjem yet.
In transit The parcel is moving through the network, or has been collected from the sender.
Ready for pickup The parcel is waiting at a service point or parcel locker.
Delivered The parcel has been delivered. For returns, 116 means the parcel has arrived back at its destination.
Delivery failed A delivery or pickup attempt failed, or the parcel needs attention. Check additionalInfo for the reason.
Returning The parcel is being returned to the sender.
Cancelled The booking or pickup has been cancelled.
Informational Does not change the state. Show it in a detailed history if you want, or ignore it.

Redirected parcels

When a parcel changes delivery method, the original parcel can receive 073 (cancelled) while a new, linked parcel continues the journey. Check linkedParcelNumbers and follow the newest parcel before showing Cancelled to the customer.

Event catalogue

Use this table to look up the meaning of each event code. See Recommended UI states for how to group them for your customers.

eventGroup apiKey DESCRIPTION TRIGGER ADDITIONAL INFO
import 001 Transport of parcel has been booked. A booking was created for the parcel. –
import 158 Distribution address updated. The delivery or pickup address was validated and standardised. –
transportation 002 Parcel received - getting ready to transport it in our network. Parcel scanned for the first time at a Helthjem terminal. –
transportation 003 The parcel is being loaded for transport to its next checkpoint. Parcel scanned at a terminal on its way to the next checkpoint. –
transportation 004 The parcel is in transit and should be delivered within a few days. PostNord reported that the parcel is in transit. –
transportation 006 Parcel has arrived at local service point and is ready for pick-up. Parcel registered as ready for pickup at the service point. –
transportation 062 The parcel has been loaded on truck for transport. Parcel loaded onto a truck. –
transportation 063 Parcel has been unloaded from truck. Parcel unloaded from a truck. –
transportation 104 Parcel is delivered to service point. Parcel delivered to the service point. –
transportation 148 Registration of shipment with external carrier failed. The booking could not be registered with PostNord. –
communication 152 Communication sent. An SMS or email notification was sent. –
communication 153 Communication failed. An SMS or email notification could not be delivered. –
communication 155 Pick-up deadline has been extended The pickup deadline at the service point was extended (freight product 55). –
status 013 Parcel delivered. Courier or service point confirmed the parcel as delivered. additionalInfo on home deliveries: 011 on the doormat 012 in the mailbox 013 in a mailbox with bag and hook No additionalInfo: service point delivery, or delivery registered manually
status 015 Your delivery can’t be completed as expected. We will notify the recipient with updated information regarding your delivery. Courier could not deliver the parcel to the home address, or the parcel is being redirected to a service point. additionalInfo on unsuccessful home deliveries: 001 can’t find delivery point 002 missing key 003 parcel damaged 004 incorrect recipient address 005 recipient confirmed away 014 unsuitable delivery point No additionalInfo: no reason given, or redirected to a service point
status 028 We will try to deliver your shipment again. The recipient updated their address details and a new delivery attempt is scheduled. –
status 029 We will try to pick up your shipment again. The sender set a new pickup date. –
status 030 We are having problems with the delivery, and are working to locate the parcel. The parcel was confirmed lost during delivery, by the courier or by customer service. additionalInfo on lost home deliveries: 006 lost during distribution 007 lost before distribution 028 stolen No additionalInfo: no known reason
status 031 Our carrier attempted to collect your shipment, but was unfortunately unable to do so. Customer service registered a failed pickup (freight product 4 or 26). additionalInfo on failed pickups: 015 parcel not placed outside / not found 016 parcel not marked with pickup code 017 parcel not safely packaged 018 too big / heavy 019 could not contact the customer 020 missing key No additionalInfo: no known reason
status 032 Parcel has been picked-up by our carrier. Courier collected the parcel, or its pickup code was registered at a terminal. –
status 034 Our carrier attempted to collect your shipment, but was unfortunately unable to locate the shipment. Courier could not find the parcel at the pickup address (freight product 4 or 26). additionalInfo on failed pickups: 015 parcel not placed outside / not found 016 parcel not marked with pickup code 017 parcel not safely packaged 018 too big / heavy 019 could not contact the customer 020 missing key No additionalInfo: no known reason
status 035 Parcel will be returned to web shop/sender. Parcel scanned at a terminal for return to the sender, either because it was recalled or as the final return scan. –
status 057 Unfortunately we were not able to deliver your parcel tonight Courier could not deliver the parcel on tonight’s route. additionalInfo on unsuccessful home deliveries: 001 can’t find delivery point 002 missing key 003 parcel damaged 014 unsuitable delivery point 024 courier does not have the parcel No additionalInfo: no reason given
status 060 Pick-up of parcel has been cancelled The planned pickup was cancelled. –
status 061 Parcel marked as wanted. this parcel should be return to store/sender. The parcel was recalled, so it will be returned to the sender instead of delivered. –
status 068 Shipment not delivered. Parcel registered as not delivered. –
status 069 Parcel not acknowledged. The delivery route was completed without the courier confirming this parcel. –
status 073 Order has been cancelled. The pickup was cancelled, or the parcel was redirected and the original booking cancelled. –
status 076 The customer has changed date for shipment. A new pickup date was set. –
status 077 The planned delivery or pick-up has been cancelled as the parcel has received a final status. The parcel was redirected or returned, so its planned delivery or pickup was cancelled. –
status 093 Parcel has been sorted incorrectly and will unfortunately be slightly delayed PostNord reported that the parcel was sorted incorrectly. –
status 095 Parcel not picked up at service point and will be returned to sender. Service point personnel registered that the parcel (freight product 55) was not collected before the deadline. The event appears on both the original parcel and the return parcel (freight product 58) that is created for it. –
status 100 The order has been changed. Some booking information was updated. –
status 112 Destination has been changed. Helthjem redirected the parcel to a new destination. –
status 113 Parcel activated. The parcel is scheduled for transport, delivery or pickup on a known date. B2C: parcel scanned and activated at a terminal. C2B/C2C: pickup date set. –
status 117 Parcel ready for pick-up sent to consignee. “Ready for pickup” notification sent to the recipient. –
status 118 Reminder parcel ready for pick-up sent to consignee. “Ready for pickup” reminder sent to the recipient. –
status 119 Pick-up period extended sent to consignee. “Pickup period extended” notification sent to the recipient. –
status 120 Reminder for parcel ready for pick-up after extended period sent to consignee. Reminder sent to the recipient after the pickup period was extended. –
status 121 Parcel returned sent to sender. “Parcel returned” notification sent to the sender. –
status 122 Parcel delivered for return at servicepoint. Service point personnel registered the return parcel when the customer handed it in. –
status 125 Parcel is no longer wanted. to be delivered as normal. The recall was cancelled, so the parcel will be delivered as normal. –
status 136 The shipment item has been cleared by customs. Customs clearance was reported by an external party. –
status 151 Shipment distribution date changed. A new pickup date was set. –
status 154 Fallback shipment solution was triggered. The booking used a fallback delivery method. –
scanner 016 Parcel has been scanned. Parcel scanned at a terminal for outbound delivery. –
scanner 017 No edi-information received for this parcel. Parcel scanned at a terminal, but no booking data was found for it. –
scanner 018 Parcel scanned at wrong station. please change station and scan again. Parcel scanned at a terminal station that does not handle its destination. –
scanner 019 Can not find alias for this parcel, verify correct transport setup or split load carrier. Parcel scanned at a terminal, but no valid destination was found for it at that station. –
scanner 022 Parcel is in transit. The parcel (freight product 55) arrived at a different service point than planned. –
scanner 024 Parcel scanned in return mode. Return parcel scanned, or its code entered, at a terminal. –
scanner 107 Load carrier has been received and is being loaded for transport. The container or roll cage holding the parcel was scanned for transport. –
scanner 115 Parcel has return status, it can not be scanned in outgoing mode. A return parcel was scanned as an outbound parcel at a terminal. –
scanner 116 Parcel has arrived at end station. Return parcel scanned at its final destination terminal. –
scanner 149 The parcel has been added to the customs report. Return parcel scanned at a terminal that records it for customs reporting. –
scanner 150 Routing information retrieved for the parcel. The terminal sorting system looked up the parcel’s routing information. –
export 026 Parcel will be delivered by a partner carrier. A home-delivery parcel was redirected to a service point at the terminal, or the parcel was booked with a partner carrier (freight product 62 or 89). –
export 147 Code for return is received/updated. A return code was received from the partner carrier (freight product 89). –
external 036 Unknown status notification from external transporter. A partner carrier sent a status update that has no matching Helthjem event. –
internal 094 Label has been generated. A shipping label was generated for the parcel. –
images 124 Additional information for delivery available. Extra delivery details were added, such as a photo of the delivered parcel. –

See also

  • Identifiers: which identifier to use, and how to remove the prefix.
  • Rate limits: how often to poll for tracking updates.
Last updated
Previous
Generate a label
Next
B2C Integration