Developer API
Developer APICore ConceptsTags

Tags

Understanding tag identity, labels, and status values

Tag Object

A tag is the logical customer-facing record in your workspace. It has a stable Tag ID, editable display metadata, a read-only original physical label when known, and a current Beacon ID that links it to the underlying hardware.

Every tag is uniquely identified by its id (e.g., aB3xK9Qm1Zr7). Its hardwareId is the assigned Beacon ID. Both are opaque and read-only. The editable name and labels are never identity or ownership keys.

Tag Schema

{
  "id": "aB3xK9Qm1Zr7p",
  "name": "Van 1",
  "originalPhysicalLabel": "01",
  "labels": ["Coca-Cola", "Seattle", "AED-0042"],
  "status": "linked",
  "isActive": true,
  "hardwareId": "A17C09E2-6B4D-4F38-9A50-000000000001",
  "battery": {
    "level": null,
    "status": 1,
    "updatedAt": "2024-06-19T13:45:23Z"
  },
  "lastLocation": {
    "lat": 40.7128,
    "lng": -74.0060,
    "timestamp": "2024-06-19T13:45:23Z",
    "timestampMs": 1718809523000
  },
  "lastSeenAt": "2024-06-19T13:45:23Z",
  "recordingPaused": false
}

Fields

id

Stable TagLogger identifier for the logical tag record. Use it to fetch or update the tag. It is independent from the Beacon ID and is not user-editable.

name

Editable display name (e.g., "Van 1" or "Package"). Null if not set.

originalPhysicalLabel

Read-only text recorded when TagLogger originally shipped or provisioned the tag, such as "01" or "4QHTZ-S21". It remains stable when the display name or a later sticker changes and is never used for ownership, access, or hardware binding. It may be null for older tags when TagLogger cannot infer the original label safely.

labels

Optional workspace-defined words or identifiers, such as a customer, site, or customer-system asset number. Labels are display and lookup aids only. They never link hardware, determine ownership, assign access, or add a tag to a shared page.

status

Tag lifecycle state. Newly confirmed records use "linked". "pending_hardware" can appear on legacy records created before confirmed provisioning was introduced.

isActive

Boolean. True if the tag is active and counting toward your workspace seats. False if deactivated or pending.

hardwareId

The opaque Beacon ID supplied by the location infrastructure for the physical hardware currently assigned to this logical tag. It is not generated by the customer, is not user-editable, and is not necessarily printed on the hardware.

battery

level is reserved and currently always null. status is the battery status: 0 unknown, 1 good, 2 medium, 3 low (an early warning, plan a swap), 4 critical (replace soon). updatedAt is when the battery state was last observed (ISO 8601, may be null).

lastLocation

Current location summary with lat, lng, timestamp (ISO 8601), and timestampMs (epoch milliseconds). Null if never reported or recording is paused. For full detail (accuracy, altitude, etc.), use the location and history endpoints.

lastSeenAt

ISO 8601 timestamp of the most recent location report. Null if the tag has never reported.

recordingPaused

Boolean. True if location recording is paused. Coordinates are suppressed when paused.

Status Values

pending_hardware

Legacy audit state for records created before hardware was assigned. These records do not count as active hardware. New purchases are represented by order fulfillment state instead and do not create placeholder tag records.

linked

The AirTag is paired and reporting location. This is the normal state for an operational tag. To tell whether a linked tag is reporting recently, compare lastSeenAt against the current time.

Identity and provisioning

Purchases do not create API tag objects ahead of the hardware. The provisioning inbox groups incoming Beacon IDs by proposed workspace so a TagLogger operator can review the account and fulfillment order once, verify every upstream onboarding name and original shipped label, and confirm the batch with one action. Logical tag records are created only for the confirmed hardware.

After confirmation, workspace ownership and the Beacon ID relationship are authoritative. The upstream onboarding name is retained as internal provisioning and validation evidence; it is not returned as a customer identity field and later observations cannot remap the tag.

Active vs. Inactive

The isActive field indicates whether the tag is consuming a "seat" in your workspace:

  • Active (isActive: true): The tag uses one of your workspace's paid seats and records locations. Your bill follows the number of seats on your plan, not how many tags are active.
  • Inactive (isActive: false): The tag is archived or deactivated and doesn't count toward your limit. You can reactivate it later.

Recording Pause

When recordingPaused is true, the tag's location collection is temporarily suspended and lastLocation is null. Pausing stops new points from being recorded. Existing history is still returned; the trail simply stops growing while paused.

This is useful for privacy (e.g., pausing tracking while an asset is at a sensitive location). Recording can be paused indefinitely or until a chosen time from the TagLogger app or with PATCH /v1/tags/{tagId} using a key with manage:tags. Existing history is retained, and pausing recording also pauses alerts for the same period.

Retrieving Tags

List all tags in your workspace:

GET /v1/tags?label=Coca-Cola&search=AED-0042 HTTP/1.1
Host: api.taglogger.com
Authorization: Bearer tl_live_xxx

The label filter is a case-insensitive exact match. Use search for a substring search across the tag id, display name, original physical label, hardware id, and labels; terms shorter than 4 characters match only the display name, original physical label, and labels. Server-side filters support up to 1,000 tags visible to the API key; for larger fleets, narrow the key's tag scope or page the unfiltered list and filter locally. Send name and/or labels with PATCH /v1/tags/{tagId}. The tag id, originalPhysicalLabel, and hardwareId remain read-only, and metadata updates never relink the tag.

Get a single tag:

GET /v1/tags/{tagId} HTTP/1.1
Host: api.taglogger.com
Authorization: Bearer tl_live_xxx

See Also