---
title: "Contact fields"
description: "Define the typed custom attributes (text, number, date, …) your contacts carry — usable in templates as per-recipient variables."
url: https://www.unitpost.com/docs/api/contact-fields
section: API reference
updated: 2026-07-31
---
# Contact fields

## Contact fields

> Define the typed custom attributes (text, number, date, …) your contacts carry — usable in templates as per-recipient variables.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/api/contact-fields.

## Operations

### `GET /api/v1/contact-fields`

List custom contact fields

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](#post-contact-fields). Requires the `contacts:read` capability.

### `POST /api/v1/contact-fields`

Create a custom contact field

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`). The `key` and `type` are fixed once created — rename the key later with [Rename a custom field's key](#post-contact-fields-id-rename), or change the label with [Update a custom contact field](#patch-contact-fields-id). See existing fields via [List custom contact fields](#get-contact-fields). Requires the `contacts:write` capability.

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

Retrieve a custom contact field

Retrieve a single custom contact field by `id`, including its key, type, and label. Update its label with [Update a custom contact field](#patch-contact-fields-id), or rename the key with [Rename a custom field's key](#post-contact-fields-id-rename). Requires the `contacts:read` capability.

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

Update a custom contact field

Update a custom field's editable metadata, such as its display label. 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](#post-contact-fields-id-rename) instead. Requires the `contacts:write` capability.

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

Delete a custom contact field

Permanently delete a custom field definition and strip its stored value from every contact. Any template variable that referenced it will resolve to empty. This can't be undone — recreate the field with [Create a custom contact field](#post-contact-fields) if you need it back. Requires the `contacts:write` capability.

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

Rename a custom field's key

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](#patch-contact-fields-id). Requires the `contacts:write` capability.

## Related

- [Segments](https://www.unitpost.com/docs/api/segments): Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of.
- [Topics](https://www.unitpost.com/docs/api/topics): Subscription categories (e.g. Promotions) recipients can opt out of without leaving your list, independent of segment membership. Scope a campaign to a topic and opted-out contacts are skipped automatically.
- [Campaigns](https://www.unitpost.com/docs/api/campaigns): One-to-many sends to a segment or an inline recipient list. Draft, validate, schedule, send, pause, resume, and cancel — with a pre-send report that catches problems before anything goes out.