API Documentation

Authentication

All API requests require an API key passed via the X-API-Key header.

curl https://api.plannexus.io/v1/applications \
 -H"X-API-Key: pn_live_your_key_here" \
 -G -d"q=extension" -d"postcode=SW1"

Rate Limiting

Rate limits are communicated via response headers:

Endpoints

Official SDKs

Thin, typed clients around the REST API. Both honour Retry-After on 429 automatically and ship TypeScript/Python types for every response shape.

from plannexus import PlanNexus

with PlanNexus(api_key="pn_live_...") as client:
 result = client.applications.search(
 q="extension", postcode="SW1", per_page=10
 )
 for app in result["data"]:
 print(app["reference"], app["address"])

import { PlanNexus } from "plannexus";

const client = new PlanNexus({ apiKey: "pn_live_..." });

const result = await client.applications.search({
 q: "extension",
 postcode: "SW1",
 per_page: 10,
});
for (const app of result.data) {
 console.log(app.reference, app.address);
}

Raw HTTP examples

import httpx

client = httpx.Client(
 base_url="https://api.plannexus.io/v1",
 headers={"X-API-Key": "pn_live_your_key"}
)

# Search for extensions in SW1
resp = client.get("/applications", params={
"q": "extension",
"postcode": "SW1",
"per_page": 10
})
data = resp.json()

for app in data["data"]:
 print(f"{app['reference']} - {app['address']}")
 print(f" Status: {app['status']}")
 print(f" Received: {app['date_received']}")

const response = await fetch(
"https://api.plannexus.io/v1/applications? " +
 new URLSearchParams({ q: "extension", postcode: "SW1" }),
 {
 headers: {"X-API-Key": "pn_live_your_key" },
 }
);

const { data, meta } = await response.json();
console.log(`Found ${meta.total} applications`);

data.forEach((app) => {
 console.log(`${app.reference} - ${app.address}`);
});

Response envelope & pagination

List endpoints (applications, authorities, subscriptions) return a wrapped envelope:

{
"data": [ /* array of records */ ],
"meta": {
"total": 4218,
"page": 1,
"per_page": 25,
"pages": 169
 }
}

Single-record endpoints return the bare object. Pagination is page-based with page and per_page query params — `per_page` caps at 100.

Error codes

Webhooks

Create a subscription via POST /v1/subscriptions (or the Webhooks page in your dashboard). PlanNexus POSTs a JSON payload to your endpoint whenever a matching application triggers a subscribed event.

Event types

• new_application — a council published a new application
• status_change — an existing application's status moved (e.g. validated → under-consultation)
• decision_made — an application was decided (approved/refused/withdrawn)

Payload format

{
"event": "new_application",
"timestamp": "2026-04-23T09:15:42.108Z",
"data": {
"application_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
"reference": "23/04521/FUL",
"authority_id": "018e1c50-...",
"address": "14 Bishopsgate, London EC2N 4AW",
"postcode": "EC2N 4AW",
"description": "Erection of a single-storey rear extension.",
"status": "validated",
"decision": null,
"application_type": "householder",
"date_received": "2026-04-23" }
}

Headers

• Content-Type : application/json
• X-PlanNexus-Signature : sha256=<hex-digest> — HMAC-SHA256 over the raw body, keyed by your webhook secret
• X-PlanNexus-Event — same as payload.event; handy for routing before parsing the body

Verifying signatures

import hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
 expected ="sha256=" + hmac.new(
 secret.encode(), body, hashlib.sha256
 ).hexdigest()
 return hmac.compare_digest(expected, header)

import { createHmac, timingSafeEqual } from "crypto";

export function verify(body, header, secret) {
 const expected =
"sha256=" +
 createHmac("sha256", secret).update(body).digest("hex");
 const a = Buffer.from(expected);
 const b = Buffer.from(header);
 return a.length === b.length && timingSafeEqual(a, b);
}

Delivery & retries

A 2xx response is treated as delivered. Anything else counts toward a consecutive-failure tally; a subscription is auto-paused after 10 consecutive failures. Paused subscriptions stop receiving events — resume them from the dashboard once your endpoint is healthy. Click Send test on a subscription to fire a synthetic event: "test" payload — test deliveries don't count against the failure tally.