API reference · v1

Retrieve an application

Retrieve current collected details and source evidence. Empty sections must be interpreted alongside availability.

GET/v1/applications/{id}

Send a secret API key in Authorization: Bearer YOUR_API_KEY. Each successful request uses one of your 500 monthly requests.

Parameters

idpath · required: Opaque ID returned by the corresponding list endpoint. URL-encode the whole value.

Response fields

schemaVersionnumber

Public application schema version within API v1.

idstring

Opaque application identifier.

authorityIdstring

Authority identifier.

authorityNamestring

Council name.

registerIdstring

Source register identifier.

referencestring

Council reference.

alternativeReferencesarray

Other published references; empty when none collected.

proposalstring

Proposal text.

officialTitlestring · optional

Published title Omitted when not collected.

addressstring

Published address

applicationTypestring · optional

Original application type Omitted when not collected.

developmentTypestring · optional

Original development type Omitted when not collected.

wardstring · optional

Council ward Omitted when not collected.

parishstring · optional

Parish Omitted when not collected.

agentstring · optional

Published agent Omitted when not collected.

statusobject

Value from the collected source record.

Show object fields

rawstring: Original status.
lifecycle"pending" | "decided" | "withdrawn" | "unknown": Normalised application stage: pending awaits a final decision; decided has a recorded decision; withdrawn was withdrawn; unknown cannot be classified from collected evidence.
outcome"approved" | "refused" | "withdrawn" | "other" | "unknown": Normalised outcome. other is a published result outside approval/refusal/withdrawal; unknown means no classified outcome. Preserve original decision text for display.
decisionstring · optional: Original decision Omitted when not collected.
appealStatusstring · optional: Original appeal status Omitted when not collected.
appealDecisionstring · optional: Original appeal decision Omitted when not collected.
appealActiveboolean: Whether collected appeal evidence indicates an active appeal. false does not prove no appeal exists.

locationobject

Value from the collected source record.

Show object fields

latitudenumber · optional: WGS84 latitude; omitted without source coordinates.
longitudenumber · optional: WGS84 longitude; omitted without source coordinates.
eastingnumber · optional: Source grid easting in metres; omitted when not collected. Read with crs.
northingnumber · optional: Source grid northing in metres; omitted when not collected. Read with crs.
crsstring · optional: Published coordinate reference system Omitted when not collected.
uprnstring · optional: UPRN explicitly supplied by source; not independently verified Omitted when not collected.
postcodestring · optional: Published postcode Omitted when not collected.
precision"source_point" | "postcode" | "unknown": source_point: point supplied by council; postcode: approximate postcode-level location; unknown: precision not established.
sourceUrlstring: Absolute source URL. Council links may change or require a browser session.
mapUrlstring · optional: Council map link; omitted when not collected.

datesarray

Array of the items described below.

Show item fields

keystring: Date field identifier.
labelstring: Council label.
datestring: Calendar date; read with precision.
precision"day" | "month" | "year": Published date precision. Do not interpret a month or year value as an exact day.
rawstring: Original date text.
evidenceType"published_milestone" | "published_deadline": Value from the collected source record.
sourceUrlstring: Absolute source URL. Council links may change or require a browser session.

documentsarray

Collected document history, including removals. Use the documents endpoint for current links.

Show item fields

idstring: Stable document identifier.
titlestring: Council document title.
sourceTypestring: Original document type.
category"Plans" | "Reports" | "Decisions" | "Forms" | "Correspondence" | "Other": Broad document grouping inferred from the source title and type; Other is unclassified.
publishedDatestring · optional: Published calendar date Omitted when not collected.
mimeTypestring · optional: Published MIME type Omitted when not collected.
urlstring: Absolute source URL. Council links may change or require a browser session.
listUrlstring: Council document-list page to try if the direct link requires a session.
firstSeenAtstring: UTC time this document was first observed, not its publication date.
lastSeenAtstring: UTC time this document was last present in a collected list.
removedAtstring · optional: When removal was observed; omitted for current documents.

documentsAvailability"complete" | "partial" | "unavailable" | "not_published"

complete: section collected; partial: some evidence missing; unavailable: could not read; not_published: source explicitly publishes none.

relationshipsarray

Array of the items described below.

Show item fields

idstring: Value from the collected source record.
kind"application" | "appeal" | "property" | "unknown": Value from the collected source record.
referencestring: Value from the collected source record.
titlestring: Value from the collected source record.
urlstring: Absolute source URL. Council links may change or require a browser session.
applicationIdstring · optional: Value from the collected source record.
evidence"explicit" | "inferred": Value from the collected source record.
sourceUrlstring: Absolute source URL. Council links may change or require a browser session.

relationshipsAvailability"complete" | "partial" | "unavailable" | "not_published"

complete: section collected; partial: some evidence missing; unavailable: could not read; not_published: source explicitly publishes none.

conditionsobject

Value from the collected source record.

Show object fields

availability"complete" | "partial" | "unavailable" | "not_published"

complete: section collected; partial: some evidence missing; unavailable: could not read; not_published: source explicitly publishes none.

itemsarray

Array of the items described below.

Show item fields

textstring: Value from the collected source record.
reasonstring · optional: Value from the collected source record.

sourceUrlstring · optional

Absolute source URL. Council links may change or require a browser session.

sectionsobject

Source section evidence; internal fetch errors are excluded.

Show fields for each entry

availability"complete" | "partial" | "unavailable" | "not_published": complete: section collected; partial: some evidence missing; unavailable: could not read; not_published: source explicitly publishes none.
urlstring: Absolute source URL. Council links may change or require a browser session.
checkedAtstring: UTC timestamp in ISO 8601 format.
fieldsobject: Value from the collected source record.

timelinearray

Published and observed events, including superseded history; empty when no events were collected.

Show item fields

idstring: Stable event identifier.
applicationIdstring: Application identifier.
kindstring: Milestone or change type; new values may be added.
titlestring: Human-readable event title.
datestring: Published date or observation date. Interpret with precision and evidenceType.
precision"day" | "month" | "year": Published date precision. Do not interpret a month or year value as an exact day.
rawDatestring · optional: Original date text Omitted when not collected.
observedAtstring: UTC time PlanningTrack observed this event; separate from its published date.
evidenceType"published_milestone" | "published_deadline" | "detected_change": published_milestone: council event date; published_deadline: council deadline; detected_change: time a change was observed.
sourceUrlstring: Absolute source URL. Council links may change or require a browser session.
sourceFieldstring · optional: Original source field Omitted when not collected.
snapshotIdstring: Immutable snapshot identifier.
supersedesEventIdstring · optional: Earlier event replaced by this one Omitted when not collected.
supersededByEventIdstring · optional: Later replacement event Omitted when not collected.
documentIdstring · optional: Related document identifier Omitted when not collected.
withdrawnAtstring · optional: UTC time this event stopped being supported by the source. Omitted while current.

sourceUrlstring

Absolute source URL. Council links may change or require a browser session.

sourceUpdatedAtstring · optional

Source-reported update time; omitted if source supplies none. It is not the collection time.

firstSeenAtstring

UTC time this application was first collected.

lastCheckedAtstring

UTC time of the latest persisted collection check.

lastSourceChangeAtstring

UTC observation time of the most recent detected source change; initial observation for newly discovered records.

snapshotIdstring

Immutable content snapshot identifier.

previousSnapshotIdstring · optional

Previous snapshot identifier Omitted when not collected.

completeness"complete" | "partial" | "unavailable" | "not_published"

complete: section collected; partial: some evidence missing; unavailable: could not read; not_published: source explicitly publishes none.

Errors

Error codes, request IDs, retry behaviour, and allowance headers apply to every endpoint. Invalid or repeated query parameters return 400; unavailable records return 404. Source failures never become successful empty results.

Request example

curl --fail-with-body --silent --show-error \
  'https://api.planningtrack.co.uk/v1/applications/APPLICATION_ID' \
  -H "Authorization: Bearer $PLANNINGTRACK_API_KEY"

Run a live request

Illustrative fixture · not a live response

{
  "schemaVersion": 1,
  "id": "local-authority-oxo-idox~EXAMPLE",
  "authorityId": "local-authority-oxo",
  "authorityName": "Oxford City Council",
  "registerId": "local-authority-oxo-idox",
  "reference": "26/01234/FUL",
  "alternativeReferences": [],
  "proposal": "Erection of a single-storey rear extension with rooflights.",
  "address": "24 Example Road, Oxford, OX1",
  "applicationType": "Full planning permission",
  "status": {
    "raw": "Awaiting decision",
    "lifecycle": "pending",
    "outcome": "unknown",
    "appealActive": false
  },
  "location": {
    "postcode": "OX1",
    "precision": "unknown",
    "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE"
  },
  "dates": [
    {
      "key": "received",
      "label": "Received",
      "date": "2026-03-12",
      "precision": "day",
      "raw": "12 March 2026",
      "evidenceType": "published_milestone",
      "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE"
    },
    {
      "key": "validated",
      "label": "Validated",
      "date": "2026-03-18",
      "precision": "day",
      "raw": "18 March 2026",
      "evidenceType": "published_milestone",
      "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE"
    }
  ],
  "documents": [
    {
      "id": "example-document-1",
      "title": "Location plan",
      "sourceType": "Plans",
      "category": "Plans",
      "mimeType": "application/pdf",
      "url": "https://example.invalid/oxford/applications/EXAMPLE/example-document-1.pdf",
      "listUrl": "https://example.invalid/oxford/applications/EXAMPLE/documents",
      "firstSeenAt": "2026-09-13T10:00:00.000Z",
      "lastSeenAt": "2026-09-13T10:00:00.000Z"
    },
    {
      "id": "example-document-2",
      "title": "Proposed floor plans and elevations",
      "sourceType": "Plans",
      "category": "Plans",
      "mimeType": "application/pdf",
      "url": "https://example.invalid/oxford/applications/EXAMPLE/example-document-2.pdf",
      "listUrl": "https://example.invalid/oxford/applications/EXAMPLE/documents",
      "firstSeenAt": "2026-09-13T10:00:00.000Z",
      "lastSeenAt": "2026-09-13T10:00:00.000Z"
    }
  ],
  "documentsAvailability": "complete",
  "relationships": [],
  "relationshipsAvailability": "not_published",
  "conditions": {
    "availability": "not_published",
    "items": [],
    "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE"
  },
  "sections": {
    "summary": {
      "availability": "complete",
      "url": "https://example.invalid/oxford/applications/EXAMPLE",
      "checkedAt": "2026-09-13T10:00:00.000Z",
      "fields": {
        "Reference": "26/01234/FUL",
        "Address": "24 Example Road, Oxford, OX1"
      }
    }
  },
  "timeline": [
    {
      "id": "example-event-received",
      "applicationId": "local-authority-oxo-idox~EXAMPLE",
      "kind": "received",
      "title": "Application received",
      "date": "2026-03-12",
      "precision": "day",
      "rawDate": "12 March 2026",
      "observedAt": "2026-09-13T10:00:00.000Z",
      "evidenceType": "published_milestone",
      "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE",
      "sourceField": "Received",
      "snapshotId": "example-snapshot"
    },
    {
      "id": "example-event-validated",
      "applicationId": "local-authority-oxo-idox~EXAMPLE",
      "kind": "validated",
      "title": "Application validated",
      "date": "2026-03-18",
      "precision": "day",
      "rawDate": "18 March 2026",
      "observedAt": "2026-09-13T10:00:00.000Z",
      "evidenceType": "published_milestone",
      "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE",
      "sourceField": "Validated",
      "snapshotId": "example-snapshot"
    }
  ],
  "sourceUrl": "https://example.invalid/oxford/applications/EXAMPLE",
  "firstSeenAt": "2026-09-13T10:00:00.000Z",
  "lastCheckedAt": "2026-09-13T10:00:00.000Z",
  "lastSourceChangeAt": "2026-09-13T10:00:00.000Z",
  "snapshotId": "example-snapshot",
  "completeness": "partial"
}

Base URL https://api.planningtrack.co.uk