Writing a message

Personalisation

Placing personalisation fields in your template

You can send personalised messages by adding personalisation fields to a single template.

Use double brackets to add a personalisation field to your template. Do not include spaces in your personalisation fields. For example:

You can read personalisation instructions while you’re editing a template.

You can use Personal Demographics Service (PDS) personalisation fields and custom personalisation fields in the same template.

PDS personalisation fields (automatic data)

NHS Notify uses the Personal Demographics Service (PDS) (opens in a new tab) to populate the personalisation fields in your template. This happens when you tell us who you want to message using recipients’ NHS numbers.

You can use the following PDS fields:

• fullName
• firstName
• lastName
• nhsNumber
• date

Custom personalisation fields (your data)

Use custom personalisation fields when you want to provide your own data that is not available through PDS.

Sending custom personalisation data in your request

When you go live, you can provide the data for your custom personalisation fields in your API or MESH request.

If you use NHS Notify API

Include a personalisation block for each message in your API request.

For example, if you wanted to include ((gpSurgery)) and ((appointmentDate)) as custom personalisation fields, the personalisation block for one message would be:

personalisation: {
"gpSurgery": "The Health Centre, Knaresborough Road",
"appointmentDate": "15 January 2027"
}

Read the API documentation (opens in a new tab) to find out where to put this in your request.

If you use NHS Notify MESH

Include the custom personalisation fields as column headings in the CSV file you use in your request. Put the personalisation data for each message in the rows underneath, with one row per message.

The column heading should start with personalisation_ followed by the same wording as the personalisation field in your template.

For example, if your personalisation fields were ((gpSurgery)) and ((appointmentDate)), the column headings would be:

• personalisation_gpSurgery
• personalisation_appointmentDate

The CSV file you use in your MESH request is different to the CSV example data file for custom personalisation fields.

Read more about how to create your request with NHS Notify MESH (opens in a new tab).

Providing example personalisation data

You must provide example data if you use custom personalisation. This means you can check how your templates will look during proofing, as the data in personalisation fields can affect message cost and length.

You do not need to do this if you only use PDS fields in your template.

Download and fill in the example data file. You can also download a completed example file to check how to format your data.

For each personalisation field, provide short, medium and long examples. For example, if your personalisation field was ((gpSurgery)), you could use the following example data:

Follow these rules for your example data:

• the personalisation fields in your template must exactly match the fields in the ‘personalisation field’ column of your spreadsheet
• decide the number of characters for your short, medium and long examples - there are no set lengths
• if a field is always a fixed length, such as a phone number, provide 3 different examples of that fixed length
• your example data does not need to be real user data

Adding personalised links

To add personalised links and URLs, include personalisation fields for both the link text and the URL in your template. For example:

Fields to avoid for custom personalisation

If you use custom personalisation, do not use the following personalisation fields:

• any PDS personalisation fields
• emailAddress
• phoneNumber
• addressLine1 to addressLine7
• middleNames
• namePrefix
• nameSuffix
• date
• clientRef
• recipientContactValue
• template

You can include extra words in your custom personalisation fields to make them different to the fields to avoid. For example, if you wanted to include GP surgery phone number, your personalisation field could be: