Skip to main content

​
Purpose

One of the aims of this specification is to make data interoperable between systems. JSON schema allows us to do this with the data structure, but the implementation of APIs will also need to have standard implementations for applications to use the data efficiently.

​
API Endpoints

The Digital Planning Data Schema defines two main API categories:

​
Public Endpoints

Public endpoints do not require authentication and return redacted (non-sensitive) data. These are designed for public access and transparency. Base path: /api/@next/public/applications
  • Applications listing and search
  • Individual application details
  • Documents associated with applications
  • Public comments
  • Specialist comments

​
Private Endpoints

Private endpoints require authentication and return unredacted data with sensitive information. These are for internal use by planning authorities. Base path: /api/@next/applications
  • Full application data
  • Unredacted documents
  • Complete comment histories
  • Submission capabilities

​
Authentication

All endpoints use header-based authentication:
​
x-client
string
required
Client identifier for filtering data by planning authorityExample: camden
​
x-service
string
required
Service identifier for tracking API usageExample: documentation-example

​
Data Formats

​
Dates

The API follows strict date formatting conventions:
  • Date-only values: YYYY-MM-DD format. Date keys should have the suffix Date.
  • DateTime values: ISO 8601 format in UTC. DateTime keys should have the suffix At.
interface Example {
  receivedDate: Date;      // Date-only (YYYY-MM-DD)
  createdAt: DateTime;     // Datetime (ISO 8601 with UTC, e.g., 2024-01-01T10:30:00Z)
}
Examples:
  • receivedDate: "2024-03-15"
  • createdAt: "2024-03-15T10:30:00Z"

​
Available Endpoints

HTTP MethodPathPublicPaginationSortSearch
GET/api/@next/public/applicationsYESYESYESYES
GET/api/@next/public/applications/{applicationId}YESNONONO
GET/api/@next/public/applications/{applicationId}/documentsYESYESYESYES
GET/api/@next/public/applications/{applicationId}/documents/{documentId}YESNONONO
GET/api/@next/public/applications/{applicationId}/publicCommentsYESYESYESYES
GET/api/@next/public/applications/{applicationId}/publicComments/{publicCommentId}YESNONONO
GET/api/@next/public/applications/{applicationId}/specialistCommentsYESYESYESYES
GET/api/@next/public/applications/{applicationId}/specialistComments/{specialistId}YESYESYESYES
GET/api/@next/applicationsNOYESYESYES
GET/api/@next/applications/{applicationId}NONONONO
GET/api/@next/applications/{applicationId}/documentsNOYESYESYES
GET/api/@next/applications/{applicationId}/documents/{documentId}NONONONO
GET/api/@next/applications/{applicationId}/publicCommentsNOYESYESYES
GET/api/@next/applications/{applicationId}/publicComments/{publicCommentId}NONONONO
GET/api/@next/applications/{applicationId}/specialistCommentsNOYESYESYES
GET/api/@next/applications/{applicationId}/specialistComments/{specialistId}NOYESYESYES
POST/api/@next/applications/{applicationId}/publicCommentsNOn/an/an/a
POST/api/@next/applications/{applicationId}/specialistCommentsNOn/an/an/a

​
Next Steps

Response Structure

Learn about the standard API response format

Pagination

Implement offset and cursor-based pagination

Filtering

Use AND/OR filters and search parameters

Endpoints

Detailed endpoint specifications

Build docs developers (and LLMs) love

Get started for freeTalk to us