Managing Attributes
Create custom fields and attributes for your contacts.
Never store sensitive data. Do not store passwords, payment card numbers, bank details, government IDs, or medical/health information in contact attributes. If you need to reference external systems, store a non-sensitive ID (for example, crm_id) instead of the raw data. Always comply with your local privacy laws and your company’s data retention policies.
Field types
Choose a type that matches the data you will store. This ensures correct validation, filtering, and formatting.
Text
Use for names, companies, tags, and general strings.
- Examples: company, referral_source
- Segments: equals, not equals, contains, starts with
Validation Rules
| Rule | Description | Example |
|---|---|---|
| Valid email address (simple RFC 5322) | jane.doe@example.com | |
| url | Valid HTTP/HTTPS URL | https://example.com/path |
| phone | Valid US or E.164 phone number | +14155552671 |
| regex | Custom regular expression (full match) | ^A-Z{3}-\d{4}$ |
Integer
Whole numbers only.
- Examples: lifetime_orders, loyalty_points, age
- Segments: equals, greater/less than, between
Boolean
True/false values.
- Examples: subscribed, is_customer, opted_in_sms
- Segments: is true, is false
Sending booleans as strings true and false through the API are not accepted and
will result in a validation error.
Date
Calendar date without time of day.
- Examples: birth_date, signup_date, last_purchase_date
- Segments: before, after, on, between
Date formats
| Format label | Pattern | Example |
|---|---|---|
| ISO 8601 (Extended) | YYYY-MM-DD | 2025-09-22 |
| ISO 8601 (Basic) | YYYYMMDD | 20250922 |
| ISO Week (Year-Week) | GGGG-WWW | 2025-W39 |
| ISO Weekday (Y-W-Day) | GGGG-WWW-E | 2025-W39-1 |
| US (MM/DD/YYYY) | MM/DD/YYYY | 09/22/2025 |
| European (DD/MM/YYYY) | DD/MM/YYYY | 22/09/2025 |
Datetime
Exact moment in time, with optional timezone offset.
- Examples: last_seen_at, unsubscribed_at, created_at
- Segments: before, after, between
Datetime formats
| Format label | Pattern | Example |
|---|---|---|
| RFC 3339 / ISO 8601 (Offset) | YYYY-MM-DDTHH:mm:ssZ | 2025-09-22T16:18:00+02:00 |
| RFC 3339 + milliseconds (Offset) | YYYY-MM-DDTHH:mm:ss.SSSZ | 2025-09-22T16:18:00.123+02:00 |
| RFC 3339 UTC (Zulu) | YYYY-MM-DDTHH:mm:ssZ | 2025-09-22T14:18:00Z |
| ISO 8601 Basic (Offset) | YYYYMMDDTHHmmssZ | 20250922T161800+02:00 |
| 24‑hour (space‑separated) | YYYY-MM-DD HH:mm:ss | 2025-09-22 16:18:00 |
| 24‑hour + milliseconds | YYYY-MM-DD HH:mm:ss.SSS | 2025-09-22 16:18:00.123 |
| 12‑hour (AM/PM) | YYYY-MM-DD hh:mm:ss A | 2025-09-22 04:18:00 PM |
| RFC 2822 (Email) | ddd, DD MMM YYYY HH:mm:ss ZZ | Mon, 22 Sep 2025 16:18:00 +0200 |
| HTTP-date (RFC 7231, GMT) | ddd, DD MMM YYYY HH:mm:ss GMT | Mon, 22 Sep 2025 14:18:00 GMT |
Creating fields
Navigate to Workspace Settings
From the top-left workspace switcher, click your workspace name and choose Workspace Settings.
Select Fields
Open the Fields tab to view default attributes and any custom fields you’ve already created.
Add New Field
Click Add Field and complete the form:
- Name. Snake_case, lowercase, and unique.
- Type. Choose Text, Integer, Boolean, Date, or Datetime.
- Description (optional). Help text for teammates.
- Format (for Date/Datetime). Choose how values are displayed and how CSV imports are parsed.
Click Create to save. The field will now be available on contacts, in imports, segments, and personalization.
Managing fields
Hide a field (recommended)
If you no longer use a field, hide it from forms and tables instead of deleting it. Hiding keeps historical values on contacts and avoids breaking references.
Delete a field (with caution)
Deleting a field permanently removes the attribute and its values from all contacts. You may be blocked from deleting a field that is used in segments, automations, or templates. Consider exporting data before deletion.
Using fields
In segments
Use fields to build powerful audience rules. Examples:
- Text: email contains @example.com
- Integer: lifetime_orders >= 3
- Boolean: subscribed is true
- Date: last_purchase_date is within the last 30 days
- Datetime: last_seen_at after 2025-09-01T00:00:00Z
In campaigns and templates
Personalize subjects and content with contact attributes. Use the variables picker in the editor to insert fields safely and provide fallbacks where appropriate (for example, First name or there).
Importing and updating attributes
- Map CSV columns to existing fields during import. Create needed fields ahead of time in Workspace Settings → Fields.
- Booleans: true/false, yes/no, 1/0 are accepted.
- Dates/Datetimes: ensure the column values match one of the supported patterns above. Offset-aware datetime formats are preferred.
- Identity: Existing contacts are matched according to your Workspace Identity settings (for example, email or phone). Mismatched identity values will create new contacts.
Reserved and default attributes
Common system attributes include email, first_name, last_name, phone. Avoid creating custom fields with these keys to prevent conflicts.
Best practices
- Keep field keys short, lowercase, and use underscores (for example, loyalty_points).
- Choose the smallest type that fits your data (Boolean/Integer over Text) for clearer logic and better filtering.
- Avoid storing sensitive or long free-form text that you won’t segment on.
- Standardize date/datetime formats across your imports and integrations.
- Review fields quarterly and hide or remove what you no longer need.
Troubleshooting
- Dates not importing: Confirm the format matches one of the supported patterns and the column has no mixed values.
- Booleans all false: Ensure the CSV values are consistently yes/no, true/false, or 1/0 (case-insensitive).
- Can’t delete a field: Remove it from any segments, automations, or templates first, or hide it instead.
- Unexpected duplicates after import: Review Identity settings in Workspace Settings and verify that emails/phones are normalized before import.