Implementing the Personalization Engine - Postal Codes
- Last Modified:
- 16 Nov 2026
- User Level:
- Administrator
This is part 2 on our series of implementing the Personalization Engine.
In the previous part, we covered how to set up and manage the Geo dimension. This part covers how to use the Postal code dimension.
Overview
Being able to target content down to the postal code level can be very useful if you are running very targeted campaigns. However, it's important to understand that the postal code is derived from the visitor's IP (GeoIP), not GPS. This means it can be skewed by VPN/mobile/corporate networks, and unavailable in some countries. We recommend only using it for soft personalization, never precise targeting, and always provide a sensible fallback.
Important: Postal code based personalization is Terminalfour Cloud-only, and enabled per site: postal-code targeting is off by default. It's switched on per site by Terminalfour because resolving postal code can affect page caching. Request enablement through your Terminalfour account contact.
How postal code matching works
Set data-query="postalcode" (postal and zip are accepted aliases). Like geo, there are no cookies or triggers involved.
Example markup:
<div data-switcher data-query="postalcode">
<div data-variant="nyc-metro" data-codes="10001,10002,11201" hidden>NYC metro event</div>
<div data-variant="manhattan" data-codes="100*" hidden>Visit our New York campus</div>
<div data-variant="other" data-default>Find your nearest location</div>
</div>
As you can see in the example above, you can use wildcards and several postal codes together, so how does the Personalization Engine decide what to match?
A note on wildcards: wildcards can only be at the end of postal codes, not at the beginning.
Unlike geo, postal codes don't support groups or ! exclusions.
Matching rules
The engine matches in the following order:
-
exact matches beat a prefix match (e.g. a user visiting from 10001 will receive the variant "nyc-metro" and not "manhattan").
-
the longest prefix wins between two overlapping prefixes (e.g. a user visiting from 10003 will receive content with a data code of
1000*over100*) -
document order breaks any remaining tie (e.g. whichever is output higher in the page source will be matched first)
Postal codes aren't tied to a country. The engine only compares the postal code itself, so 10* intended for Berlin will also match New York zip codes like 10001. If you target postal codes in more than one country, consider using the which we'll cover later in the guide.
Examples:
| Country | Example data codes | Example Matches | Use case |
|---|---|---|---|
| US Zip |
|
10001 | Nearest campus; city pricing |
| UK |
|
SW1A | Region-specific open day banner |
| Canada |
|
M5V | Local stockist / event |
| Ireland |
|
D02 | City-level CTA |
| Germany |
|
10115 | Regional offer |
Setting it up
Each personalized region uses one dimension at a time, so we'll replace the geo element on the Homepage Hero Banner with a postal code element. If you only target a handful of postal codes, a List works well. For this example we'll use a plain text element instead, so editors can enter exactly the codes they need.
Edit the Homepage Hero Banner content type, remove the Personalization Country/Region element, and add this element in its place:
| Name | Description | Element Type | Size |
|---|---|---|---|
| Personalization Postal Code | Enter the postal codes this variant should be shown to, separated by commas. Add * to the end of a code to match every postal code starting with it (e.g. D02*). Enter DEFAULT for the fallback variant. |
Plain Text | 200 |
Note: Removing an element deletes any content already stored in it. If you have live geo-personalized content using this content type, consider creating a separate content type for postal codes instead.
Then update the text/personalized-hero content layout so data-codes outputs the new element:
data-codes="{{publish element="Personalization Postal Code"}}"
Finally, edit your Personalized Hero content, select "Postal Code" for the Personalize by field, and fill in the postal codes for each Hero Banner.
Testing your variants
To preview the page as a visitor from a specific postal code, add it to the URL in a query string, e.g. https://example.com?postalcode=10001. zip also works.
What's next?
We've covered Geo based personalization and now postal code based. Next we'll take a look at the behavioral targeting rules.
Back to top