Skip to content

Label reports

Pro

Access and manage your label report data through the API. These resources provide a full view of a label's lifecycle, from its configuration and measurement data to calculated alert status. Update key metadata to keep your logistics organized.

GET
/v2/labelReports

List label reports

Returns one page of label reports for the company your key belongs to. Results are ordered by created ascending unless order says otherwise. Pagination is page based, so ask for a page number and a page size. Every parameter is optional and every value is read from the query string as a string.

Query parameters

filterstring
One or more key[operator]value conditions, comma separated. Supported operators are eq, neq, gt, gte, lt, lte, like, ilike and includes. A nested key uses a dot, as in senseConfig.interval[lte]1500.
orderstring default created[asc]
A single key[asc] or key[desc]. Any direction other than asc sorts descending.
customFieldsstring
One or more customFieldId[operator]value conditions, comma separated, using the same operators as filter. Applied as a pre-filter on matching reports.
pageNumberstring default 1
Which page to return, counted from 1.
pageSizestring default 100
How many reports to return per page. The source sets no upper bound.
outputstring default normal
minimal returns a reduced column set with minimalSenseData. normal returns the full report, including calculatedSenseData and trimmedSenseData.

Calculated, trimmed and minimal sense data

A label report returns several shapes of sense data, which can be used for different purposes. A label report’s timeline can be trimmed in order to leave out irrelevant parts of the shipment. The calculatedSenseData object contains the full data report of the label, where trimmedSenseData is a recalculated subset of that data based on the trimmed timeline. minimalSenseData returns a minimized data report containing flattenedDatapoints which can be used to visualize a quick and rough overview of the violations during the shipment.

What you get back

The response holds two keys. data contains an array of label report documents. totalDocuments is how many reports match the request in total.

Request

curl --get "https://api.tapp.online/v2/labelReports" \
  --data-urlencode "pageSize=50" \
  --data-urlencode "output=minimal" \
  --data-urlencode "order=created[desc]" \
  --header "x-api-key: $TAPP_API_KEY"

const params = new URLSearchParams({
  pageSize: '50',
  output: 'minimal',
  order: 'created[desc]'
})

const response = await fetch(
  `https://api.tapp.online/v2/labelReports?${params}`,
  {
    headers: {
      'x-api-key': process.env.TAPP_API_KEY as string
    }
  }
)

const { data, totalDocuments } = await response.json()

import os

import requests

response = requests.get(
    'https://api.tapp.online/v2/labelReports',
    params={
        'pageSize': 50,
        'output': 'minimal',
        'order': 'created[desc]',
        'filter': 'status[eq]active'
    },
    headers={'x-api-key': os.environ['TAPP_API_KEY']}
)

response.raise_for_status()
print(response.json()['totalDocuments'])

<?php

$query = http_build_query([
    'pageSize' => 50,
    'output' => 'minimal',
    'order' => 'created[desc]',
]);

$context = stream_context_create([
    'http' => [
        'header' => 'x-api-key: ' . getenv('TAPP_API_KEY'),
    ],
]);

$body = file_get_contents(
    "https://api.tapp.online/v2/labelReports?$query",
    false,
    $context
);

$page = json_decode($body, true);

Response

{
  "data": [
    {
      "id": "b8c47a62-8a40-4b7b-88d3-214a1b453bac",
      "created": "2026-05-04T09:12:00.000Z",
      "updated": "2026-05-06T08:41:13.000Z",
      "company": {
        "id": "1c0f4d9a-2e64-4f31-8d70-5a9b3c7e1f42",
        "name": "Example Exporters",
        "shortCode": "EXEX"
      },
      "subCompany": null,
      "label": {
        "uid": "04A1B2C3D4E580",
        "sequenceCode": "EXEX-2605-014"
      },
      "mode": "airFreight",
      "type": "tempSense",
      "status": "completed",
      "labelReference": "AMS-BOG-4471",
      "senseConfig": {
        "limits": {
          "minTemperature": 2,
          "maxTemperature": 8
        },
        "interval": 900,
        "configTime": 1777020000,
        "startDelay": 0,
        "runningTime": 172800
      },
      "hasFlag": false,
      "isArchived": false,
      "numberOfTaps": 3,
      "minimalSenseData": {
        "flattenedDatapoints": [0, 0, 0, 1, 1, 0],
        "numberOfDatapointsAvailable": 192,
        "numberOfDatapointsRead": 192,
        "numberOfMeasurementsOccurred": 192,
        "numberOfViolations": {
          "temperature": 2,
          "humidity": 0,
          "all": 2
        }
      },
      "alert": {
        "level": 1,
        "timestamp": 1777107300
      }
    }
  ],
  "totalDocuments": 128
}
GET
/v2/labelReports/:id

Retrieve a label report

Returns a single label report and its data.

Path parameters

idstring
required
The report id. Ids are UUIDs in practice, though the route validates only that the value is a string.

Selected response fields

idstring
The report id.
createdstring
When the report was created, with updated for the last change. Both are ISO 8601 timestamps.
labelobject
uid, sequenceCode, type, name, firmwareVersionInfo and estimatedBatteryDaysLeft, which the API computes on this endpoint rather than storing it.
modestring
One of airFreight, roadTransport, seaFreight, railFreight, stationary or unknown.
typestring
One of tempSense, humiditySense, shockSense or freezeSense.
statusstring
Either active or completed.
senseConfigobject
The configuration copied onto the report when the label was started: limits, interval, configTime, startDelay and runningTime. It is a copy, not a reference, so editing the label later does not change it.
calculatedSenseDataobject
The measurement result, including datapoints, attainedValues, numberOfViolations, durationOfViolations, analysedValues, and the timing fields startTime, elapsedTime, elapsedTimeFromConfig, preciseElapsedTime and preciseElapsedTimeFromConfig.
alertobject
level and timestamp. Level is -1 for a report with no taps yet, 0 for none, 1 for moderate and 2 for critical.
accessarray
Which companies hold this report and in what role: owner, editor or viewer.

The report object carries more fields than are listed here, among them user, customFields, labelPreset, alertsConfig, numberOfTaps, dataIsIncomplete, trimmedSenseData and reportedSenseData.

Request

LABEL_REPORT_ID=b8c47a62-8a40-4b7b-88d3-214a1b453bac

curl "https://api.tapp.online/v2/labelReports/$LABEL_REPORT_ID" \
  --header "x-api-key: $TAPP_API_KEY"

const labelReportId = 'b8c47a62-8a40-4b7b-88d3-214a1b453bac'

const response = await fetch(
  `https://api.tapp.online/v2/labelReports/${labelReportId}`,
  {
    headers: {
      'x-api-key': process.env.TAPP_API_KEY as string
    }
  }
)

const labelReport = await response.json()

import os

import requests

labelReportId = 'b8c47a62-8a40-4b7b-88d3-214a1b453bac'

response = requests.get(
    f'https://api.tapp.online/v2/labelReports/{labelReportId}',
    headers={'x-api-key': os.environ['TAPP_API_KEY']}
)

response.raise_for_status()
labelReport = response.json()
print(labelReport['status'], labelReport['alert']['level'])

<?php

$labelReportId = 'b8c47a62-8a40-4b7b-88d3-214a1b453bac';

$context = stream_context_create([
    'http' => [
        'header' => 'x-api-key: ' . getenv('TAPP_API_KEY'),
    ],
]);

$body = file_get_contents(
    "https://api.tapp.online/v2/labelReports/$labelReportId",
    false,
    $context
);

$labelReport = json_decode($body, true);

Response

{
  "id": "b8c47a62-8a40-4b7b-88d3-214a1b453bac",
  "created": "2026-05-04T09:12:00.000Z",
  "updated": "2026-05-06T08:41:13.000Z",
  "company": {
    "id": "1c0f4d9a-2e64-4f31-8d70-5a9b3c7e1f42",
    "name": "Example Exporters",
    "shortCode": "EXEX"
  },
  "label": {
    "uid": "04A1B2C3D4E580",
    "sequenceCode": "EXEX-2605-014",
    "type": "tempSense",
    "name": "Pallet 14",
    "firmwareVersionInfo": {
      "firmwareVersion": "1.4.2",
      "firmwareApiVersion": "1.0.0"
    },
    "estimatedBatteryDaysLeft": 246
  },
  "mode": "airFreight",
  "type": "tempSense",
  "status": "completed",
  "labelReference": "AMS-BOG-4471",
  "senseConfig": {
    "limits": {
      "minTemperature": 2,
      "maxTemperature": 8
    },
    "interval": 900,
    "configTime": 1777020000,
    "startDelay": 0,
    "runningTime": 172800
  },
  "hasFlag": false,
  "isArchived": false,
  "numberOfTaps": 3,
  "dataIsIncomplete": false,
  "calculatedSenseData": {
    "datapoints": [
      {
        "timestamp": 1777020900,
        "temperature": 4.1
      },
      {
        "timestamp": 1777022700,
        "temperature": 9.2
      }
    ],
    "numberOfDatapointsAvailable": 192,
    "numberOfDatapointsRead": 192,
    "numberOfMeasurementsOccurred": 192,
    "attainedValues": {
      "minTemperature": 1.6,
      "maxTemperature": 9.2
    },
    "startTime": 1777020000,
    "elapsedTime": 172800,
    "elapsedTimeFromConfig": 172800,
    "preciseElapsedTime": 172801,
    "preciseElapsedTimeFromConfig": 172801,
    "preciseInterval": 900.4,
    "currentTime": 1777192801,
    "startDelay": 0,
    "numberOfViolations": {
      "temperature": 2,
      "humidity": 0,
      "all": 2
    },
    "durationOfViolations": {
      "temperature": 1800,
      "humidity": 0,
      "all": 1800
    },
    "analysedValues": {
      "temperature": {
        "average": 4.6,
        "degreeHour": 1.1,
        "meanKineticTemperature": 4.9
      }
    }
  },
  "alert": {
    "level": 1,
    "timestamp": 1777107300
  },
  "customFields": null,
  "access": [
    {
      "id": "7d2a1f68-9b03-4c55-a1e2-6f8d0b47c913",
      "companyId": "1c0f4d9a-2e64-4f31-8d70-5a9b3c7e1f42",
      "labelReportId": "b8c47a62-8a40-4b7b-88d3-214a1b453bac",
      "role": "owner"
    }
  ]
}
PATCH
/v2/labelReports/:id

Update a label report

Updates one report, identified by the id in the path. Send only the fields you want to change. The key needs the update permission on labelReports. The properties allowed to be updated are limited.

Path parameters

idstring
required
The report to update.

Body

limitsobject
The measurement thresholds the report’s alerts are calculated on: minTemperature, maxTemperature, minHumidity and maxHumidity. Changing them recalculates the alert state from the datapoints already read, so a report can change alert level without the label being tapped again. Only the owning company may change limits.
labelReferencestring
Your own reference for the run, such as a shipment or order number.
statusstring
Either active or completed.
hasFlagboolean
Whether the report is flagged. Held per company, so flagging a shared report does not flag it for the other companies that can see it.
isArchivedboolean
Whether the report is archived. Also held per company.
customFieldsarray
One entry per field to set, each with a customFieldId and a value. The value is a string, a number, an array of either, or null to clear it.

Report owner vs. shared reports

Depending on whether the reports belongs to your company or is shared with you, different properties are allowed to be updated. Properties such as hasFlag and isArchived are updated independently on a company basis.

Who may change what

Report owner
Every field above.
Shared report editor
Everything except limits, which answers 403 with Only the label report owner can update limits.
Shared report viewer
Only hasFlag and isArchived. Any other field answers 403.

Request

LABEL_REPORT_ID=b8c47a62-8a40-4b7b-88d3-214a1b453bac

curl --request PATCH "https://api.tapp.online/v2/labelReports/$LABEL_REPORT_ID" \
  --header "x-api-key: $TAPP_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "labelReference": "AMS-BOG-4471",
    "limits": {
      "minTemperature": 0,
      "maxTemperature": 25
    }
  }'

const labelReportId = 'b8c47a62-8a40-4b7b-88d3-214a1b453bac'

const response = await fetch(
  `https://api.tapp.online/v2/labelReports/${labelReportId}`,
  {
    method: 'PATCH',
    headers: {
      'x-api-key': process.env.TAPP_API_KEY as string,
      'content-type': 'application/json'
    },
    body: JSON.stringify({
      labelReference: 'AMS-BOG-4471',
      limits: {
        minTemperature: 0,
        maxTemperature: 25
      }
    })
  }
)

const labelReport = await response.json()

import os

import requests

labelReportId = 'b8c47a62-8a40-4b7b-88d3-214a1b453bac'

response = requests.patch(
    f'https://api.tapp.online/v2/labelReports/{labelReportId}',
    headers={'x-api-key': os.environ['TAPP_API_KEY']},
    json={
        'labelReference': 'AMS-BOG-4471',
        'limits': {'minTemperature': 0, 'maxTemperature': 25}
    }
)

response.raise_for_status()
labelReport = response.json()

<?php

$labelReportId = 'b8c47a62-8a40-4b7b-88d3-214a1b453bac';

$payload = json_encode([
    'labelReference' => 'AMS-BOG-4471',
    'limits' => [
        'minTemperature' => 0,
        'maxTemperature' => 25,
    ],
]);

$context = stream_context_create([
    'http' => [
        'method' => 'PATCH',
        'header' => "x-api-key: " . getenv('TAPP_API_KEY') . "\r\ncontent-type: application/json",
        'content' => $payload,
    ],
]);

$body = file_get_contents("https://api.tapp.online/v2/labelReports/$labelReportId", false, $context);

$labelReport = json_decode($body, true);

Response

{
  "id": "b8c47a62-8a40-4b7b-88d3-214a1b453bac",
  "created": "2026-05-04T09:12:00.000Z",
  "updated": "2026-05-06T09:03:52.000Z",
  "labelReference": "AMS-BOG-4471",
  "status": "completed",
  "hasFlag": false,
  "isArchived": false,
  "senseConfig": {
    "limits": {
      "minTemperature": 0,
      "maxTemperature": 25
    },
    "interval": 900,
    "configTime": 1777020000,
    "startDelay": 0,
    "runningTime": 172800
  },
  "alert": {
    "level": 0,
    "timestamp": 1777107300
  },
  "access": [
    {
      "id": "7d2a1f68-9b03-4c55-a1e2-6f8d0b47c913",
      "companyId": "1c0f4d9a-2e64-4f31-8d70-5a9b3c7e1f42",
      "labelReportId": "b8c47a62-8a40-4b7b-88d3-214a1b453bac",
      "role": "owner"
    }
  ]
}