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 ListContact (the relationship between a contact and a sending list), not on the Contact itself. This means the same phone number can have different custom field 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 Sending Lists > select list > Contacts
Click on a contact
Click Edit Custom Fields
Add or modify custom fields
Click Save

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`	Has any value	`vip EXISTS`
`not_exists`	Is null or missing	`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.

Bulk Custom Field Updates

Coming Soon — Bulk custom field updates via audiences are not yet available. Currently, custom fields can be set via the API when creating or updating contacts.

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

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

Bulk Custom Field Updates

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

​Bulk Custom Field Updates

​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

Bulk Custom Field Updates

Viewing Custom Field Usage

Example: Full Segmentation Strategy

Next Steps