Person Field Mapping

This document explains how the CDP treats person profile fields when you send data via the Identify API or CSV upload. You can use common naming variations for core fields without renaming your data first.

---

Overview

The CDP has four core person fields: first name, last name, email, and phone. These are stored as first-class attributes and used for messaging, deduplication, and search.

We automatically recognize many common field name variations (e.g. firstName, first_name, First Name). Your payload can use any of the accepted names below; we normalize them internally. The same behavior applies to both:

• Data Gateway — POST /identify with a properties object
• CSV upload — column headers in your uploaded file

You do not need to change your existing column names or API payload keys to match a single convention.

---

Core Person Fields

Canonical field	Description
first_name	Person's first or given name
last_name	Person's last or family name
email	Email address (used for email channels and deduplication)
phone	Phone number; must be in E.164 format (see below)

All other fields you send are stored as custom attributes and are not normalized.

---

Accepted Field Names

You can send any of the following names for each core field. They are mapped to the canonical name shown.

First name → first_name

Accepted name
first_name
firstName
firstname
FirstName
First_Name
First Name
first name

Last name → last_name

Accepted name
last_name
lastName
lastname
LastName
Last_Name
Last Name
last name

Email → email

Accepted name
email
Email
email_address
emailAddress
EmailAddress
Email_Address
Email Address
email address

Phone → phone

Accepted name
phone
Phone
phone_number
phoneNumber
PhoneNumber
Phone_Number
Phone Number
phone number
mobile
Mobile
mobile_number
mobileNumber
Mobile_Number

---

Format Requirements

Email

• Stored value: The value is trimmed (leading/trailing spaces removed) and lowercased before storage.
• Invalid or empty emails are not rejected at ingestion; validation may be applied elsewhere (e.g. before sending email).

Phone (E.164 only)

• Stored value: Only E.164 phone numbers are stored in the core phone field.
• E.164 format: a + followed by the country code and subscriber number, with no spaces or other formatting (e.g. +2348055551212, +14155551234).
• If the value cannot be parsed into a valid E.164 number, it is not stored in phone. The raw value may still appear in custom attributes if you sent it under another key (e.g. mobile or phone_number).
• Valid examples: +2348055551212, +1 (555) 123-4567 (parsed to +15551234567 where valid).
• Invalid examples: not-a-phone, 123 (no country code), or numbers that fail validation — these will not be written to phone.

---

Priority Rules

If you send both a canonical name and an alias for the same concept in one payload, the canonical name wins.

• Example: { "email": "[email protected]", "email_address": "[email protected]" } → stored email is [email protected].
• Same rule applies for first_name / firstName, last_name / lastName, and phone / phone_number (or any other alias).

---

Custom Attributes

Any property or CSV column whose name is not in the accepted lists above is stored as a custom attribute on the person. These are not normalized or transformed; keys and values are stored as you send them. You can use them for segmentation, and personalization.

---

Integration Examples

Identify API (camelCase)

POST /identify
{
  "identifier": "user-123",
  "properties": {
    "firstName": "Jane",
    "lastName": "Doe",
    "emailAddress": "[email protected]",
    "phoneNumber": "+2348055551212",
    "company": "Acme"
  }
}

firstName, lastName, emailAddress, and phoneNumber are mapped to the core fields. company is stored as a custom attribute.

Identify API (snake_case)

POST /identify
{
  "identifier": "user-456",
  "properties": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "mobile": "+14155551234",
    "plan": "premium"
  }
}

mobile is mapped to phone (and must be valid E.164). plan is stored as a custom attribute.

CSV upload

Your CSV can use any of the accepted names as column headers. Example:

id	First Name	Last Name	email_address	mobile	segment
cust-001	Jane	Doe	[email protected]	+2348055551212	enterprise
cust-002	John	Smith	[email protected]	+14155551234	trial

• id is used as the person identifier (or your configured identifier column).
• First Name and Last Name map to first_name and last_name.
• email_address maps to email (and will be lowercased).
• mobile maps to phone (must be valid E.164).
• segment is stored as a custom attribute.

Same behavior applies whether you use firstName/lastName, first_name/last_name, or First Name/Last Name in the header row.