Contact Properties

Define custom properties to store additional data on your contacts beyond the built-in fields. Properties can be used in segments, templates, and workflows for personalized messaging.

GET
/contact-properties

List all custom contact properties defined for your team.

json
{
  "properties": [
    {
      "id": 1,
      "name": "plan",
      "label": "Subscription Plan",
      "type": "select",
      "options": ["free", "pro", "scale"],
      "required": false,
      "created_at": "2026-03-20T10:00:00.000Z"
    },
    {
      "id": 2,
      "name": "company",
      "label": "Company Name",
      "type": "text",
      "options": null,
      "required": false,
      "created_at": "2026-03-20T10:05:00.000Z"
    }
  ]
}
POST
/contact-properties

Create a new custom contact property. The name must be unique and is used as the key when setting property values on contacts.

json
{
  "name": "plan",
  "label": "Subscription Plan",
  "type": "select",
  "options": ["free", "pro", "scale"],
  "required": false
}
PATCH
/contact-properties/:id

Update a contact property's label, options, or required flag. The name and type cannot be changed after creation.

json
{
  "label": "Current Plan",
  "options": ["free", "pro", "scale", "enterprise"],
  "required": true
}
DELETE
/contact-properties/:id

Delete a custom contact property. This removes the property definition and its values from all contacts.

json
{
  "success": true
}

Property Types

Each property has a type that determines what values it can hold:

TypeDescription
textFree-form text string
numberNumeric value
booleanTrue or false
dateISO 8601 date string
selectOne of a predefined set of options (provide the options array)

Using Properties on Contacts

Once defined, set property values when creating or updating contacts via the properties field:

POST
/contacts

Create a contact with custom properties.

json
{
  "email": "alice@example.com",
  "first_name": "Alice",
  "properties": {
    "plan": "pro",
    "company": "Acme Inc"
  }
}