Track lists

Some markets are easier to describe by name than one address at a time. Our lead detective C. T. Lucky keeps a list per industry, and each one names the companies we already have on file. You can read a list without an account, and put the whole thing on your books in one move.

Read a list

GET /v1/track-lists/{slug}

Public. No token, no account, nothing to sign. The slug is the industry's name in lowercase with hyphens — the same one the industry page uses.

curl "https://api.competitortracker.io/v1/track-lists/leave-management-software"

{
  "slug": "leave-management-software",
  "name": "Leave management software",
  "generatedAt": "2026-08-09T00:35:23.468Z",
  "isStale": false,
  "items": [
    {
      "id": "019e9422-7784-7026-90cb-2f30dfe0b4f4",
      "slug": "absence",
      "name": "Absence",
      "url": "https://absence.io",
      "changesTotal": 21,
      "lastRead": "2026-08-08T02:02:21.042Z",
      "affiliated": false,
      "alreadyTracked": null
    }
  ],
  "balance": null
}

changesTotal is how many changes we hold for that company and lastRead is when we last looked at them. A company we have never read carries a zero and a null — it starts from the day you add it, so its first report comes with the next round rather than immediately.

generatedAt dates the tracking rather than the request. isStale turns true when a list has not been refreshed inside its usual window. Neither is an error: the companies on a stale list are still the right companies.

An industry with nothing published yet returns an empty items array and a 200. That is an answer, not a fault.

Sign in for more

Send a bearer token on the same request and two extra facts come back.

alreadyTracked turns from null into a straight yes or no per company. The null is deliberate — without a token we are not saying you don't track a company, we are saying we were not asked.

balance stops being null and carries your coins, how many companies you are paying for and how many of this list you already have:

{
  "balance": {
    "coins": 25,
    "paidCompetitorCount": 0,
    "alreadyTrackedCount": 3,
    "grantEligible": true
  }
}

That is enough to price the list before you commit to it: one coin per company per month, so a list of twenty-three costs twenty-three a month.

grantEligible answers whether this organization can still claim the allowance below. Read it rather than working it out from the other numbers: the rule looks at whether you have ever tracked a company, not at what you are paying for today, so an organization that stopped tracking everything is still not eligible.

Companies we are affiliated with

affiliated is true when a company on the list is one of ours. You can track it exactly like any other and we watch it the same way — we would just rather say so than let you find out later. The flag rides on anonymous reads too, because a disclosure that waits for you to sign in is not much of a disclosure.

Read one company

GET /v1/track-companies/{slug}

Public like the list above, and deliberately the same answer: one company comes back as a list with a single entry in items. Anything you wrote to read a list reads this without a change.

curl "https://api.competitortracker.io/v1/track-companies/vacation-tracker"

The slug is the company's name in lowercase with hyphens — the same one its company page uses. slug and name at the top level are the company's own rather than an industry's. Every field on the entry means what it means above, affiliated included, and a bearer token adds the same two facts.

The allowance below does not apply here. It is an offer about a whole industry and it is claimed against an industry's name.

Claim the allowance

POST /v1/track-lists/{slug}/grant

A new organization opens with twenty-five coins, which does not stretch to a large industry. So the first list you take on is covered: we top your balance up to the size of the list, once.

curl -X POST "https://api.competitortracker.io/v1/track-lists/leave-management-software/grant" \
  -H "Authorization: Bearer $TOKEN"

{
  "eligible": true,
  "reason": "granted",
  "coinsGranted": 23,
  "balanceAfter": 25,
  "listLength": 23,
  "capped": false,
  "alreadyClaimed": false
}

The rules, in full:

• Once per organization, ever. Not once per list. Claiming a second list returns alreadyClaimed and grants nothing.
• Only if you have never tracked a company. The allowance is for a standing start, and the question is about your history rather than your current roster — an organization that tracked companies and later stopped is not eligible.
• The amount comes from the list. Nothing in your request can influence it. Ask for a list of twenty-three and the arithmetic uses twenty-three.
• There is a ceiling. A list past it is topped up to the ceiling and capped comes back true, so you can say so rather than quietly fall short.

Calling it again is safe. A repeat returns the original outcome instead of granting more, so a retry after a dropped connection costs nothing.

reason tells you which of those applied: granted, already_funded when your balance already covered the list, already_claimed, already_tracking, or grant_disabled.

Claim before you subscribe. The coin check runs on every subscription, so a list that outruns your balance will stop partway through rather than at the start.

Put the list on file

Each item carries id — that is the company itself, and you can subscribe with it directly:

curl -X POST "https://api.competitortracker.io/v1/competitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "competitorId": "019e9422-7784-7026-90cb-2f30dfe0b4f4" }'

Sending the id rather than the address is the better move for anything that came off a list. We already know the company, so there is no address to normalize, no domain to check and no redirect to trip over. Send url instead when you are adding something of your own. One or the other, never both.

Subscribe one company per request. A company you already track answers 409, so a partial list can be finished by resending it without sorting out which ones landed.