Skip to main content
The GOV.UK Notify API is a RESTful API for sending SMS, email, and letter notifications at scale. The API is designed for government services but follows standard REST conventions.

​
Base URLs

The API has two main components:

Public API

/v2/* endpoints for sending notifications and managing templates

Internal API

Internal endpoints for service management (admin app only)

​
API Versions

​
Version 2 (Current)

All public API endpoints are under the /v2 prefix:
  • Notifications: /v2/notifications/{type}
  • Templates: /v2/template/{id} and /v2/templates
  • Inbound SMS: /v2/received-text-messages
Version 1 endpoints are deprecated and internal-only. All new integrations should use v2 endpoints.

​
API Characteristics

​
RESTful Design

  • Standard HTTP methods: GET, POST, DELETE
  • JSON request and response bodies
  • HTTP status codes for success and error indication
  • Resource-based URL structure

​
Authentication

All API requests require JWT authentication in the Authorization header: 
Authorization: Bearer <JWT_TOKEN>
See Authentication for details on generating JWT tokens.

​
Content Type

All requests and responses use JSON: 
Content-Type: application/json

​
Response Format

​
Success Responses

Successful responses return the appropriate HTTP status code:
  • 200 OK - Successful GET request
  • 201 Created - Successful POST request that creates a resource
  • 204 No Content - Successful DELETE request
Example success response
{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "your-reference",
  "content": {
    "body": "Hello John Smith",
    "from_number": "GOVUK"
  },
  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

​
Error Responses

Error responses include:
  • Status code - HTTP error code
  • Errors array - List of error objects with details
Example error response
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "phone_number is a required property"
    }
  ]
}

​
Common HTTP Status Codes

CodeMeaningDescription
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenService lacks required permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
504Gateway TimeoutRequest timed out

​
Error Types

Common error types returned by the API:
Request validation failed. Check the message field for specific validation errors.Common causes:
  • Missing required fields
  • Invalid field formats
  • Invalid enum values
Phone number format is invalid.Common causes:
  • Phone number not in E.164 format
  • Invalid country code
  • Landline number for SMS
Email address format is invalid.
Authentication failed.Common causes:
  • Missing Authorization header
  • Invalid JWT token
  • Expired token
  • Clock skew (token time > 30 seconds from server time)
API rate limit exceeded.Common causes:
  • Too many requests per minute
  • Exceeded daily message limit
Generic request error.Common causes:
  • Invalid template ID
  • Service lacks permission for notification type
  • Recipient not allowed in trial mode

​
Client Libraries

Official client libraries are available for common programming languages:

Python

pip install notifications-python-client

Ruby

gem install notifications-ruby-client

Java

Maven/Gradle dependency

Node.js

npm install notifications-node-client
See Client Libraries for installation and usage guides.

​
Rate Limits

The API enforces rate limits to ensure fair usage:
  • Per-minute limit: Based on service configuration (default varies by key type)
  • Daily limits: Separate limits for SMS, email, and letters
See Rate Limits for detailed information.

​
Next Steps

Authentication

Learn how to authenticate API requests

Send a notification

Start sending notifications

Rate limits

Understand rate limiting

Client libraries

Use official client libraries

Build docs developers (and LLMs) love

Get started for freeTalk to us