Trackable API Flow

Authenticated trackable flow

Use this guide when a person finds a trackable, reaches the secret-access flow, signs in, and then wants to do the richer ownership or note-backed stop workflow without losing the simpler direct-report option.

Follow the sequence Main API docs Anonymous flow Error reference

When to use this flow

This is the best flow for people who want durable ownership, editable comments, note conversion, moderation power, or the ability to come back later and manage what they posted. The person may start from a secret code or QR token before login, but once they authenticate they do not need to keep resending the access code on every write.

Step 1: Resolve the found item

The short website entry route is always /trackable/{code}. API clients can also resolve the token directly.

POST https://www.locationnotes.com/api/trackables/lookup
Content-Type: application/json

{
  "code": "LN4C8R2Z"
}
{
  "found": true,
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "isPublicCodeMatch": false,
  "usesSecretAccess": true,
  "redirectUrl": "/en-US/trackables/active/f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
}

If usesSecretAccess is true, the browser now has an active secret-backed session for that trackable. That session is separate from sign-in and exists specifically so the user can keep moving through the trackable workflow first.

Step 2: Read the active-session landing payload

GET https://www.locationnotes.com/api/trackables/active/{trackableId}

This tells the client whether activation is still required, whether the item belongs to a group, and which activation contexts are available after sign-in.

Step 3: Sign in and activate when needed

If the item is still unactivated, log in and activate it to a personal owner or a team.

POST https://www.locationnotes.com/api/trackables/{trackableId}/activate
Authorization: Bearer <access token>
Content-Type: application/json

{
  "name": "",
  "description": "",
  "statusMessage": "",
  "useGroupDefaultTitle": true,
  "useGroupDefaultDescription": true,
  "useGroupDefaultStatusMessage": true,
  "teamId": null,
  "externalLinkUrl": "",
  "externalLinkDescription": "",
  "useGroupDefaultExternalLink": true,
  "initialJourneyStopLatitude": 47.6205,
  "initialJourneyStopLongitude": -122.3493
}

If the item came from a group, activation is also where the final item-level identity is confirmed. Clients can either send explicit name, description, and statusMessage values or leave them blank while using useGroupDefaultTitle, useGroupDefaultDescription, and useGroupDefaultStatusMessage to keep the group's current defaults on the activated item.

Clients can optionally include <code>initialJourneyStopLatitude</code> plus <code>initialJourneyStopLongitude</code> when activation should also create the first tracked location immediately.

Step 4: Choose between the simple and rich logging paths

Once authenticated, the client can still use the lightweight direct-report path or the richer note path. The two paths are complementary, not mutually exclusive.

Step 5A: Save a direct journey stop

POST https://www.locationnotes.com/api/trackables/{trackableId}/journey-stops
Authorization: Bearer <access token>
Content-Type: application/json

{
  "latitude": 41.8819,
  "longitude": -87.6278
}

The saved stop is an immutable logistics snapshot. If a linked note later moves, the journey keeps the original snapped coordinate so the route history does not silently change.

Step 5B: Create a note and attach the trackable

POST https://www.locationnotes.com/api/notes/mine
Authorization: Bearer <access token>
Content-Type: application/json

{
  "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
  "title": "North lobby handoff",
  "body": "Visible as a note and as a trackable stop.",
  "latitude": 41.8818,
  "longitude": -87.6231,
  "visibility": "Private"
}
POST https://www.locationnotes.com/api/public/notes/{noteId}/trackables
Authorization: Bearer <access token>
Content-Type: application/json

{
  "trackableSecretCodes": "LN4C8R2Z"
}

Attaching the trackable while saving the note also records a journey-stop snapshot at that moment. That note-backed stop is what protects the trackable path if the note's own map point changes later.

The note attachment also grants the note's required access scope to that trackable. The stop preserves place history, but note access is still enforced by the note's own visibility and scope rules.

Step 6: Comment as an authenticated user

POST https://www.locationnotes.com/api/trackables/{trackableId}/comments
Authorization: Bearer <access token>
Content-Type: application/json

{
  "body": "Picked up and moving again."
}

Signed-in trackable comments can be edited only by the signed-in comment author. Owners and current team admins can delete comments or journey stops, but they still cannot rewrite someone else's words.

Step 7: Read the complete route and comments

GET https://www.locationnotes.com/api/trackables/{trackableId}/journey
GET https://www.locationnotes.com/api/trackables/{trackableId}/comments

The journey payload is already ordered chronologically and preloaded for map rendering. If a stop came from a private note the viewer cannot open, the API can still expose the location point while omitting the protected note content.

Journey reads expose the saved stop plus currentNotesAtCoordinate. That collection is today's visible note read model for the same coordinate, not proof that the stop permanently owns one note.

Operational notes

Related references: What is a Trackable?, anonymous trackable flow, and trackable error reference.