Create a custom contact field
POST/api/v1/contact-fields
POST /contact-fields
curl -X POST 'https://www.unitpost.com/api/v1/contact-fields' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0' \
-H 'Content-Type: application/json' \
-d '{
"key": "plan",
"label": "Plan",
"type": "text"
}'Response · 201
{
"object": "contact_field",
"id": "id_123",
"key": "string",
"label": "string",
"type": "text",
"default_value": "string",
"position": 0,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Define a new typed custom field that can then be set on any contact and used as a template variable (e.g. plan, signup_date). An optional default_value is the value used for any contact that has none: when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. The key and type are fixed once created — rename the key later with Rename a custom field's key, or change the label with Update a custom contact field. See existing fields via List custom contact fields. Requires the contacts:write capability.
Request body4 fields
| Field | Type | Description |
|---|---|---|
keyrequired | string | — |
labelrequired | string | — |
type | enumtext | number | boolean | date | — |
default_value | string | null | The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. |
Response · 201 fields9 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
idrequired | string | — |
keyrequired | string | — |
labelrequired | string | — |
typerequired | enumtext | number | boolean | date | — |
default_valuerequired | string | null | The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. |
positionrequired | number | — |
created_atrequired | string | — |
updated_atrequired | string | — |
201401409422