Send an SMS notification to a phone number.
Request Body
The phone number to send the SMS to. Must be a valid phone number.
The UUID of the SMS template to use.
Key-value pairs to fill in placeholders in the template. Values must be strings or dictionaries (for file uploads).
A unique identifier for this notification that you can use to identify it later. Maximum 1,000 characters.
The UUID of a specific SMS sender to use. If not provided, the default sender for the template will be used.
An ISO 8601 formatted datetime string to schedule the notification for sending. Must be within the next 24 hours. Set to null to send immediately.
Response
The unique identifier for this notification.
The reference you provided, or null if you did not provide one.
The content of the SMS notification.The SMS message body with placeholders filled in.
The phone number the SMS will be sent from.
The URI to retrieve this notification.
Information about the template used.The UUID of the template.
The version number of the template.
The URI to retrieve the template.
The datetime the notification is scheduled for, or null if sending immediately.
Example Request
curl -X POST https://api.notifications.service.gov.uk/v2/notifications/sms \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+447700900123",
"template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
"personalisation": {
"name": "John Smith",
"appointment_date": "12 March 2024"
},
"reference": "appointment-reminder-123"
}'
Example Response
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": "appointment-reminder-123",
"content": {
"body": "Hello John Smith, your appointment is on 12 March 2024.",
"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/services/8b3aa916-e138-4d4b-8c96-da8b6ddfe9a2/templates/f33517ff-2a88-4f6e-b855-c550268ce08a"
},
"scheduled_for": null
}
Error Responses
400 Bad Request
Invalid phone number
{
"status_code": 400,
"errors": [
{
"error": "InvalidPhoneError",
"message": "Not a valid phone number"
}
]
}
{
"status_code": 400,
"errors": [
{
"error": "ValidationError",
"message": "phone_number is a required property"
}
]
}
{
"status_code": 400,
"errors": [
{
"error": "BadRequestError",
"message": "Content for template has a character count greater than the limit of 918"
}
]
}
403 Forbidden
Service does not have permission to send SMS
{
"status_code": 403,
"errors": [
{
"error": "BadRequestError",
"message": "Service is not allowed to send sms"
}
]
}
404 Not Found
Template not found
{
"status_code": 404,
"errors": [
{
"error": "NoResultFound",
"message": "No result found"
}
]
}
429 Too Many Requests
Rate limit exceeded
{
"status_code": 429,
"errors": [
{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type LIVE of 3000 requests per 60 seconds"
}
]
}
{
"status_code": 429,
"errors": [
{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (daily: 1000) for today"
}
]
}