Service Management

Internal API endpoints for managing services in GOV.UK Notify

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": "[e-mail]",
      "mobile_number": "[phone]",
      "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": ["[e-mail]"],
  "phone_numbers": ["[phone]"]
}

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": ["[e-mail]", "[e-mail]"],
  "phone_numbers": ["[phone]", "[phone]"]
}

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

Related Endpoints

See also:

• API Key Management - Manage service API keys
• Template Management - Manage service templates
• User Management - Manage users across services