These endpoints are used by the admin interface to manage templates. All endpoints require admin authentication.
Create Template
POST /service/{service_id}/template
Create a new template for a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Request Body
{
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"service": "service-uuid",
"created_by": "user-uuid",
"parent_folder_id": "folder-uuid",
"process_type": "normal"
}
Template Types
| Type | Description |
|---|
email | Email template |
sms | SMS template |
letter | Letter template |
Process Types
| Type | Description |
|---|
normal | Standard priority |
priority | High priority (faster delivery) |
bulk | Bulk sending (may be slower) |
Response
{
"data": {
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"version": 1,
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-01T00:00:00Z",
"created_by": {
"id": "user-uuid",
"name": "Admin User"
},
"service": "service-uuid",
"archived": false
}
}
201 Created
For letter templates, if no postage is specified, it defaults to second class.
Update Template
POST /service/{service_id}/template/{template_id}
Update an existing template. Each update creates a new version.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Request Body
{
"name": "Updated Welcome Email",
"subject": "Welcome to ((service_name)) - Updated",
"content": "Hi ((name)),\n\nWelcome! We've updated our message.",
"created_by": "user-uuid"
}
Response
{
"data": {
"id": "template-uuid",
"name": "Updated Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name)) - Updated",
"content": "Hi ((name)),\n\nWelcome! We've updated our message.",
"version": 2,
"updated_at": "2023-01-02T00:00:00Z"
}
}
Get All Templates for Service
GET /service/{service_id}/template
Retrieve all templates for a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"data": [
{
"id": "template-uuid-1",
"name": "Welcome Email",
"template_type": "email",
"version": 2,
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-02T00:00:00Z",
"archived": false
},
{
"id": "template-uuid-2",
"name": "Reminder SMS",
"template_type": "sms",
"version": 1,
"created_at": "2023-01-01T00:00:00Z",
"archived": false
}
]
}
Get Template by ID
GET /service/{service_id}/template/{template_id}
Retrieve a specific template (latest version).
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Response
{
"data": {
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"version": 2,
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-02T00:00:00Z",
"created_by": {
"id": "user-uuid",
"name": "Admin User"
},
"service": "service-uuid",
"archived": false,
"folder": "folder-uuid",
"redact_personalisation": false,
"postage": "second"
}
}
Preview Template
GET /service/{service_id}/template/{template_id}/preview
Preview a template with personalisation values.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Query Parameters
Provide personalisation values as query parameters:
?name=John&service_name=My Service
Response
{
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to My Service",
"content": "Hi John,\n\nWelcome to our service!",
"version": 2
}
Error Response
If required personalisation is missing:
{
"result": "error",
"message": {
"template": ["Missing personalisation: name, service_name"]
}
}
400 Bad Request
Get Template Version
GET /service/{service_id}/template/{template_id}/version/{version}
Retrieve a specific version of a template.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
version | integer | The version number |
Response
{
"data": {
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"version": 1,
"created_at": "2023-01-01T00:00:00Z"
}
}
Get All Template Versions
GET /service/{service_id}/template/{template_id}/versions
Retrieve all versions of a template.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Response
{
"data": [
{
"id": "template-uuid",
"name": "Updated Welcome Email",
"version": 2,
"created_at": "2023-01-02T00:00:00Z",
"created_by": "user-uuid"
},
{
"id": "template-uuid",
"name": "Welcome Email",
"version": 1,
"created_at": "2023-01-01T00:00:00Z",
"created_by": "user-uuid"
}
]
}
Archive Template
POST /service/{service_id}/template/{template_id}
Archive a template by setting the archived flag.
Request Body
{
"archived": true,
"created_by": "user-uuid"
}
Response
{
"data": {
"id": "template-uuid",
"archived": true,
"version": 3
}
}
Archiving a template also archives any associated email attachment files.
Redact Template
POST /service/{service_id}/template/{template_id}
Redact personalisation data from a template’s notification history.
Request Body
{
"redact_personalisation": true,
"created_by": "user-uuid"
}
Response
Status Code: 200 OK
Redacting a template prevents viewing personalisation data in sent notifications. This is useful for GDPR compliance.
Update Template Reply-To
POST /service/{service_id}/template/{template_id}
Update the reply-to address or letter contact for a template.
Request Body
For email templates:
{
"reply_to": "reply-to-email-uuid"
}
{
"reply_to": "letter-contact-uuid"
}
{
"reply_to": "sms-sender-uuid"
}
Response
{
"data": {
"id": "template-uuid",
"service_letter_contact_id": "letter-contact-uuid",
"version": 2
}
}
Get Precompiled Letter Template
GET /service/{service_id}/template/precompiled
Retrieve the precompiled letter template for a service. This is a special hidden template used for sending letters from PDF files.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"id": "template-uuid",
"name": "Pre-compiled PDF",
"template_type": "letter",
"hidden": true,
"is_precompiled_letter": true
}
Preview Letter Template from Notification
GET /service/{service_id}/template/preview/{notification_id}/{file_type}
Generate a preview of a sent letter notification.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
notification_id | uuid | The notification ID |
file_type | string | Either pdf or png |
Query Parameters
| Parameter | Type | Description |
|---|
page | integer | Page number for PNG previews |
Response
{
"content": "base64-encoded-file-content",
"metadata": {
"message": "content-outside-printable-area",
"invalid_pages": ["1", "3"]
}
}
Template Content Validation
SMS Templates
- Maximum length: Automatically calculated based on GSM-7 encoding
- Character limit: 918 characters (6 SMS segments)
- Personalisation fields count towards the limit
Email Templates
- Subject line: No strict limit but keep under 100 characters for deliverability
- Content: No strict limit
- Supports Markdown formatting
Letter Templates
- QR codes: Data must not exceed 500 characters
- Postage: Must be
first or second class
- Content must fit within printable area
Personalisation
Templates support personalisation using double parentheses:
Hi ((name)),
Your reference number is ((reference)).
{
"personalisation": {
"name": "John Smith",
"reference": "ABC123"
}
}