Custom Fields

Custom fields are custom key-value pairs attached to contacts. Use them to organize contacts, track metadata, and build targeted audiences.

What Are Custom Fields?

Custom fields are flexible metadata you define. Each custom field has:

Key: The custom field name (e.g., source, tier, cohort)
Value: The custom field value (e.g., facebook, gold, january2024)

Contact: +14155551234
Custom Fields:
  source: facebook
  campaign: summer_promo
  tier: gold
  cohort: 2024-01

Custom fields are per-list — they are stored on the contact’s membership of a given sending list, so the same phone number can have different values on different lists.

Common Custom Field Patterns

Acquisition Source

Track where contacts came from:

Key	Example Values
`source`	facebook, google, organic, referral
`campaign`	summer2024, black_friday, launch
`landing_page`	/promo, /signup, /offer
`ad_set`	lookalike_1, interest_targeting

Contact Segmentation

Categorize contacts by behavior or value:

Key	Example Values
`tier`	gold, silver, bronze
`engagement`	high, medium, low
`buyer_status`	purchased, browsed, new
`ltv_bucket`	0-50, 50-200, 200+

Temporal Data

Track time-based information:

Key	Example Values
`cohort`	2024-01, 2024-Q1, week_12
`signup_date`	2024-01-15
`last_purchase`	2024-03-20

Custom Attributes

Store any relevant metadata:

Key	Example Values
`state`	CA, NY, TX
`language`	en, es, fr
`interest`	fitness, tech, fashion
`age_range`	18-24, 25-34, 35-44

Adding Custom Fields

During Import

Include custom fields in the custom_fields object when creating contacts via the API:

{
  "phone_number": "+14155551234",
  "custom_fields": {
    "source": "facebook",
    "campaign": "summer2024",
    "tier": "gold"
  }
}

Via API

Include custom fields when creating contacts:

curl -X POST https://api.tracklysms.com/api/v2/contacts \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "list_number": "+18005551234",
    "custom_fields": {
      "source": "api",
      "campaign": "onboarding"
    }
  }'

In Dashboard

Go to Reports > Contact Lookup
Under Browse Lists, select the list and click the contact’s row to open its details
On that list’s card under List Memberships, click Edit Fields
Edit the JSON in the Edit Custom Fields dialog, then click Save Changes

Using Custom Fields in Audiences

Custom fields are the primary way to segment contacts into audiences. Use them in audience conditions:

Basic Condition

custom_field:source = facebook

Matches contacts with source custom field equal to facebook.

Multiple Values

custom_field:tier IN [gold, silver]

Matches contacts with tier custom field of either gold or silver.

Existence Check

custom_field:vip EXISTS

Matches contacts that have any value for the vip custom field.

Negation

custom_field:churned NOT EXISTS

Matches contacts that don’t have the churned custom field.

Numeric Comparison

custom_field:age >= 25
custom_field:lifetime_value > 100

Numeric custom fields support gt, gte, lt, lte operators in addition to eq and ne.

All Available Operators

Operator	Description	Example
`eq`	Equal to	`source = facebook`
`ne`	Not equal to	`tier != free`
`in`	Matches any value	`tier IN [gold, silver]`
`not_in`	Matches none	`tier NOT IN [churned, cancelled]`
`contains`	Substring match	`source contains "fb"`
`gt`	Greater than	`age > 25`
`gte`	Greater than or equal	`spend >= 100`
`lt`	Less than	`age < 65`
`lte`	Less than or equal	`spend <= 50`
`exists`	Field is present (an explicit null value counts as present)	`vip EXISTS`
`not_exists`	Field is missing (an explicit null value still counts as present)	`churned NOT EXISTS`

Custom Field Best Practices

Use consistent naming

Establish naming conventions and stick to them:

Use lowercase: source not Source
Use underscores: sign_up_date not sign-up-date
Be specific: acquisition_source not src

Keep values normalized

Use consistent values across imports:

facebook not sometimes Facebook or FB
2024-01-15 not Jan 15, 2024 or 1/15/24

Don't over-use custom fields

Add custom fields you’ll actually use for targeting. Too many custom fields create noise.

Document your custom fields

Maintain a reference of what custom fields you use and what values are valid. Share with your team.

Use custom fields for audience exclusions

Custom fields like churned, complained, high_risk help you exclude contacts from sends.

Viewing Custom Field Usage

To see all custom fields in use across your contacts:

Go to Audiences > New Audience
Click Add Condition > Custom Field
The dropdown shows all existing custom field keys
Select a key to see its values

This helps you understand what custom fields exist in your data.

Example: Full Segmentation Strategy

Here’s an example custom field strategy for an e-commerce brand:

Acquisition:
  source: facebook | google | organic | email | referral
  campaign: (campaign name)
  cohort: 2024-Q1 | 2024-Q2 | ...

Behavior:
  buyer_status: never | once | repeat
  last_purchase_days: 7 | 30 | 90 | 180
  engagement_level: high | medium | low

Value:
  ltv_tier: vip | standard | new
  aov_bucket: low | medium | high

Preferences:
  category_interest: electronics | fashion | home
  promo_responsive: true | false

This enables audiences like:

VIP Winback: ltv_tier=vip AND last_purchase_days=90
New High Engagers: cohort=2024-Q1 AND engagement_level=high AND buyer_status=never
Promo Candidates: promo_responsive=true AND buyer_status=once

Next Steps

Building Audiences

Use custom fields for targeting

Segmentation Logic

Combine custom field conditions

Import Contacts

Add custom fields during import

Getting Started

AI Agents & MCP

Guides

Account & Team

Integrations

Resources

What Are Custom Fields?

Common Custom Field Patterns

Acquisition Source

Contact Segmentation

Temporal Data

Custom Attributes

Adding Custom Fields

During Import

Via API

In Dashboard

Using Custom Fields in Audiences

Basic Condition

Multiple Values

Existence Check

Negation

Numeric Comparison

All Available Operators

Custom Field Best Practices

Viewing Custom Field Usage

Example: Full Segmentation Strategy

Next Steps

Building Audiences

Segmentation Logic

Import Contacts

​What Are Custom Fields?

​Common Custom Field Patterns

​Acquisition Source

​Contact Segmentation

​Temporal Data

​Custom Attributes

​Adding Custom Fields

​During Import

​Via API

​In Dashboard

​Using Custom Fields in Audiences

​Basic Condition

​Multiple Values

​Existence Check

​Negation

​Numeric Comparison

​All Available Operators

​Custom Field Best Practices

​Viewing Custom Field Usage

​Example: Full Segmentation Strategy

​Next Steps

Building Audiences

Segmentation Logic

Import Contacts

What Are Custom Fields?

Common Custom Field Patterns

Acquisition Source

Contact Segmentation

Temporal Data

Custom Attributes

Adding Custom Fields

During Import

Via API

In Dashboard

Using Custom Fields in Audiences

Basic Condition

Multiple Values

Existence Check

Negation

Numeric Comparison

All Available Operators

Custom Field Best Practices

Viewing Custom Field Usage

Example: Full Segmentation Strategy

Next Steps