Skip to main content

​
Overview

The Letter Branding API allows you to create, update, and retrieve letter branding configurations. Letter branding controls the visual appearance of letters sent through GOV.UK Notify, including letterheads and logos. Base URL: /letter-branding

​
Letter Branding Object

​
Properties

PropertyTypeDescription
idUUIDUnique identifier for the letter branding
namestringName of the letter branding (must be unique, max 255 chars)
filenamestringFilename for the branding template (must be unique, max 255 chars)
created_atdatetimeTimestamp when branding was created
created_byUUIDID of user who created the branding, nullable
updated_atdatetimeTimestamp of last update, nullable
updated_by_idUUIDID of user who last updated, nullable
Both name and filename must be unique across all letter brandings.

​
Endpoints

​
List Letter Brandings

Retrieve all available letter branding configurations. 
GET /letter-branding

​
Response

Status: 200 OK 
[
  {
    "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
    "name": "HM Revenue & Customs",
    "filename": "hmrc-letter-template",
    "created_at": "2024-01-10T08:30:00.000000Z",
    "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "updated_at": "2024-02-15T10:45:00.000000Z"
  },
  {
    "id": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
    "name": "Department for Transport",
    "filename": "dft-letter-template",
    "created_at": "2024-01-20T14:15:00.000000Z",
    "created_by": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e",
    "updated_at": null
  }
]

​
Get Letter Branding by ID

Retrieve a specific letter branding configuration. 
GET /letter-branding/{letter_branding_id}

​
Path Parameters

ParameterTypeDescription
letter_branding_idUUIDThe ID of the letter branding

​
Response

Status: 200 OK 
{
  "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
  "name": "HM Revenue & Customs",
  "filename": "hmrc-letter-template",
  "created_at": "2024-01-10T08:30:00.000000Z",
  "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "updated_at": "2024-02-15T10:45:00.000000Z"
}

​
Create Letter Branding

Create a new letter branding configuration. 
POST /letter-branding

​
Request Body

FieldTypeRequiredDescription
namestringYesUnique name for the letter branding
filenamestringYesUnique filename for the branding template
created_by_idUUIDNoID of user creating the branding

​
Example Request

{
  "name": "Home Office",
  "filename": "home-office-letter-template",
  "created_by_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

​
Response

Status: 201 Created 
{
  "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
  "name": "Home Office",
  "filename": "home-office-letter-template",
  "created_at": "2024-03-03T09:00:00.000000Z",
  "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "updated_at": null
}

​
Error Responses

Status: 400 Bad Request Duplicate name: 
{
  "result": "error",
  "message": {
    "name": ["Name already in use"]
  }
}
Duplicate filename: 
{
  "result": "error",
  "message": {
    "filename": ["Filename already in use"]
  }
}

​
Update Letter Branding

Update an existing letter branding configuration. 
POST /letter-branding/{letter_branding_id}

​
Path Parameters

ParameterTypeDescription
letter_branding_idUUIDThe ID of the letter branding to update

​
Request Body

FieldTypeRequiredDescription
namestringYesUpdated name for the letter branding
filenamestringYesUpdated filename for the branding template
updated_by_idUUIDNoID of user updating the branding
Both name and filename are required even when updating.

​
Example Request

{
  "name": "Home Office",
  "filename": "home-office-updated-template",
  "updated_by_id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e"
}

​
Response

Status: 201 Created 
{
  "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
  "name": "Home Office",
  "filename": "home-office-updated-template",
  "created_at": "2024-03-03T09:00:00.000000Z",
  "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "updated_at": "2024-03-03T11:20:00.000000Z"
}

​
Get Organizations and Services Using Branding

Retrieve all organizations and services associated with a specific letter branding. 
GET /letter-branding/{letter_branding_id}/orgs_and_services

​
Path Parameters

ParameterTypeDescription
letter_branding_idUUIDThe ID of the letter branding

​
Response

Status: 200 OK 
{
  "data": {
    "organisations": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "name": "HM Revenue & Customs",
        "active": true
      },
      {
        "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
        "name": "HMRC Operations",
        "active": true
      }
    ],
    "services": [
      {
        "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
        "name": "Tax Notifications",
        "active": true,
        "restricted": false
      }
    ]
  }
}

​
Get Unique Name

Generate a unique branding name. If the name already exists, returns an alternate name with a counter (e.g., “Name (alternate 1)”). 
POST /letter-branding/get-unique-name/

​
Request Body

FieldTypeRequiredDescription
namestringYesThe name to check for uniqueness

​
Example Request

{
  "name": "Department for Education"
}

​
Response

Status: 200 OK If name is available: 
{
  "name": "Department for Education"
}
If name exists, returns alternate: 
{
  "name": "Department for Education (alternate 3)"
}
The endpoint checks for existing brandings and automatically increments the alternate counter up to 99.

​
Code Examples

​
Python

import requests

base_url = "https://api.notifications.service.gov.uk"
headers = {"Authorization": f"Bearer {api_key}"}

# Create letter branding
response = requests.post(
    f"{base_url}/letter-branding",
    headers=headers,
    json={
        "name": "Foreign, Commonwealth & Development Office",
        "filename": "fcdo-letter-template",
        "created_by_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    }
)
branding = response.json()
print(f"Created branding: {branding['id']}")

# List all letter brandings
response = requests.get(f"{base_url}/letter-branding", headers=headers)
brandings = response.json()
for branding in brandings:
    print(f"{branding['name']}: {branding['filename']}")

# Get specific branding
branding_id = "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c"
response = requests.get(
    f"{base_url}/letter-branding/{branding_id}",
    headers=headers
)
branding = response.json()

# Update branding
response = requests.post(
    f"{base_url}/letter-branding/{branding_id}",
    headers=headers,
    json={
        "name": "Foreign, Commonwealth & Development Office",
        "filename": "fcdo-updated-template",
        "updated_by_id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e"
    }
)
updated = response.json()

# Get unique name for new branding
response = requests.post(
    f"{base_url}/letter-branding/get-unique-name/",
    headers=headers,
    json={"name": "Cabinet Office"}
)
unique_name = response.json()["name"]
print(f"Available name: {unique_name}")

​
cURL

# Create letter branding
curl -X POST "https://api.notifications.service.gov.uk/letter-branding" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Foreign, Commonwealth & Development Office",
    "filename": "fcdo-letter-template",
    "created_by_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'

# List all letter brandings
curl "https://api.notifications.service.gov.uk/letter-branding" \
  -H "Authorization: Bearer $API_KEY"

# Get specific branding
curl "https://api.notifications.service.gov.uk/letter-branding/5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c" \
  -H "Authorization: Bearer $API_KEY"

# Update branding
curl -X POST "https://api.notifications.service.gov.uk/letter-branding/5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Foreign, Commonwealth & Development Office",
    "filename": "fcdo-updated-template",
    "updated_by_id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e"
  }'

# Get unique name
curl -X POST "https://api.notifications.service.gov.uk/letter-branding/get-unique-name/" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Cabinet Office"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us