Hashing PII for Upload

All personally identifiable information (PII) uploaded to Narrative must be pseudonymized using cryptographic hash functions. This guide walks you through formatting and hashing email addresses and phone numbers before uploading them to the platform.

To understand why Narrative requires hashed identifiers rather than raw PII, see Data Pseudonymization.

Prerequisites

Before you begin, ensure you have:

Your ID list saved as a single-column CSV file
Access to one of the following: Google Sheets, a command line terminal, or the Touchless PII Hasher app

Choose your method

Method	Best for	Requirements
Touchless PII Hasher	Quick, one-off hashing	Web browser only
Google Sheets	Small lists (under 10,000 rows)	Google account
Command line	Large lists, automation	Terminal access

Hashing email addresses

Pre-formatting requirements

Hash functions are case-sensitive and whitespace-sensitive. Before hashing, you must normalize your email addresses:

Rule	Example	Result
Lowercase all text	`[email protected]`	`[email protected]`
Remove leading/trailing whitespace	`[email protected]`	`[email protected]`
Gmail only: remove `+` aliases and everything after	`[email protected]`	`[email protected]`
Gmail only: remove periods in the username	`[email protected]`	`[email protected]`

The Gmail rules apply to gmail.com and googlemail.com addresses only. Leave periods and + aliases in every other address. This matches NORMALIZE_EMAIL.

Skipping pre-formatting will result in different hash values, preventing matches with other datasets. A single extra space or uppercase letter produces a completely different hash.

Supported hash algorithms

Narrative supports three hash algorithms. For maximum correspondence with other datasets, we recommend generating all three:

Algorithm	Output length	Example hash of `[email protected]`
MD5	32 characters	`29a1df4646cb3417c19994a59a3e022a`
SHA-1	40 characters	`e1e8d3e4a336d4f9dc63b70a534ff10834471556`
SHA-256	64 characters	`06a240d11cc201676da976f7b49341181fd180da37cbe40a77432c0a366c80c3`

Method 1: Touchless PII Hasher (fastest)

The Touchless PII Hasher is a free web app that handles formatting and hashing automatically. Your data never leaves your browser.

Open the app

Navigate to narrative.io/touchless-pii-hasher.

Upload your file

Drag and drop your CSV file or click to browse.

Download the results

The app automatically formats and hashes your data. Download the resulting file.

Method 2: Google Sheets (small lists)

For lists under 10,000 rows, use Narrative’s Hashing Functions spreadsheet which automatically handles pre-formatting and all three hash algorithms.

Make a copy of the template

Open the Hashing Functions spreadsheet and click Make a copy when prompted.

Paste your email list

Copy your list of emails and paste them starting in cell A4.

Wait for processing

The spreadsheet may take a few minutes to compute, depending on list size.

Download the results

Navigate to the tab titled DOWNLOAD_THIS_SHEET_AS_.CSV_FILE. Go to File > Download > Comma-separated values (.csv, current sheet).

Method 3: Command line (large lists)

For large lists or automation, use the command line. Narrative provides a hashing script, or you can use standard Unix tools.

Mac/Linux
Windows (PowerShell)

Option A: Use Narrative’s hashing script

Download the script

Download hashingFunction.py and save it to your ~/bin directory.

Make it executable

chmod +x ~/bin/hashingFunction.py

Run the script

~/bin/hashingFunction.py < input.csv > output.csv

Option B: Use standard Unix toolsFor a quick one-liner that handles pre-formatting and generates SHA-256 hashes:

cat emails.csv | tr '[:upper:]' '[:lower:]' | sed 's/+[^@]*//g' | \
  while read email; do echo -n "$email" | shasum -a 256 | cut -d' ' -f1; done > hashed.csv

To generate all three hash formats:

cat emails.csv | tr '[:upper:]' '[:lower:]' | sed 's/+[^@]*//g' | \
  while read email; do
    echo "$(echo -n "$email" | md5),$(echo -n "$email" | shasum -a 1 | cut -d' ' -f1),$(echo -n "$email" | shasum -a 256 | cut -d' ' -f1)"
  done > hashed.csv

Use PowerShell to hash your email list:

Get-Content emails.csv | ForEach-Object {
    $email = $_.Trim().ToLower() -replace '\+[^@]*', ''
    $bytes = [System.Text.Encoding]::UTF8.GetBytes($email)

    $md5 = [System.Security.Cryptography.MD5]::Create()
    $sha1 = [System.Security.Cryptography.SHA1]::Create()
    $sha256 = [System.Security.Cryptography.SHA256]::Create()

    $md5Hash = [BitConverter]::ToString($md5.ComputeHash($bytes)) -replace '-', ''
    $sha1Hash = [BitConverter]::ToString($sha1.ComputeHash($bytes)) -replace '-', ''
    $sha256Hash = [BitConverter]::ToString($sha256.ComputeHash($bytes)) -replace '-', ''

    "$sha256Hash,$md5Hash,$sha1Hash".ToLower()
} | Out-File -Encoding UTF8 hashed.csv

Never direct output to the same file as input. This will delete your data:

# DO NOT DO THIS
hashingFunction.py < emails.csv > emails.csv  # Data will be lost!

Hashing phone numbers

Phone numbers follow a similar process, but with different pre-formatting rules. Narrative matches phone numbers by SHA-256 only, and which attribute a hash matches depends on exactly what you hashed.

Pre-formatting requirements

Write every number in E.164 format: a +, the country code, then the national number, with nothing else.

Rule	Example	Result
Add the country code to a national number	`(555) 123-4567` (US)	`+15551234567`
Drop a national trunk prefix	`07700 900013` (UK)	`+447700900013`
Remove spaces, dashes, parentheses and extensions	`+1 555 123 4567 x39`	`+15551234567`

A leading 0 is a trunk prefix, not part of the number, and the country can’t be told from the number alone. Convert national numbers with the country they belong to; don’t guess it.

Which attribute your hash matches

You hash	Example input	Map the hash as
The E.164 number, with the `+`	`+15551234567`	`sha256_hashed_phone_number`
The E.164 number without the `+`	`15551234567`	`sha256_hashed_msisdn`
The 10-digit national number of a `+1` number	`5551234567`	`sha256_hashed_phone_number_nsn`

Hash the E.164 number with the + unless your partner expects one of the other forms. If your numbers are already in Narrative as plain text, you don’t need to hash them: map the column to telephone_number, and Narrative derives all three hashes for numbers written with a +. NQL’s NORMALIZE_PHONE converts national numbers when you know their country.

Using Google Sheets for phone numbers

Use Narrative’s Phone Hashing Functions spreadsheet. It strips every non-numeric character, the + included, so its SHA-256 hashes are MSISDN hashes: map them as sha256_hashed_msisdn. Follow the same steps as email hashing above.

Using command line for phone numbers

These commands expect numbers that already carry their country code. They keep the + and the digits, drop everything else, and output the SHA-256 hash.

Mac/Linux
Windows (PowerShell)

cat phones.csv | tr -cd '0-9+\n' | \
  while read phone; do
    echo "$(echo -n "$phone" | shasum -a 256 | cut -d' ' -f1)"
  done > hashed_phones.csv

Get-Content phones.csv | ForEach-Object {
    $phone = $_ -replace '[^0-9+]', ''
    $bytes = [System.Text.Encoding]::UTF8.GetBytes($phone)

    $sha256 = [System.Security.Cryptography.SHA256]::Create()
    $sha256Hash = [BitConverter]::ToString($sha256.ComputeHash($bytes)) -replace '-', ''

    $sha256Hash.ToLower()
} | Out-File -Encoding UTF8 hashed_phones.csv

Verify your output

Before uploading, verify your hashing is correct using this test data: Test email: [email protected]

Algorithm	Expected hash
SHA-256	`06a240d11cc201676da976f7b49341181fd180da37cbe40a77432c0a366c80c3`
MD5	`29a1df4646cb3417c19994a59a3e022a`
SHA-1	`e1e8d3e4a336d4f9dc63b70a534ff10834471556`

Test phone number: +15551234567

Form	Expected SHA-256 hash
With the `+` (`sha256_hashed_phone_number`)	`8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4`
Without the `+` (`sha256_hashed_msisdn`)	`d6736136ea896c1bfdc553e0e86e702c70d060d805696ca3e4e9e0961353860a`

If your hashes match, your implementation is correct.

Uploading your hashed list

Once your list is hashed:

Ensure your file is in CSV format
Navigate to your dataset in Narrative
Upload the hashed file

Troubleshooting

Issue	Cause	Solution
Hashes don’t match expected values	Pre-formatting not applied	Verify lowercase, whitespace removal, and alias stripping
Google Sheets is slow or unresponsive	List too large	Use command line method for lists over 10,000 rows
Different hashes for same email	Inconsistent formatting	Ensure all emails go through the same pre-formatting pipeline
Command not found (Mac/Linux)	Script not in PATH	Use full path to script or add `~/bin` to PATH
PowerShell security error	Execution policy	Run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`

Data Pseudonymization

Understand why Narrative requires hashed identifiers

Touchless PII Hasher

Free web app for quick, secure hashing

Security Model

Learn how Narrative protects your data

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

Choose your method

Hashing email addresses

Pre-formatting requirements

Supported hash algorithms

Method 1: Touchless PII Hasher (fastest)

Method 2: Google Sheets (small lists)

Method 3: Command line (large lists)

Hashing phone numbers

Pre-formatting requirements

Which attribute your hash matches

Using Google Sheets for phone numbers

Using command line for phone numbers

Verify your output

Uploading your hashed list

Troubleshooting

Data Pseudonymization

Touchless PII Hasher

Security Model

​Prerequisites

​Choose your method

​Hashing email addresses

​Pre-formatting requirements

​Supported hash algorithms

​Method 1: Touchless PII Hasher (fastest)

​Method 2: Google Sheets (small lists)

​Method 3: Command line (large lists)

​Hashing phone numbers

​Pre-formatting requirements

​Which attribute your hash matches

​Using Google Sheets for phone numbers

​Using command line for phone numbers

​Verify your output

​Uploading your hashed list

​Troubleshooting

​Related content

Data Pseudonymization

Touchless PII Hasher

Security Model

Prerequisites

Choose your method

Hashing email addresses

Pre-formatting requirements

Supported hash algorithms

Method 1: Touchless PII Hasher (fastest)

Method 2: Google Sheets (small lists)

Method 3: Command line (large lists)

Hashing phone numbers

Pre-formatting requirements

Which attribute your hash matches

Using Google Sheets for phone numbers

Using command line for phone numbers

Verify your output

Uploading your hashed list

Troubleshooting

Related content