---
title: "Rename a custom field's key"
method: POST
path: "/contact-fields/{id}/rename"
tags: ["Contact fields"]
---

# Rename a custom field's key

`POST /contact-fields/{id}/rename`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/contact-fields/{id}/rename`
- Auth: HTTP bearer

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.

## Request body

- ContactFieldRename
  - `key` string, required

## Response `200`

The renamed contact field.

- ContactField
  - `object` 'contact_field', required
  - `id` string, required
  - `key` string, required
  - `label` string, required
  - `type` 'text' | 'number' | 'boolean' | 'date', required
  - `default_value` string, nullable, required: 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.
  - `position` number, required
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `202`: Accepted: the field held a value on more than 5,000 contacts. The field already carries the new key (`GET /contact-fields/{id}` shows it); each contact's stored value moves to the new key in the background. A value written under the new key while the job runs is kept; until the job reaches a contact, that contact resolves the new key to the field's default. The body is the job; follow it with `GET /jobs/{id}` until its `status` is `COMPLETED` (or `FAILED`).
- `401`: Missing or invalid API key.
- `404`: Contact field not found.
- `409`: A field with the new key already exists, or a delete / rename of this field is already running (`job_in_progress`; the `Location` header names that job).
- `422`: Validation error.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)