> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Fields

> Organize and segment contacts with 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
```

<Note>
  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.
</Note>

## 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:

```json theme={null}
{
  "phone_number": "+14155551234",
  "custom_fields": {
    "source": "facebook",
    "campaign": "summer2024",
    "tier": "gold"
  }
}
```

### Via API

Include custom fields when creating contacts:

```bash theme={null}
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

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

| 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

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="Don't over-use custom fields">
    Add custom fields you'll actually use for targeting. Too many custom fields create noise.
  </Accordion>

  <Accordion title="Document your custom fields">
    Maintain a reference of what custom fields you use and what values are valid. Share with your team.
  </Accordion>

  <Accordion title="Use custom fields for audience exclusions">
    Custom fields like `churned`, `complained`, `high_risk` help you exclude contacts from sends.
  </Accordion>
</AccordionGroup>

## Bulk Custom Field Updates

<Info>
  **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.
</Info>

## 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

<CardGroup cols={2}>
  <Card title="Building Audiences" icon="users" href="/guides/audiences/creating-audiences">
    Use custom fields for targeting
  </Card>

  <Card title="Segmentation Logic" icon="diagram-project" href="/guides/audiences/segmentation-logic">
    Combine custom field conditions
  </Card>

  <Card title="Import Contacts" icon="upload" href="/guides/contacts/importing">
    Add custom fields during import
  </Card>
</CardGroup>