Wards
Wards represent electoral divisions or geographic areas. Cases and events are scoped to wards for geographic reporting.
List wards
/api/wardsReturns all wards for your tenant, ordered alphabetically by name.
Required scope
This endpoint requires the wards:read scope.
Example response
[
{
"id": "ward-abc123",
"tenantId": "tenant-001",
"name": "Truro Boscawen",
"boundaryDescription": "Covers central Truro including Boscawen Park and Lemon Quay",
"councilTier": "unitary",
"latitude": 50.263,
"longitude": -5.051,
"enabled": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
]
Create a ward
/api/wardsCreates a new ward within the current tenant.
Returns 201 with the created ward object. Returns 409 if a ward with the same name already exists.
Get a ward
/api/wards/:idReturns a single ward by ID.
Example response
{
"id": "ward-abc123",
"tenantId": "tenant-001",
"name": "Truro Boscawen",
"boundaryDescription": "Covers central Truro including Boscawen Park and Lemon Quay",
"councilTier": "unitary",
"latitude": 50.263,
"longitude": -5.051,
"enabled": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
Update a ward
/api/wards/:idUpdates a ward's fields. Only provided fields are changed.
Returns the updated ward object. Returns 404 if the ward does not exist, or 409 if the new name conflicts with an existing ward.
Councillors & Users
Users represent councillors, admins, and caseworkers within a tenant.
List users
/api/usersReturns all users for your tenant, ordered alphabetically by name.
Required scope
This endpoint requires the users:read scope.
Example response
[
{
"id": "user-abc123",
"name": "Jane Smith",
"email": "jane@example.gov.uk",
"role": "councillor",
"enabled": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"planOverride": null,
"planOverrideExpiresAt": null,
"planOverrideReason": null
}
]
Plan-tier visibility
The full user model includes additional profile fields (bio, publicEmail, publicPhone, officeAddress, party, social URLs, interests, responsibilities) that are only populated for councillors. These fields are visible on the public profile page and their availability depends on whether the councillor has claimed their profile.
Create a user
/api/usersCreates a new user within the current tenant. Requires councillor role or above.
Caseworker seats require Pro plan
Creating users with the caseworker role requires a Pro plan or higher. The API returns 403 with details about the required plan if the tenant's plan does not support caseworker seats.
Returns 201 with the created user (password is never returned). Returns 409 if a user with the same email already exists.
Update a user
/api/users/:idUpdates a user's fields. Requires councillor role or above.
Returns the updated user object. Returns 404 if the user does not exist within the tenant.
Categories
Categories provide thematic grouping for cases. They support keyword-based auto-suggestion when creating new cases.
List categories
/api/categoriesReturns all categories for your tenant, ordered by sort order.
Required scope
This endpoint requires the categories:read scope.
Example response
[
{
"id": "cat-abc123",
"tenantId": "tenant-001",
"name": "Housing",
"description": "Council housing, repairs, and homelessness",
"keywords": "housing,repairs,damp,mould,homelessness,rent",
"enabled": true,
"sortOrder": 0,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
]
Create a category
/api/categoriesCreates a new category within the current tenant.
Returns 201 with the created category. The sortOrder is automatically set to one above the current maximum. Returns 409 if a category with the same name already exists.
Get a category
/api/categories/:idReturns a single category by ID.
Example response
{
"id": "cat-abc123",
"tenantId": "tenant-001",
"name": "Housing",
"description": "Council housing, repairs, and homelessness",
"keywords": "housing,repairs,damp,mould,homelessness,rent",
"enabled": true,
"sortOrder": 0,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
Update a category
/api/categories/:idUpdates a category's fields. Only provided fields are changed.
Returns the updated category object. Returns 404 if the category does not exist, or 409 if the new name conflicts with an existing category.
Suggest a category
/api/categories/suggestSuggests the best matching category for a given case summary, based on keyword matching.
Example response
{
"suggestion": {
"id": "cat-abc123",
"name": "Roads & Pavements"
}
}
Returns { "suggestion": null } if no category matches the provided summary.
Using category suggestions
Call this endpoint as the user types a case summary to auto-populate the category field. The suggestion is based on keyword overlap between the summary text and each category's keywords field.