# Custom Fields

> Learn how to define custom contact properties in Waflow, including field types and using custom fields in message templates.

Source: https://edesy.in/docs/waflow/contacts/custom-fields

Custom fields allow you to store any additional information about your contacts beyond the default fields. This guide covers creating custom fields, field types, managing field values, and using custom fields in your message templates.

## What Are Custom Fields?

Custom fields are user-defined properties that extend the contact data model. While Waflow includes standard fields like name, email, and phone, custom fields let you store:

- Business-specific data (customer ID, account number)
- Behavioral data (last purchase date, preferred product)
- Segmentation data (lead score, customer tier)
- Any other information relevant to your business

Custom fields are defined at the workspace level and apply to all contacts in that workspace.

## Default vs Custom Fields

### Default Fields

Every contact has these built-in fields:

| Field | Type | Editable |
|-------|------|----------|
| Phone Number | Phone | No (unique identifier) |
| First Name | Text | Yes |
| Last Name | Text | Yes |
| Email | Email | Yes |
| Company | Text | Yes |
| Notes | Long Text | Yes |
| Created At | Date | No (automatic) |
| Updated At | Date | No (automatic) |

### Custom Fields

You define these based on your needs:

| Example Field | Type | Use Case |
|---------------|------|----------|
| Customer ID | Text | Link to your CRM |
| Order Count | Number | Track purchase frequency |
| Last Purchase Date | Date | Identify dormant customers |
| Membership Tier | Dropdown | Gold, Silver, Bronze |
| Opted into SMS | Checkbox | Track consent |
| Website | URL | Company website |
| Notes | Long Text | Detailed observations |

## Field Types

Waflow supports these custom field types:

### Text

Short single-line text values.

| Property | Details |
|----------|---------|
| Max length | 255 characters |
| Use for | Names, IDs, short descriptions |
| Example | "customer_id": "CUST-12345" |

### Long Text

Multi-line text for longer content.

| Property | Details |
|----------|---------|
| Max length | 5,000 characters |
| Use for | Notes, descriptions, feedback |
| Example | Detailed customer preferences |

### Number

Numeric values (integers or decimals).

| Property | Details |
|----------|---------|
| Format | Integer or decimal |
| Range | -2^31 to 2^31 |
| Use for | Scores, counts, amounts |
| Example | "lead_score": 85 |

### Date

Date values without time.

| Property | Details |
|----------|---------|
| Format | YYYY-MM-DD |
| Use for | Birthdates, anniversaries, purchase dates |
| Example | "last_purchase": "2024-12-15" |

### Date & Time

Date and time values.

| Property | Details |
|----------|---------|
| Format | YYYY-MM-DDTHH:MM:SS |
| Use for | Appointments, events, precise timestamps |
| Example | "appointment": "2024-12-20T14:30:00" |

### Dropdown

Select from predefined options.

| Property | Details |
|----------|---------|
| Options | You define the list |
| Selection | Single choice |
| Use for | Categories, tiers, statuses |
| Example | "tier": "Gold" (options: Bronze, Silver, Gold) |

### Multi-Select

Select multiple options from a list.

| Property | Details |
|----------|---------|
| Options | You define the list |
| Selection | Multiple choices |
| Use for | Interests, products owned, preferences |
| Example | "interests": ["Sports", "Music", "Travel"] |

### Checkbox

Boolean yes/no values.

| Property | Details |
|----------|---------|
| Values | true/false (displayed as checkbox) |
| Use for | Consent flags, preferences, features |
| Example | "sms_consent": true |

### URL

Web links.

| Property | Details |
|----------|---------|
| Format | Valid URL with protocol |
| Use for | Websites, profiles, documents |
| Example | "linkedin": "https://linkedin.com/in/johndoe" |

### Email

Email addresses (in addition to the default email field).

| Property | Details |
|----------|---------|
| Format | Valid email format |
| Use for | Secondary emails, work emails |
| Example | "work_email": "john@company.com" |

## Creating Custom Fields

### Step-by-Step Guide

1. Go to **Settings** > **Custom Fields**
2. Click **Create Field**
3. Configure the field:

#### Field Name

Enter a unique name for the field:

| Good Names | Avoid |
|------------|-------|
| last_purchase_date | date |
| customer_tier | tier |
| preferred_language | pref |
| order_count | count |

Use lowercase with underscores. Names must be unique.

#### Display Name

The human-readable label shown in the UI:

- "Last Purchase Date"
- "Customer Tier"
- "Preferred Language"

#### Field Type

Select from the types described above.

#### Options (for Dropdown/Multi-Select)

If creating a dropdown or multi-select:

1. Click **Add Option**
2. Enter option value
3. Repeat for all options
4. Drag to reorder if needed

Example options for "Customer Tier":
- Bronze
- Silver
- Gold
- Platinum

#### Default Value (Optional)

Set a default value for new contacts:

- For checkbox: Default checked or unchecked
- For dropdown: Default selection
- For text: Default text (can be empty)

#### Required Field (Optional)

Mark as required if every contact must have a value:

- Required fields show a red asterisk
- Contacts cannot be saved without a value
- Existing contacts will need updating

> **Warning:** Be careful marking fields as required. Existing contacts without values may cause issues.

4. Click **Save**

The field is now available on all contact profiles.

### Bulk Create via Import

Create custom fields during CSV import:

1. Start a CSV import
2. For unmapped columns, select **Create Custom Field**
3. Configure the field type
4. Complete the import

Fields are created automatically with values populated.

## Managing Custom Fields

### View All Fields

Go to **Settings** > **Custom Fields** to see:

- All custom fields in your workspace
- Field types
- Number of contacts with values
- Created date

### Edit a Field

1. Go to **Settings** > **Custom Fields**
2. Click the edit icon on a field
3. Modify settings:
   - Display name (always editable)
   - Default value
   - Required status
   - Dropdown options (add/remove)
4. Click **Save**

> **Note:** Field name and type cannot be changed after creation. Create a new field if you need a different type.

### Delete a Field

1. Go to **Settings** > **Custom Fields**
2. Click the delete icon
3. Confirm deletion

> **Warning:** Deleting a field removes all values for all contacts. This cannot be undone.

### Reorder Fields

Change the order fields appear in contact profiles:

1. Go to **Settings** > **Custom Fields**
2. Drag fields to reorder
3. Order is saved automatically

## Editing Field Values

### Single Contact

1. Go to the contact's profile
2. Click **Edit**
3. Find the custom field
4. Enter or change the value
5. Click **Save**

### Bulk Update

Update values for multiple contacts:

1. Go to **Contacts**
2. Select contacts using checkboxes
3. Click **Edit Fields** in bulk actions
4. Select the field to update
5. Enter the new value
6. Click **Apply to Selected**

### Via CSV Import

Update existing contacts with new field values:

1. Prepare a CSV with phone number and field values
2. Import with "Update duplicates" option
3. Map columns to custom fields

### Via API

```bash
curl -X PATCH https://api.waflow.com/v1/contacts/+14155551234 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "customer_tier": "Gold",
      "last_purchase_date": "2024-12-15",
      "lead_score": 92
    }
  }'
```

## Using Custom Fields in Templates

Custom fields can be used as variables in message templates, enabling personalization.

### Variable Syntax

Use double curly braces with the field name:

```
Hello {{first_name}},

Your membership tier is {{customer_tier}}.
Your account ID: {{customer_id}}

Thank you for being a valued customer!
```

### Field Name to Variable

| Field Name | Variable Syntax |
|------------|-----------------|
| first_name | {{first_name}} |
| customer_tier | {{customer_tier}} |
| last_purchase_date | {{last_purchase_date}} |
| order_count | {{order_count}} |

### Fallback Values

Set fallback values for empty fields:

```
Hello {{first_name|Customer}},
```

If first_name is empty, "Customer" is used instead.

### Date Formatting

Format date fields in templates:

```
Your last purchase was on {{last_purchase_date|date:MMM DD, YYYY}}.
```

Outputs: "Your last purchase was on Dec 15, 2024."

### Number Formatting

Format numbers:

```
You have earned {{points|number}} reward points.
```

Adds thousand separators automatically.

### Conditional Content (Advanced)

Some templates support conditional blocks:

```
{{#if customer_tier == "Gold"}}
As a Gold member, you get 20% off!
{{else}}
Upgrade to Gold for 20% off!
{{/if}}
```

> **Note:** Conditional blocks are available in advanced template mode. Contact support to enable.

## Custom Fields in Segments

Use custom fields in dynamic segment rules:

### Example Rules

| Rule | Description |
|------|-------------|
| lead_score > 80 | High-potential leads |
| customer_tier equals "Gold" | Gold members |
| last_purchase_date within 30 days | Recent buyers |
| preferred_language equals "Spanish" | Spanish speakers |

### Complex Segments

Combine multiple custom field conditions:

```
ALL of:
- customer_tier equals "Gold" OR customer_tier equals "Platinum"
- last_purchase_date within 90 days
- sms_consent equals true
```

## Best Practices

### Planning Your Fields

Before creating fields:

1. **List your needs**: What data do you want to track?
2. **Check defaults**: Is it already a default field?
3. **Choose types carefully**: Type cannot be changed later
4. **Consider templates**: Will you use this in messages?
5. **Plan for segments**: Will you filter by this data?

### Naming Conventions

| Practice | Example |
|----------|---------|
| Use lowercase | `customer_tier` not `Customer_Tier` |
| Use underscores | `last_purchase_date` not `lastpurchasedate` |
| Be descriptive | `website_url` not `url1` |
| Include units if applicable | `lifetime_value_usd` |
| Avoid abbreviations | `subscription_status` not `sub_stat` |

### Field Organization

Organize fields logically:

| Category | Fields |
|----------|--------|
| Identity | customer_id, external_id |
| Demographics | birthday, preferred_language |
| Behavioral | last_purchase_date, order_count |
| Scoring | lead_score, engagement_score |
| Preferences | preferred_channel, interests |
| Consent | sms_consent, email_consent |

### Data Hygiene

Keep field data clean:

- Set appropriate default values
- Use dropdowns instead of text when possible
- Validate data during import
- Regularly audit field values
- Remove unused fields

### Performance Considerations

| Limit | Value |
|-------|-------|
| Custom fields per workspace | 100 |
| Dropdown options per field | 200 |
| Multi-select options per field | 50 |
| Text field max length | 255 characters |
| Long text max length | 5,000 characters |

## Common Use Cases

### E-commerce

| Field | Type | Use |
|-------|------|-----|
| customer_id | Text | CRM integration |
| last_purchase_date | Date | Recency targeting |
| total_orders | Number | Loyalty segmentation |
| average_order_value | Number | Value segmentation |
| preferred_category | Dropdown | Personalization |

### Lead Management

| Field | Type | Use |
|-------|------|-----|
| lead_source | Dropdown | Attribution |
| lead_score | Number | Prioritization |
| deal_stage | Dropdown | Pipeline tracking |
| demo_scheduled | Date | Follow-up |
| competitor_mentioned | Checkbox | Objection handling |

### Subscriptions

| Field | Type | Use |
|-------|------|-----|
| plan_type | Dropdown | Tier-based messaging |
| subscription_start | Date | Anniversary campaigns |
| renewal_date | Date | Renewal reminders |
| lifetime_value | Number | VIP identification |
| churn_risk | Number | Retention campaigns |

## Troubleshooting

### Field Not Appearing in Template Variables

- Verify the field exists in your workspace
- Check the field name spelling
- Use the exact field name (case-sensitive)

### Import Failing for Custom Fields

- Match column headers exactly to field names
- Ensure values match field types
- For dropdowns, values must match defined options exactly

### Segment Not Filtering Correctly

- Verify field has values (check for empty/null)
- Check operator (equals vs contains)
- For dates, ensure format is correct

### Can't Change Field Type

Field types are fixed after creation. To change:

1. Create a new field with the correct type
2. Export contacts with the old field
3. Update the values for the new field format
4. Import with new field mapping
5. Delete the old field

## Next Steps

Now that you have custom fields set up:

- [Create segments](https://edesy.in/docs/waflow/contacts/tags-segments) using your fields
- [Build templates](https://edesy.in/docs/waflow/templates/variables) with personalization
- [Launch campaigns](https://edesy.in/docs/waflow/campaigns/create-campaign) targeting specific audiences