Track decisions on a list of applications

Goal: you follow a list of applications (your clients', or ones near your sites) and want to know when each is decided.

1. Store the id, not just the reference

The API looks applications up by id (pa_...). There is no filter by council reference, so find each application once with a search, for example by authority and since or by postcode, pick the one whose reference matches, and store its id. References are only unique within a council, so match on authority too.

2a. Check each one (small lists)

Call GET /api/v1/applications/:id for each tracked application once a day and compare app_state. Each application costs one record a month, however many times you check it.

// Daily: has anything on my list been decided?
const KEY = process.env.PLANNING_SIGNAL_API_KEY;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

for (const tracked of await db.trackedApplications()) { // rows with the pa_ id you stored
  const res = await fetch(`https://planningsignal.co.uk/api/v1/applications/${tracked.id}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  const body = await res.json();
  if (!res.ok) { console.warn(tracked.id, body.code); continue; }
  const app = body.data;
  if (app.app_state !== tracked.app_state) {
    await db.saveState(tracked.id, app.app_state, app.decided_date, app.decision);
    console.log(`${app.reference}: ${tracked.app_state} -> ${app.app_state}`);
  }
  await sleep(1100); // stay under 60 requests a minute
}

2b. Scan the council's decisions (long lists)

With hundreds of applications in a few councils, ask each council for everything decided since your last run with decided_since, and match the ids against your list. You pay only for applications that were decided, not for every one you follow.

curl "https://planningsignal.co.uk/api/v1/applications?authority=Camden&decided_since=2026-10-01&limit=100" \
  -H "Authorization: Bearer ps_live_your_key_here"

Prefer email? The website's watch feature tells you about every change to an application without any code: see Watch an application.