Preview a template

POST /v2/template/{id}/preview

Preview a template

cURL

curl --request POST \
  --url https://api.example.com/v2/template/{id}/preview \
  --header 'Content-Type: application/json' \
  --data '
{
  "personalisation": {}
}
'

200

{
  "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

With personalisation

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"
    }
  ]
}