v1 · API reference

Contact fields

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

Base URL: https://www.unitpost.com/api/v1/api/v1

Contact fields

List custom contact fields

GET/api/v1/api/v1/contact-fields

GET /contact-fields

curl -X GET 'https://www.unitpost.com/api/v1/api/v1/contact-fields' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

Field	Type	Description
`limit`	integer · query	Max rows to return (default 20, max 100).
`after`	string · query	Return rows after this id (forward paging).
`before`	string · query	Return rows before this id (backward paging).

Response · 200 fields9 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`key`required	string	—
`label`required	string	—
`type`required	enumtext \| number \| boolean \| date	—
`default_value`required	object	—
`position`required	number	—
`created_at`required	string	—
`updated_at`required	string	—

200401422

Create a custom contact field

POST/api/v1/api/v1/contact-fields

POST /contact-fields

curl -X POST 'https://www.unitpost.com/api/v1/api/v1/contact-fields' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Plan",
    "type": "string"
  }'

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). 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
`key`required	string	—
`label`required	string	—
`type`	enumtext \| number \| boolean \| date	—
`default_value`	object	—

Response · 201 fields9 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`key`required	string	—
`label`required	string	—
`type`required	enumtext \| number \| boolean \| date	—
`default_value`required	object	—
`position`required	number	—
`created_at`required	string	—
`updated_at`required	string	—

201401409422

Retrieve a custom contact field

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

GET /contact-fields/{id}

curl -X GET 'https://www.unitpost.com/api/v1/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

Field	Type	Description
`id`required	string · path	—

Response · 200 fields9 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`key`required	string	—
`label`required	string	—
`type`required	enumtext \| number \| boolean \| date	—
`default_value`required	object	—
`position`required	number	—
`created_at`required	string	—
`updated_at`required	string	—

200401404

Update a custom contact field

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

PATCH /contact-fields/{id}

curl -X PATCH 'https://www.unitpost.com/api/v1/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -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. 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

Field	Type	Description
`id`required	string · path	—

Request body4 fields

Field	Type	Description
`label`	string	—
`type`	enumtext \| number \| boolean \| date	—
`position`	integer	—
`default_value`	object	—

Response · 200 fields9 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`key`required	string	—
`label`required	string	—
`type`required	enumtext \| number \| boolean \| date	—
`default_value`required	object	—
`position`required	number	—
`created_at`required	string	—
`updated_at`required	string	—

200401404422

Delete a custom contact field

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

DELETE /contact-fields/{id}

curl -X DELETE 'https://www.unitpost.com/api/v1/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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 if you need it back. Requires the contacts:write capability.

Parameters1 field

Field	Type	Description
`id`required	string · path	—

204401404

Rename a custom field's key

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

POST /contact-fields/{id}/rename

curl -X POST 'https://www.unitpost.com/api/v1/api/v1/contact-fields/cf_123/rename' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "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

Field	Type	Description
`id`required	string · path	—

Request body1 field

Field	Type	Description
`key`required	string	—

Response · 200 fields9 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`key`required	string	—
`label`required	string	—
`type`required	enumtext \| number \| boolean \| date	—
`default_value`required	object	—
`position`required	number	—
`created_at`required	string	—
`updated_at`required	string	—

200401404409422