Contact Properties

Every contact in Synapse has a set of standard fields and can also carry any number of custom properties. This page explains what data is stored on contacts and how it gets there.

Standard Fields

These fields are built into every contact record:

Field	Type	Description	Example
email	Text	The contact's email address	`[email protected]`
first_name	Text	First name	`Jane`
last_name	Text	Last name	`Doe`
phone	Text	Phone number	`+6591234567`
external_id	Text	Your application's user ID for this person	`app_user_12345`
product_type	Text	Product category or customer type	`Standard`, `Premium`
subscription_status	Text	Email subscription status	`subscribed`, `unsubscribed`, `complained`
created_at	Date	When the contact was first created in Synapse	`2026-03-15T10:30:00Z`
updated_at	Date	When the contact was last modified	`2026-04-01T08:00:00Z`

In addition to standard fields, contacts have a flexible properties field that can store any structured data. Custom properties come from the events your application sends and are stored as key-value pairs.

Examples

Property	Value	How It Got There
`country`	`SG`	Sent with a registration event
`language`	`en`	Sent with a profile update event
`plan`	`premium`	Sent with a subscription event
`onboarding_status`	`completed`	Set by a flow's Update Contact step
`last_campaign`	`spring_sale_2026`	Set by a flow's Update Contact step

Nested Properties

Custom properties can be nested. For example, a contact might have:

Property Path	Value
`address.city`	`Singapore`
`address.country`	`SG`
`preferences.language`	`en`
`preferences.timezone`	`Asia/Singapore`

In NLT templates, you access nested properties with dot notation:

`{the user's Address.City}`

`{the user's Preferences.Language}`

External ID Mapping

The external_id field connects a Synapse contact to a user in your application. This is typically your internal user ID.

How It Works

Your application sends an event with a user_id field (e.g., app_user_12345).
Synapse maps this to the contact's external_id.
All future events with the same user_id are linked to the same contact.

Why This Matters

It ensures all events for the same person are connected to one contact record.
It prevents duplicate contacts when the same user triggers multiple events.
It lets you look up a contact by their ID from your own system.

Note

The external ID must be unique per contact within your workspace. If two events arrive with different user IDs but the same email address, they will create two separate contacts. Use a consistent user ID from your application.

How Properties Are Updated

Contact properties are updated through two mechanisms:

1. Event Contact Overrides

When your application sends an event, it can include contact data updates:

If the event includes first_name, email, or other standard fields, those are updated on the contact.
If the event includes custom data, it's merged into the contact's properties.

New properties are added, existing properties are overwritten with new values, and properties not included in the event are left unchanged.

2. Flow Update Contact Steps

Flows can include Update Contact steps that set properties on the contact's record. For example, after a contact completes a welcome flow, you might set:

onboarding_status = completed
welcome_email_sent = true

These properties then become available for use in segments and templates.

Using Properties in Templates

All contact properties are available in NLT templates using the user's syntax:

`{the user's First Name}`

`{the user's Phone}`

`{the user's Properties.Country}`

`{the user's Product Type}`

See Variables for full details on accessing contact data in templates.

Using Properties in Segments

Contact properties (both standard and custom) can be used as segment filter criteria:

email contains @gmail.com -- contacts with Gmail addresses
product_type is Standard -- contacts on the Standard product
properties.country is SG -- contacts in Singapore
phone exists -- contacts who have a phone number

See Building Segments and Filter Operators for more details.

Tip

Think of contact properties as a living profile that grows richer over time. Every event and flow interaction can add or update data, making your templates and segments more precise.