Service Management

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"
  }
}

Status Code: 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": "[email protected]",
      "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"
      }
    ]
  }
}

Status Code: 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": ["[email protected]"],
  "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": ["[email protected]", "[email protected]"],
  "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}
    }
  }
}

Billing & Stats

Branding & Organisation

Callbacks & Events

​List Services

​Query Parameters

​Response

​Get Service by ID

​Path Parameters

​Query Parameters

​Response

​Create Service

​Request Body

​Response

​Update Service

​Path Parameters

​Request Body

​Response

​Archive Service

​Path Parameters

​Response

​Find Services by Name

​Query Parameters

​Response

​Get Service Users

​Path Parameters

​Response

​Add User to Service

​Path Parameters

​Request Body

​Response

​Remove User from Service

​Path Parameters

​Response

​Errors

​Get Service History

​Path Parameters

​Response

​Get Guest List

​Path Parameters

​Response

​Update Guest List

​Path Parameters

​Request Body

​Response

​Service Statistics

​Path Parameters

​Query Parameters

​Response

​Get Monthly Notification Stats

​Path Parameters

​Query Parameters

​Response

​Related Endpoints

Build docs developers (and LLMs) love

List Services

Query Parameters

Response

Get Service by ID

Path Parameters

Query Parameters

Response

Create Service

Request Body

Response

Update Service

Path Parameters

Request Body

Response

Archive Service

Path Parameters

Response

Find Services by Name

Query Parameters

Response

Get Service Users

Path Parameters

Response

Add User to Service

Path Parameters

Request Body

Response

Remove User from Service

Path Parameters

Response

Errors

Get Service History

Path Parameters

Response

Get Guest List

Path Parameters

Response

Update Guest List

Path Parameters

Request Body

Response

Service Statistics

Path Parameters

Query Parameters

Response

Get Monthly Notification Stats

Path Parameters

Query Parameters

Response

Related Endpoints