Skip to main content

​
Standard Response Format

All API endpoints follow a consistent response structure to ensure predictable data handling: 
export interface ApiResponse<T> {
  data: T | null;
  pagination?: Pagination | CursorPagination;
  status?: {
    code: number;
    message: string;
    detail?: string;
  };
}

​
Response Fields

​
data
T | null
The actual data being returned. Will be null if the request failed or no data is available.
​
pagination
Pagination | CursorPagination
Optional pagination metadata. Present only on list endpoints that support pagination.Can be either:
  • Offset pagination (recommended for most cases)
  • Cursor-based pagination (for large datasets)
​
status
object
HTTP status information

​
Success Response Example

{
  "data": {
    "applicationType": "planningPermission",
    "data": {
      "application": {
        "reference": "ABC-2024-001",
        "stage": "consultation",
        "status": "undetermined"
      }
    }
  },
  "pagination": {
    "resultsPerPage": 10,
    "currentPage": 1,
    "totalPages": 5,
    "totalResults": 47,
    "totalAvailableItems": 1234
  },
  "status": {
    "code": 200,
    "message": "OK"
  }
}

​
Error Response Examples

​
400 Bad Request

{
  "data": null,
  "status": {
    "code": 400,
    "message": "Bad Request",
    "detail": "Invalid query parameter: sortBy must be one of [publishedAt, receivedAt]"
  }
}

​
404 Not Found

{
  "data": null,
  "status": {
    "code": 404,
    "message": "Not Found",
    "detail": "Application with ID 'ABC-2024-999' not found"
  }
}

​
422 Unprocessable Entity

{
  "data": null,
  "status": {
    "code": 422,
    "message": "Unprocessable Entity",
    "detail": "receivedAtFrom requires receivedAtTo to be specified"
  }
}

​
500 Internal Server Error

{
  "data": null,
  "status": {
    "code": 500,
    "message": "Internal Server Error"
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescriptionWhen Used
200OKRequest successful
400Bad RequestInvalid request parameters
404Not FoundResource doesn’t exist
422Unprocessable EntityValid syntax but semantic errors
500Internal Server ErrorServer-side error

​
Content Type

All responses use JSON format: 
Content-Type: application/json

​
Data Types

The data field type varies by endpoint:

​
Single Resource

For endpoints returning a single item: 
ApiResponse<PostSubmissionApplication>

​
Collection of Resources

For endpoints returning multiple items: 
ApiResponse<PostSubmissionApplication[]>
ApiResponse<PostSubmissionFile[]>
ApiResponse<PublicComment[]>

​
Empty Success Response

For POST endpoints that don’t return data: 
{
  "data": null,
  "status": {
    "code": 200,
    "message": "OK"
  }
}

​
Next Steps

Pagination

Learn about pagination metadata

Endpoints

Explore specific endpoint responses

Build docs developers (and LLMs) love

Get started for freeTalk to us