REST API Reference

Overview

The AppealBase REST API lets you search planning appeals (England) and fetch full decision text by reference. All endpoints require an API key and return JSON. Your API key must be linked to a user account; usage is rate-limited per account tier per calendar month.

Base URL

https://www.appealbase.com

All endpoint paths below are relative to this base.

Authentication

Send your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Your API key must be linked to an AppealBase user account. If not, requests return 403 Forbidden with a message to contact support.

Send request bodies as JSON with Content-Type: application/json.

Rate limiting

Each API key is tied to a user account with an account tier. Tiers have a monthly call limit (number of requests per calendar month). Limits vary by tier (e.g. 1000 requests/month for standard). When you exceed the limit, the API returns 429 Too Many Requests with an error message and your limit. Limits reset at the start of each calendar month.

Contact info@appealbase.com to discuss higher limits or a different tier.

Error responses

Errors are returned as JSON with an error field. Rate limit responses also include limit.

Search appeals

POST /api/v1/search

Full-text search with optional filters. Returns paginated summaries (truncated text and snippets). Use the retrieve endpoint to get full decision text for a specific reference.

Query tips: The query field is full-text only. For date-only or area-only searches (e.g. "all appeals from 2024-01-15" or "appeals in Birmingham"), use a minimal query such as appeal and set date_from/date_to and/or lpa.

Request body

Response structure

Top-level:

Each item in results:

Example request

curl -X POST https://www.appealbase.com/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "green belt", "decision": "Allowed", "page": 1, "pageSize": 2}'

Example response

Real response from query: "green belt", decision: "Allowed", pageSize: 2 (first result only; summary and snippets truncated).

{
  "results": [
    {
      "reference": "6001357",
      "lpa_name": "Bromley",
      "decision_date": "2026-03-04",
      "decision": "Allowed",
      "appeal_type": "Householder",
      "development_type": null,
      "inspector_name": null,
      "site_address": "26 Standard Road, Downe, Orpington, BR6 7HL",
      "site_area": null,
      "procedure": "Written",
      "full_text_char_count": 16989,
      "summary": "Appeal Decision\n\n**by R Cahalane BA(Hons) MSc MRTPI**\n\n**an Inspector appointed by the Secretary of State**\n\n**Decision date: 4[th] March 2026**\n\n**Appeal Ref: 6001357**\n**26 Standard Road, Downe, Orpington, Bromley BR6 7HL**\n\n- The appeal is made under section 78 of the Town and Country Planning Act... [truncated]",
      "snippets": ["...rt refers to a\n\nlikely loss of light to the occupiers of No.30 Standard Road. This therefore forms an\nadditional consideration for this appeal.\n\n**... [truncated]", "...learly outweighed by other considerations so as to amount to very special\ncircumstances required to justify the proposal.\n\n**Reasons**\n\n_Whether in... [truncated]", "...een\n\nBelt as designated on the Policies Map of the Council's Local Plan (LP) (adopted\n2019). Policy 49 of the LP is consistent with the Framework i... [truncated]", "...nsion or alteration of a building provided that it does\n\nnot result in disproportionate additions over and above the size of the original\nbuilding.... [truncated]", "...ionate addition over\n\nand above the size of the original form of No 26. The increased built form would be\nvisible from surrounding vantage points. ... [truncated]"],
      "created_at": "2026-03-04T12:30:10.080951+00:00",
      "lpa_code": null,
      "floor_space": null,
      "no_residences": null,
      "lpa_app_reference": "25/01852/FULL6",
      "appellant": "Mr & Mrs J Keys",
      "agent": null,
      "site_green_belt": null,
      "agri_holding": null,
      "listed_building": null,
      "historic_building_grant": null,
      "conservation_area": null,
      "flooding_issue": null,
      "aonb": null,
      "sssi": null
    }
  ],
  "totalCount": 3250,
  "page": 1,
  "pageSize": 2,
  "totalPages": 1625
}

Retrieve full decision text

POST /api/v1/retrieve

Fetch the full decision text and metadata for one appeal by its 7-digit reference (e.g. from search results).

Request body

Response structure

Top-level:

Fields in appeal:

Example request

curl -X POST https://www.appealbase.com/api/v1/retrieve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference": "6001357"}'

Example response

Real response for reference: "6001357" (all fields; full_text truncated).

{
  "appeal": {
    "created_at": "2026-03-04T12:30:10.080951+00:00",
    "lpa_decision_date": null,
    "received_date": null,
    "valid_date": null,
    "start_date": null,
    "decision_date": "2026-03-04",
    "site_green_belt": null,
    "agri_holding": null,
    "listed_building": null,
    "historic_building_grant": null,
    "conservation_area": null,
    "flooding_issue": null,
    "aonb": null,
    "sssi": null,
    "redetermined": null,
    "bespoke": null,
    "recovered_date": null,
    "not_recovered_date": null,
    "call_in_date": null,
    "costs_applied_for": null,
    "enforcement_ground_cnt": null,
    "full_text_char_count": 16989,
    "reference": "6001357",
    "appeal_type": "Householder",
    "lpa_name": "Bromley",
    "lpa_code": null,
    "floor_space": null,
    "no_residences": null,
    "lpa_app_reference": "25/01852/FULL6",
    "full_text": "Appeal Decision\n\n**by R Cahalane BA(Hons) MSc MRTPI**\n\n**an Inspector appointed by the Secretary of State**\n\n**Decision date: 4[th] March 2026**\n\n**Appeal Ref: 6001357**\n**26 Standard Road, Downe, Orpington, Bromley BR6 7HL**\n\n- The appeal is made under section 78 of the Town and Country Planning Act 1990 (as amended) against a refusal to grant planning permission.\n\n- The appeal is made by Mr & Mrs J Keys against the decision of the Council of the London Borough of Bromley.\n\n... [truncated, 16987 chars total]",
    "costs_text": null,
    "enforcement_grounds": null,
    "decision": "Allowed",
    "inspector_name": null,
    "procedure": "Written",
    "development_type": null,
    "appeal_type_reason": null,
    "appeal_reason": null,
    "type_detail": null,
    "jurisdiction": null,
    "link_status": null,
    "lead_case": null,
    "appellant": "Mr & Mrs J Keys",
    "agent": null,
    "site_address": "26 Standard Road, Downe, Orpington, BR6 7HL",
    "site_area": null
  }
}