LocationNotes API documentation

Base URL

All examples on this page assume the current production host:

https://www.locationnotes.com

Format

Requests and responses use JSON. GUIDs are the primary identifiers across notes, categories, teams, and devices.

Authorization

Private, sync, and team endpoints require an `Authorization: Bearer <access token>` header unless the route is marked public below.

Language

Public and management reads can pass `contentLanguage=en-US` or another supported content language to filter the returned note/category content.

{
  "deviceId": "5dd06ca7-34a5-4f2e-812d-3f1ef3e48290",
  "notes": [
    {
      "noteId": "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb",
      "ownerUserId": "a7cfd28f-c17f-4cf7-8913-47fa10fd0d1f",
      "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
      "title": "Offline inspection",
      "body": "Saved while disconnected.",
      "contentLanguage": "en-US",
      "latitude": null,
      "longitude": null,
      "visibility": "Private",
      "externalLinkUrl": "https://example.com/offline-inspection",
      "externalLinkDescription": "",
      "applyExternalLinkChanges": true,
      "isDeleted": false,
      "updatedUtc": "2026-03-13T20:12:00Z",
      "clientMutationId": "android-offline-42",
      "teamId": null
    }
  ],
  "categories": []
}

{
  "appliedNoteIds": [
    "ef90c4ca-88a9-4a9b-b3a8-36e2649c5dcb"
  ],
  "appliedCategoryIds": [],
  "conflicts": []
}

{
  "lastSyncUtc": "2026-03-13T19:45:00Z",
  "publicArea": {
    "minLatitude": 41.78,
    "minLongitude": -87.75,
    "maxLatitude": 41.96,
    "maxLongitude": -87.54
  }
}

{
  "serverSyncUtc": "2026-03-13T20:13:02Z",
  "userNotes": [],
  "userCategories": [],
  "teamCategories": [],
  "publicNotes": [],
  "teamNotes": []
}

Read personal notes

Optional query string: contentLanguage and full map bounds with minLatitude, minLongitude, maxLatitude, maxLongitude.

Create a note

{
  "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
  "title": "Category-only feedback",
  "body": "This note stays off the map on purpose.",
  "contentLanguage": "en-US",
  "externalLinkUrl": "https://example.com/field-guide",
  "externalLinkDescription": "",
  "latitude": null,
  "longitude": null,
  "visibility": "Public",
  "commentPolicy": "LoggedInUsers"
}

Note page reads and actions

{
  "body": "I found it too."
}

{
  "trackableSecretCodes": "LN4C8R2Z",
  "selectedActiveTrackableIds": [
    "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
  ],
  "activeTrackableAttachMode": "Self"
}

These note-page routes respect private-note access. If the caller can open the note page, the API can return comments and visible trackables for that note. Attaching trackables requires the note owner or a team admin.

Read categories

Create or move categories

{
  "name": "Field Reports",
  "contentLanguage": "en-US",
  "parentCategoryId": null
}

Common reads

• GET /api/teams
• GET /api/teams/{teamId}/notes
• GET /api/teams/{teamId}/categories
• GET /api/teams/{teamId}/categories/tree
• GET /api/teams/{teamId}/invite-links

Create a team

{
  "name": "beta-testers",
  "title": "Beta Testers",
  "description": "Public beta release gate for Android validation.",
  "externalLinkUrl": "https://example.com/beta-program",
  "externalLinkDescription": "",
  "joinPolicy": "RequestsAllowed",
  "pageVisibility": "Public",
  "defaultNoteVisibility": "Public",
  "contentLanguage": "en-US"
}

Create a team note

{
  "categoryId": "68cb4c9b-d9bd-4bde-8c6a-a03a4c70b283",
  "title": "Shared dock inspection",
  "body": "Visible to the team until we publish it.",
  "contentLanguage": "en-US",
  "externalLinkUrl": "https://example.com/shared-briefing",
  "externalLinkDescription": "",
  "latitude": 41.8818,
  "longitude": -87.6231,
  "visibility": "Private",
  "commentPolicy": "TeamMembers"
}

Membership and invite operations

• POST /api/teams/{teamId}/memberships/request
• POST /api/teams/{teamId}/memberships/invite
• POST /api/teams/{teamId}/memberships/{membershipId}/accept
• POST /api/teams/{teamId}/memberships/{membershipId}/refuse
• POST /api/teams/{teamId}/memberships/{membershipId}/approve
• POST /api/teams/{teamId}/memberships/{membershipId}/deny
• POST /api/teams/{teamId}/memberships/{membershipId}/promote-admin
• DELETE /api/teams/{teamId}/memberships/{membershipId}
• POST /api/teams/invite-links/{teamSlug}/{inviteCode}/join

Identifier formats and examples

Generated public-code tokens and generated short-secret bodies use the same smudge-resistant character family. Typed lookup treats O like 0, I or L like 1, S like 5, and U like V. For system short-secret codes, that normalization applies to the generated body after the literal prefix. Public codes use that same configured prefix with a dash before the generated body, so they are visually distinct from short secret codes.

List and detail reads

• GET /api/trackables/public
• GET /api/trackables/mine
• GET /api/trackables/{trackableId}
• GET /api/trackables/profile/{userName}/{publicCode}
• GET /api/trackables/team/{teamSlug}/{publicCode}
• GET /api/trackables/{trackableId}/journey

Create one trackable

{
  "name": "Promo coin",
  "description": "Launch event inventory item",
  "externalLinkUrl": "https://example.com/promo-coin",
  "externalLinkDescription": "",
  "teamId": null,
  "isPublic": true,
  "activateImmediately": false,
  "secretCode": ""
}

{
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "heading": "Unactivated Trackable",
  "description": "Please activate this trackable item",
  "items": [
    {
      "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
      "name": "Unactivated Trackable",
      "publicCode": "LN-7K4V9T",
      "secretCode": "LN4C8R2Z",
      "scanUrl": "https://locationnotes.com/trackable/ABCD...<100 characters total>...",
      "qrPayload": "https://locationnotes.com/trackable/ABCD...<100 characters total>..."
    }
  ]
}

Bring your own secret code

{
  "name": "Marketing token",
  "description": "Bring-your-own identifier",
  "teamId": null,
  "isPublic": false,
  "activateImmediately": true,
  "secretCode": "TAG42"
}

The server accepts caller-supplied secret codes that do not start with LN or GT and do not match any existing secret or public code. The returned public code is still system-generated.

Create a group

{
  "name": "Gnomes in this hunt",
  "description": "Seasonal hunt inventory",
  "defaultTrackableTitle": "",
  "defaultTrackableDescription": "",
  "defaultExternalLinkUrl": "https://example.com/hunt-rules",
  "defaultExternalLinkDescription": "",
  "trackableCount": 12,
  "teamId": null,
  "isPublic": true,
  "activateImmediately": false
}

Groups are limited to 100 trackables. Unactivated items fall back to the group defaults until activation. Once activated, they must use their own title and description.

Lookup and active session

• POST /api/trackables/lookup matches a public code token or short secret code after normalizing the common smudged-character substitutions listed above.
• GET /trackable/{code} is the short website entry route. It accepts a public code, a short secret code, or the long QR token and then routes to the correct flow.
• GET /api/trackables/active lists the client's currently active secret-code sessions.
• GET /api/trackables/active/{trackableId} returns the active landing payload, including activation requirements and grouped items when available.
• POST /api/trackables/active/{trackableId}/message updates the remembered status text.
• DELETE /api/trackables/active/{trackableId} ends the remembered secret-code session on that client.

Secret-code lookups and private scan-QR visits create an active client session instead of returning the secret value. That active session is what lets later note flows attach the trackable without re-entering the code.

A bare public-code lookup is safe because short public codes are globally unique. The website intentionally uses the same direct entry base route for all three forms: /trackable/{publicCode}, /trackable/{secretCode}, and /trackable/{qrToken}.

That shared entry route stays valid even if the configured short-code lengths change later, because the server resolves the code value instead of depending on hard-coded website path variations.

Owner-scoped profile and team public pages remain resolved destinations after lookup, but the shareable website entry URL still starts at /trackable/{code}.

That distinction also applies on note pages: a public code is for opening the public trackable page, while note attachment expects an existing short secret code or an already-active browser session.

GET /api/trackables/lookup?code=LN4C8R2Z

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

GET /trackable/LN-7K4V9T

GET /api/trackables/profile/alex/LN-7K4V9T

GET /api/trackables/team/beta-testers/LN-7K4V9T

GET /trackable/ABCD...<100 characters total>...

Activate to self or team

{
  "name": "Bramble the Mossy Wanderer",
  "description": "A small green gnome ready for the next stop.",
  "externalLinkUrl": "",
  "externalLinkDescription": "",
  "useGroupDefaultExternalLink": true,
  "teamId": "optional-team-guid"
}

If teamId is supplied, the trackable becomes team-owned, team admins can manage it, and the activating member keeps control while they remain on that team. Without teamId, the trackable becomes personally owned.

For group-created unactivated items, activation is also the step where the new owner must choose the final item-specific title and description.

Detach and reattach groups

• DELETE /api/trackables/{trackableId}/group removes the current group association.
• POST /api/trackables/{trackableId}/group with { "trackableGroupId": "..." } associates a detached trackable with a new group.

A trackable can only belong to one group at a time. The server enforces the detach-first rule. Only the original activator can reattach a detached trackable, and the destination group must also be controlled by that user or an eligible team admin.

{
  "trackableGroupId": "4bdffcab-bb51-4fd8-8c15-59f7b2d72c3f"
}

Trackable comments

• GET /api/trackables/{trackableId}/comments
• POST /api/trackables/{trackableId}/comments

Clients must be logged in to post comments. Unactivated trackables cannot be commented on.

{
  "body": "Starting the route now."
}

Visibility and journey disclosure

Trackable journey pages may show mapped locations even when some underlying notes are private. In those cases, unauthorized viewers can receive the location point but not the protected note content.

Authorized viewers receive the note title, description, and note link directly from the preloaded journey payload and map pin popups.

Deletion and retention

Deleting one account does not automatically delete every trackable that account ever touched. Shared or team-owned trackables can remain while only the deleted user's removable personal activity is removed.

Review the Delete Data page and the account-delete API section for the current retention boundaries.

Verify a link

Call this before showing the description field in a custom client. A successful response returns a normalized URL, the suggested description from the page title, and a support URL for review issues. Failed responses return HTTP 400 with a detail message, a support URL, and an upstreamStatusCode when the destination site itself returned an HTTP error.

{
  "url": "https://example.com/hunt-rules"
}

{
  "normalizedUrl": "https://example.com/hunt-rules",
  "suggestedDescription": "Example Domain",
  "supportUrl": "/uk-UA/support"
}

{
  "title": "Request rejected.",
  "status": 400,
  "detail": "The external page returned HTTP 405 Method Not Allowed during verification.",
  "supportUrl": "/uk-UA/support",
  "upstreamStatusCode": 405
}

Note, team, and sync fields

Create and update note, team, and sync payloads use externalLinkUrl plus externalLinkDescription. When ApplyExternalLinkChanges is true on sync note payloads, the server revalidates the link before saving.

• CreateNoteRequest.ExternalLinkUrl
• CreateNoteRequest.ExternalLinkDescription
• CreateTeamRequest.ExternalLinkUrl
• CreateTeamRequest.ExternalLinkDescription
• UpdateTeamSettingsRequest.ExternalLinkUrl
• UpdateTeamSettingsRequest.ExternalLinkDescription
• NoteDto.ExternalLinkUrl
• NoteDto.ExternalLinkDescription
• NoteDto.ApplyExternalLinkChanges

Trackable and group fields

Trackable creation and activation payloads use externalLinkUrl plus externalLinkDescription. Trackable-group creation uses defaultExternalLinkUrl plus defaultExternalLinkDescription, and activation accepts useGroupDefaultExternalLink when the owner intentionally wants to keep the group default.

• TrackableCreateInputModel.ExternalLinkUrl
• TrackableCreateInputModel.ExternalLinkDescription
• TrackableGroupCreateInputModel.DefaultExternalLinkUrl
• TrackableGroupCreateInputModel.DefaultExternalLinkDescription
• TrackableActivationInputModel.ExternalLinkUrl
• TrackableActivationInputModel.ExternalLinkDescription
• TrackableActivationInputModel.UseGroupDefaultExternalLink

Server behavior

• Clients should treat externalLinkDescription as unavailable until verification succeeds.
• If the client leaves the description blank, the server uses the verified page title or "no title found on external page".
• Rejected destinations can fail because the URL format is invalid, the host is local or private, the page could not be reached, the page did not return success, or adult-content signals were found.
• Public pages render saved external links through a LocationNotes exit page instead of sending the visitor straight to the third-party destination.

Use this for health checks, Android compatibility gating, and the current beta-page URL.

Returns staged Android beta metadata, including display version, version code, minimum compatible version, and release notes.