Skip to main content
POST
/
v2
/
template
/
{id}
/
preview
Preview a template
curl --request POST \
  --url https://api.example.com/v2/template/{id}/preview \
  --header 'Content-Type: application/json' \
  --data '
{
  "personalisation": {}
}
'
{
  "id": "<string>",
  "type": "<string>",
  "version": 123,
  "body": "<string>",
  "subject": "<string>",
  "html": "<string>",
  "postage": "<string>",
  "status_code": 123,
  "errors": [
    {}
  ]
}
Generates a preview of a template with personalisation data filled in. This allows you to see what the final message will look like before sending it.

​
Path Parameters

​
id
string
required
The UUID of the template to preview

​
Request Body

​
personalisation
object
Key-value pairs for filling in template placeholders. The keys must match the placeholder names in your template.If your template has no placeholders, you can send an empty request body.

​
Authentication

Requires an API key with appropriate service permissions.

​
Response

​
id
string
The UUID of the template
​
type
string
The type of template. One of:
  • sms - SMS message template
  • email - Email template
  • letter - Letter template
​
version
integer
The version number of the template
​
body
string
The template content with personalisation values filled in
​
subject
string
The subject line with personalisation values filled in (for email templates only)
​
html
string
The HTML version of the email body with personalisation values filled in (for email templates only)
​
postage
string
The postage class for letter templates. One of:
  • first - First class
  • second - Second class
  • economy - Economy class
  • europe - Europe
  • rest-of-world - Rest of world

​
Example Requests

curl -X POST "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a/preview" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "personalisation": {
      "name": "John Smith",
      "reference": "REF-12345"
    }
  }'

​
Example Responses

​
Email template

{
  "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
  "type": "email",
  "version": 3,
  "body": "Hello John Smith,\n\nYour reference number is REF-12345.",
  "subject": "Your application has been received",
  "html": "<p>Hello John Smith,</p><p>Your reference number is REF-12345.</p>",
  "postage": null
}

​
SMS template

{
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "type": "sms",
  "version": 1,
  "body": "Your security code is 123456. Do not share this code.",
  "subject": null,
  "html": null,
  "postage": null
}

​
Letter template

{
  "id": "b2c3d4e5-f6a7-4b6c-9d0e-1f2a3b4c5d6e",
  "type": "letter",
  "version": 2,
  "body": "Dear Sarah Jones,\n\nThis is to confirm your appointment on 15 March 2024.",
  "subject": null,
  "html": null,
  "postage": "second"
}

​
Error Responses

​
status_code
integer
HTTP status code
​
errors
array
Array of error objects describing what went wrong

​
400 Bad Request - Invalid UUID

Returned when the template ID is not a valid UUID. 
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "id is not a valid UUID"
    }
  ]
}

​
400 Bad Request - Missing personalisation

Returned when required personalisation fields are missing. 
{
  "status_code": 400,
  "errors": [
    {
      "error": "BadRequestError",
      "message": "Missing personalisation: name, reference"
    }
  ]
}

​
400 Bad Request - Invalid JSON

Returned when the request body is not valid JSON. 
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "Invalid JSON"
    }
  ]
}

​
403 Forbidden

Returned when the API key doesn’t have permission to access the template. 
{
  "status_code": 403,
  "errors": [
    {
      "error": "AuthError",
      "message": "Invalid token: service not found"
    }
  ]
}

​
404 Not Found

Returned when the template doesn’t exist. 
{
  "status_code": 404,
  "errors": [
    {
      "error": "NoResultFound",
      "message": "No result found"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us