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