Condition leads by discipline

Needs API Pro, the Leads website plan or National. Other plans get 403 plan_required.

Goal: you are an ecologist, transport planner or drainage engineer, and want every newly decided application whose conditions need your discipline, with the agent to contact.

Approach

Call GET /api/v1/conditions with your discipline and since set to the newest created_at you saw last time.
Group the conditions by application_id: one application often has several conditions for the same discipline.
Fetch each application once for the address, the agent's contact details and the council's link.
Narrow further with q, for example discipline=transport&q=travel plan.

Code

# Daily, API Pro. Ecology conditions added since the last run.
import os, requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['PLANNING_SIGNAL_API_KEY']}"
since = load_last_run() or "2026-10-01"   # ISO date or timestamp you saved

params = {"discipline": "ecology", "since": since, "limit": 100}
leads = {}
while True:
    res = session.get("https://planningsignal.co.uk/api/v1/conditions", params=params, timeout=30)
    res.raise_for_status()
    body = res.json()
    for c in body["data"]:
        leads.setdefault(c["application_id"], []).append(c)
        since = max(since, c["created_at"])
    if not body["next_cursor"]:
        break
    params["cursor"] = body["next_cursor"]

for app_id, conditions in leads.items():
    if not app_id:
        continue  # notice not tied to an application record
    app = session.get(f"https://planningsignal.co.uk/api/v1/applications/{app_id}", timeout=30).json()["data"]
    print(app["reference"], app["authority"], app.get("agent_company"), len(conditions), "conditions")
save_last_run(since)

What it costs

One record per condition plus one per application you fetch, each once a month. Repeat runs over the same window are free within the month.

Disciplines

transport, ecology, arboriculture, drainage, contamination, heritage, acoustics, air-quality, energy, landscape, construction-management, highways, lighting, waste, fire-safety, structural, sustainability, land-stability, aviation, materials. Meanings are in the fields reference.

Agent details are business contacts but can identify people. Contacting them is your responsibility under UK GDPR and PECR, including not sending unsolicited marketing emails to individuals without consent (see the licence). No code? Conditions alerts email the same leads.

Questions? Contact us, or see the help centre.