From 0695e01d330bdfab89fe4eee70941f53cd05d5c3 Mon Sep 17 00:00:00 2001
From: joybytes <171517790+joybytes@users.noreply.github.com>
Date: Fri, 4 Sep 2026 13:15:56 +0100
Subject: [PATCH] feat: document personalisation on get template responses

---
 CHANGELOG.md                                       |  4 ++++
 integration_test/schemas/v2/template_schemas.py    |  7 +++++++
 notifications_python_client/__init__.py            |  2 +-
 .../test_notifications_api_client.py               | 14 ++++++++++++++
 4 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dbd41db..c9d7590 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 12.2.0
+
+* Document `personalisation` on template responses from `get_template`, `get_template_version` and `get_all_templates`. This is an object of placeholder names, for example `{"name": {"required": True}}`.
+
 ## 12.1.0
 
 * Adds `sanitise_content_for` parameter to `send_email_notification` endpoint. See [our documentation](https://docs.notifications.service.gov.uk/python.html#reducing-the-risk-of-malicious-content-injection-in-placeholders) for guidance on how to use this.
diff --git a/integration_test/schemas/v2/template_schemas.py b/integration_test/schemas/v2/template_schemas.py
index 7d8859b..bf9fd25 100644
--- a/integration_test/schemas/v2/template_schemas.py
+++ b/integration_test/schemas/v2/template_schemas.py
@@ -26,6 +26,13 @@
         "body": {"type": "string"},
         "subject": {"type": ["string", "null"]},
         "letter_contact_block": {"type": ["string", "null"]},
+        "personalisation": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "properties": {"required": {"type": "boolean"}},
+            },
+        },
     },
     "required": ["id", "type", "created_at", "updated_at", "version", "created_by", "body"],
 }
diff --git a/notifications_python_client/__init__.py b/notifications_python_client/__init__.py
index 0eb140e..2f49e68 100644
--- a/notifications_python_client/__init__.py
+++ b/notifications_python_client/__init__.py
@@ -7,7 +7,7 @@
 #
 # -- http://semver.org/
 
-__version__ = "12.1.0"
+__version__ = "12.2.0"
 
 from notifications_python_client.errors import (  # noqa
     REQUEST_ERROR_MESSAGE,
diff --git a/tests/notifications_python_client/test_notifications_api_client.py b/tests/notifications_python_client/test_notifications_api_client.py
index 740fbcf..8d015a9 100644
--- a/tests/notifications_python_client/test_notifications_api_client.py
+++ b/tests/notifications_python_client/test_notifications_api_client.py
@@ -400,6 +400,20 @@ def test_get_template(notifications_client, rmock):
     assert rmock.called
 
 
+def test_get_template_returns_personalisation(notifications_client, rmock):
+    endpoint = f"{TEST_HOST}/v2/template/{123}"
+    rmock.request(
+        "GET",
+        endpoint,
+        json={"id": "123", "personalisation": {"name": {"required": True}}},
+        status_code=200,
+    )
+
+    response = notifications_client.get_template(123)
+
+    assert response["personalisation"] == {"name": {"required": True}}
+
+
 def test_get_template_version(notifications_client, rmock):
     endpoint = f"{TEST_HOST}/v2/template/123/version/1"
     rmock.request("GET", endpoint, json={"status": "success"}, status_code=200)