Skip to main content

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 users. All endpoints require admin authentication.

Create User

POST /user Create a new user account.

Request Body

{
  "name": "John Smith",
  "email_address": "john.smith@example.gov.uk",
  "mobile_number": "+447700900123",
  "password": "SecurePassword123!",
  "auth_type": "sms_auth"
}

Response

{
  "data": {
    "id": "user-uuid",
    "name": "John Smith",
    "email_address": "john.smith@example.gov.uk",
    "mobile_number": "+447700900123",
    "state": "pending",
    "auth_type": "sms_auth",
    "created_at": "2023-01-01T00:00:00Z"
  }
}
Status Code: 201 Created

Get User by ID

GET /user/{user_id} Retrieve a user’s details.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Response

{
  "data": {
    "id": "user-uuid",
    "name": "John Smith",
    "email_address": "john.smith@example.gov.uk",
    "mobile_number": "+447700900123",
    "state": "active",
    "auth_type": "sms_auth",
    "email_access_validated_at": "2023-01-01T00:00:00Z",
    "logged_in_at": "2023-01-01T12:00:00Z",
    "failed_login_count": 0
  }
}

Update User Attribute

POST /user/{user_id} Update user attributes such as name, email, or mobile number.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "name": "John A. Smith",
  "email_address": "john.a.smith@example.gov.uk",
  "mobile_number": "+447700900456",
  "updated_by": "admin-user-uuid"
}

Response

{
  "data": {
    "id": "user-uuid",
    "name": "John A. Smith",
    "email_address": "john.a.smith@example.gov.uk",
    "mobile_number": "+447700900456"
  }
}
When updated_by is provided and email or mobile number is changed, the user will receive a notification about the change.

Archive User

POST /user/{user_id}/archive Archive a user account. The user will no longer be able to log in.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Response

Status Code: 204 No Content

Activate User

POST /user/{user_id}/activate Activate a previously archived user account.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Response

{
  "data": {
    "id": "user-uuid",
    "state": "active"
  }
}

Get User by Email

POST /user/email Find a user by email address.

Request Body

{
  "email": "john.smith@example.gov.uk"
}

Response

{
  "data": {
    "id": "user-uuid",
    "name": "John Smith",
    "email_address": "john.smith@example.gov.uk",
    "mobile_number": "+447700900123",
    "state": "active"
  }
}

Find Users by Email

POST /user/find-users-by-email Search for users by partial email match.

Request Body

{
  "email": "john.smith"
}

Response

{
  "data": [
    {
      "id": "user-uuid-1",
      "name": "John Smith",
      "email_address": "john.smith@example.gov.uk"
    },
    {
      "id": "user-uuid-2",
      "name": "John Smith Jr",
      "email_address": "john.smith.jr@example.gov.uk"
    }
  ]
}

Authentication & Security

Verify Password

POST /user/{user_id}/verify/password Verify a user’s password.

Request Body

{
  "password": "UserPassword123!"
}

Response

Status Code: 204 No Content if password is correct Status Code: 400 Bad Request if password is incorrect
{
  "result": "error",
  "message": {"password": ["Incorrect password"]}
}

Send 2FA Code (SMS)

POST /user/{user_id}/sms-code Send a two-factor authentication code via SMS.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "to": "+447700900123"
}

Response

Status Code: 204 No Content

Send 2FA Code (Email)

POST /user/{user_id}/email-code Send a two-factor authentication code via email.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "email_auth_link_host": "https://notify.gov.uk",
  "next": "/services"
}

Response

Status Code: 204 No Content

Verify 2FA Code

POST /user/{user_id}/verify/code Verify a two-factor authentication code.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "code": "123456",
  "code_type": "sms"
}

Response

Status Code: 204 No Content if code is valid Status Code: 400 Bad Request if code is expired or invalid Status Code: 404 Not Found if code not found

Complete WebAuthn Login

POST /user/{user_id}/complete/webauthn-login Complete login after WebAuthn authentication attempt.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "successful": true,
  "webauthn_credential_id": "credential-uuid"
}

Response

Status Code: 204 No Content

Reset Failed Login Count

POST /user/{user_id}/reset-failed-login-count Reset the failed login count for a user.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Response

{
  "data": {
    "id": "user-uuid",
    "failed_login_count": 0
  }
}

Password Management

Send Password Reset Email

POST /user/reset-password Send a password reset email to a user.

Request Body

{
  "email": "john.smith@example.gov.uk",
  "admin_base_url": "https://notify.gov.uk",
  "next": "/services"
}

Response

Status Code: 204 No Content

Update Password

POST /user/{user_id}/update-password Update a user’s password.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "_password": "NewSecurePassword123!"
}

Response

{
  "data": {
    "id": "user-uuid",
    "name": "John Smith"
  }
}

Email Verification

Send New User Email Verification

POST /user/{user_id}/email-verification Send an email verification link to a new user.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "admin_base_url": "https://notify.gov.uk"
}

Response

Status Code: 204 No Content

Send Email Change Verification

POST /user/{user_id}/change-email-verification Send a verification email when a user changes their email address.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "email": "new.email@example.gov.uk"
}

Response

Status Code: 204 No Content

Send Already Registered Email

POST /user/{user_id}/email-already-registered Send an email notifying that an email address is already registered.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Request Body

{
  "email": "existing@example.gov.uk"
}

Response

Status Code: 204 No Content

Service Permissions

Set User Permissions for Service

POST /user/{user_id}/service/{service_id}/permission Set a user’s permissions for a specific service.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID
service_iduuidThe service ID

Request Body

{
  "permissions": [
    {"permission": "send_messages"},
    {"permission": "manage_templates"},
    {"permission": "manage_users"}
  ],
  "folder_permissions": ["folder-uuid-1", "folder-uuid-2"]
}

Response

Status Code: 204 No Content

Set User Permissions for Organisation

POST /user/{user_id}/organisation/{organisation_id}/permissions Set a user’s permissions for an organisation.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID
organisation_iduuidThe organisation ID

Request Body

{
  "permissions": [
    {"permission": "manage_services"},
    {"permission": "view_all_services"}
  ]
}

Response

Status Code: 204 No Content

Get Organisations and Services

GET /user/{user_id}/organisations-and-services Get all organisations and services associated with a user.

Path Parameters

ParameterTypeDescription
user_iduuidThe user ID

Response

{
  "organisations": [
    {
      "id": "org-uuid",
      "name": "Cabinet Office",
      "count_of_live_services": 5
    }
  ],
  "services": [
    {
      "id": "service-uuid",
      "name": "My Service",
      "restricted": false,
      "organisation": "org-uuid"
    }
  ]
}

Available Permissions

Service permissions:
  • send_messages - Send notifications
  • manage_templates - Create and edit templates
  • manage_service - Update service settings
  • manage_api_keys - Create and revoke API keys
  • manage_users - Add and remove team members
  • view_activity - View notification history
Organisation permissions:
  • manage_services - Create and manage services
  • view_all_services - View all services in the organisation
  • manage_organisation - Update organisation settings
See also:

Build docs developers (and LLMs) love