Skip to main content
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:
KeyExample Values
sourcefacebook, google, organic, referral
campaignsummer2024, black_friday, launch
landing_page/promo, /signup, /offer
ad_setlookalike_1, interest_targeting

​
Contact Segmentation

Categorize contacts by behavior or value:
KeyExample Values
tiergold, silver, bronze
engagementhigh, medium, low
buyer_statuspurchased, browsed, new
ltv_bucket0-50, 50-200, 200+

​
Temporal Data

Track time-based information:
KeyExample Values
cohort2024-01, 2024-Q1, week_12
signup_date2024-01-15
last_purchase2024-03-20

​
Custom Attributes

Store any relevant metadata:
KeyExample Values
stateCA, NY, TX
languageen, es, fr
interestfitness, tech, fashion
age_range18-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://app.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

  1. Go to Sending Lists > select list > Contacts
  2. Click on a contact
  3. Click Edit Custom Fields
  4. Add or modify custom fields
  5. 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

OperatorDescriptionExample
eqEqual tosource = facebook
neNot equal totier != free
inMatches any valuetier IN [gold, silver]
not_inMatches nonetier NOT IN [churned, cancelled]
containsSubstring matchsource contains "fb"
gtGreater thanage > 25
gteGreater than or equalspend >= 100
ltLess thanage < 65
lteLess than or equalspend <= 50
existsHas any valuevip EXISTS
not_existsIs null or missingchurned NOT EXISTS

​
Custom Field Best Practices

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
Use consistent values across imports:
  • facebook not sometimes Facebook or FB
  • 2024-01-15 not Jan 15, 2024 or 1/15/24
Add custom fields you’ll actually use for targeting. Too many custom fields create noise.
Maintain a reference of what custom fields you use and what values are valid. Share with your team.
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:
  1. Go to Audiences > New Audience
  2. Click Add Condition > Custom Field
  3. The dropdown shows all existing custom field keys
  4. 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