Documentation Index
Fetch the complete documentation index at: https://mintlify.com/alphagov/notifications-api/llms.txt
Use this file to discover all available pages before exploring further.
These endpoints are used by the admin interface to manage services. All endpoints require admin authentication.
List Services
GET /service
Retrieve a list of all services, optionally filtered by user or with detailed statistics.
Query Parameters
| Parameter | Type | Description |
|---|
only_active | boolean | Filter to only active services (default: false) |
detailed | boolean | Include statistics with each service (default: false) |
user_id | uuid | Filter services by user ID |
include_from_test_key | boolean | Include notifications from test keys in statistics (default: true) |
start_date | date | Start date for statistics (YYYY-MM-DD format) |
end_date | date | End date for statistics (YYYY-MM-DD format) |
Response
{
"data": [
{
"id": "service-uuid",
"name": "My Service",
"active": true,
"restricted": false,
"created_at": "2023-01-01T00:00:00Z",
"organisation_type": "central",
"email_branding": "branding-uuid",
"letter_branding": "letter-branding-uuid"
}
]
}
Get Service by ID
GET /service/{service_id}
Retrieve details for a specific service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Query Parameters
| Parameter | Type | Description |
|---|
detailed | boolean | Include statistics (default: false) |
today_only | boolean | Only include today’s statistics (default: false) |
Response
{
"data": {
"id": "service-uuid",
"name": "My Service",
"active": true,
"restricted": false,
"created_at": "2023-01-01T00:00:00Z",
"organisation_type": "central",
"permissions": ["email", "sms", "letter"],
"email_branding": "branding-uuid",
"letter_branding": "letter-branding-uuid",
"statistics": {
"email": {"requested": 100, "delivered": 95, "failed": 5},
"sms": {"requested": 50, "delivered": 48, "failed": 2}
}
}
}
Create Service
POST /service
Create a new service.
Request Body
{
"name": "New Service",
"user_id": "user-uuid",
"organisation_type": "central",
"active": true,
"restricted": true,
"permissions": ["email", "sms"]
}
Response
{
"data": {
"id": "service-uuid",
"name": "New Service",
"active": true,
"restricted": true,
"created_at": "2023-01-01T00:00:00Z",
"organisation_type": "central"
}
}
201 Created
Update Service
POST /service/{service_id}
Update an existing service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Request Body
{
"name": "Updated Service Name",
"restricted": false,
"email_branding": "branding-uuid",
"letter_branding": "letter-branding-uuid"
}
Response
{
"data": {
"id": "service-uuid",
"name": "Updated Service Name",
"restricted": false,
"email_branding": "branding-uuid"
}
}
Archive Service
POST /service/{service_id}/archive
Archive a service. This makes the service inactive, archives templates, and revokes API keys. This operation cannot be reversed.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
Status Code: 204 No Content
Find Services by Name
GET /service/find-services-by-name
Search for services by partial name match.
Query Parameters
| Parameter | Type | Description |
|---|
service_name | string | Partial service name to search for (required) |
Response
{
"data": [
{
"id": "service-uuid",
"name": "Matching Service",
"active": true,
"restricted": false,
"organisation_name": "Cabinet Office"
}
]
}
Get Service Users
GET /service/{service_id}/users
Retrieve all users associated with a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"data": [
{
"id": "user-uuid",
"name": "John Smith",
"email_address": "john.smith@example.gov.uk",
"mobile_number": "+447700900123",
"permissions": ["manage_users", "manage_templates", "send_messages"]
}
]
}
Add User to Service
POST /service/{service_id}/users/{user_id}
Add a user to a service with specified permissions.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
user_id | uuid | The user ID |
Request Body
{
"permissions": [
{"permission": "send_messages"},
{"permission": "manage_templates"}
],
"folder_permissions": ["folder-uuid-1", "folder-uuid-2"]
}
Response
{
"data": {
"id": "service-uuid",
"name": "My Service",
"users": [
{
"id": "user-uuid",
"name": "John Smith"
}
]
}
}
201 Created
Remove User from Service
DELETE /service/{service_id}/users/{user_id}
Remove a user from a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
user_id | uuid | The user ID |
Response
Status Code: 204 No Content
Errors
- 400 Bad Request: Cannot remove the only user from a service
- 404 Not Found: User not found in service
Get Service History
GET /service/{service_id}/history
Retrieve historical changes to a service, including service updates, API key changes, and template modifications.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"data": {
"service_history": [
{
"id": "service-uuid",
"name": "My Service",
"version": 2,
"updated_at": "2023-01-01T00:00:00Z"
}
],
"api_key_history": [
{
"id": "key-uuid",
"name": "API Key 1",
"created_at": "2023-01-01T00:00:00Z",
"revoked_at": null
}
],
"template_history": [
{
"id": "template-uuid",
"name": "Welcome Email",
"version": 3,
"updated_at": "2023-01-01T00:00:00Z"
}
]
}
}
Get Guest List
GET /service/{service_id}/guest-list
Retrieve the guest list for a restricted service. The guest list contains email addresses and phone numbers that can receive notifications in trial mode.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"email_addresses": ["test@example.gov.uk"],
"phone_numbers": ["+447700900123"]
}
Update Guest List
PUT /service/{service_id}/guest-list
Update the guest list for a restricted service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Request Body
{
"email_addresses": ["test1@example.gov.uk", "test2@example.gov.uk"],
"phone_numbers": ["+447700900123", "+447700900456"]
}
Response
Status Code: 204 No Content
Service Statistics
GET /service/{service_id}/statistics
Get notification statistics for a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Query Parameters
| Parameter | Type | Description |
|---|
today_only | boolean | Only return today’s statistics (default: false) |
limit_days | integer | Number of days to include (default: 7) |
Response
{
"data": {
"email": {
"requested": 1000,
"delivered": 950,
"failed": 50
},
"sms": {
"requested": 500,
"delivered": 490,
"failed": 10
},
"letter": {
"requested": 100,
"delivered": 95,
"failed": 5
}
}
}
Get Monthly Notification Stats
GET /service/{service_id}/notifications/monthly
Get monthly notification statistics for a financial year.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Query Parameters
| Parameter | Type | Description |
|---|
year | integer | Financial year (required) |
Response
{
"data": {
"2023-04": {
"email": {"requested": 100, "delivered": 95, "failed": 5},
"sms": {"requested": 50, "delivered": 48, "failed": 2}
},
"2023-05": {
"email": {"requested": 150, "delivered": 140, "failed": 10}
}
}
}