Contact fields

List custom contact fields

GET/api/v1/contact-fields

GET /contact-fields
curl -X GET 'https://www.unitpost.com/api/v1/contact-fields' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}

Retrieve a list of the custom contact fields defined in your workspace, cursor-paginated. These are the typed attributes (text, number, date, boolean, and so on) you can set on any contact and reference as template variables. Define a new one with Create a custom contact field. Requires the contacts:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe 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.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200401422

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
FieldTypeDescription
keyrequiredstring—
labelrequiredstring—
typeenumtext | number | boolean | date—
default_valuestring | nullThe 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
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe 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.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
201401409422

Retrieve a custom contact field

GET/api/v1/contact-fields/{id}

GET /contact-fields/{id}
curl -X GET 'https://www.unitpost.com/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "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"
}

Retrieve a single custom contact field by id, including its key, type, and label. Update its label with Update a custom contact field, or rename the key with Rename a custom field's key. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe 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.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a custom contact field

PATCH/api/v1/contact-fields/{id}

PATCH /contact-fields/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "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"
}

Update a custom field's editable metadata, such as its display label or default_value. A changed default takes effect at once, for sends and for segment membership, because it is never stored on contacts. The key and type are immutable here — to change the key (and migrate every contact's stored value) use Rename a custom field's key instead. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body4 fields
FieldTypeDescription
labelstring—
typeenumtext | number | boolean | date—
positioninteger—
default_valuestring | nullThe 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 · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe 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.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200401404422

Delete a custom contact field

DELETE/api/v1/contact-fields/{id}

DELETE /contact-fields/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Permanently delete a custom field definition and strip its stored value from every contact. Any template variable that referenced it will resolve to empty. On more than 5,000 contacts the strip runs as a background job and the response is 202 with the job's progress instead of 204. This can't be undone — recreate the field with Create a custom contact field if you need it back. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202204401404409

Rename a custom field's key

POST/api/v1/contact-fields/{id}/rename

POST /contact-fields/{id}/rename
curl -X POST 'https://www.unitpost.com/api/v1/contact-fields/cf_123/rename' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "subscription_plan"
  }'
Response · 200
{
  "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"
}

Change a custom field's key, migrating the stored value on every contact so no data is lost. Because the key is how templates and the API reference the field, update any template variables that used the old key. To change only the display label, use Update a custom contact field. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
keyrequiredstring—
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe 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.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200202401404409422

Search docs and guides

Search the docs and product guides.