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"
}
}
201 Created
Get User by ID
GET /user/{user_id}
Retrieve a user’s details.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Response
Status Code: 204 No Content
Activate User
POST /user/{user_id}/activate
Activate a previously archived user account.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
service_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
organisation_id | uuid | The 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
| Parameter | Type | Description |
|---|
user_id | uuid | The 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 notificationsmanage_templates - Create and edit templatesmanage_service - Update service settingsmanage_api_keys - Create and revoke API keysmanage_users - Add and remove team membersview_activity - View notification history
Organisation permissions:
manage_services - Create and manage servicesview_all_services - View all services in the organisationmanage_organisation - Update organisation settings
See also: