PATCH /api/v1/custom-fields/{customFieldId}
Changes the label of a custom field. Nothing else moves: values are stored under the key, which
stays the same.
The label is the only thing this call changes. A body carrying key or type is refused with
400 rather than half-applied — to change either, create a new field.
Authorization
| Role in the organization | This endpoint |
|---|---|
OWNER | Allowed |
ADMIN | Allowed |
MEMBER | Refused — 403 |
Path parameters
| Parameter | Type | Description |
|---|---|---|
customFieldId | string | Required. The field to rename |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
label | string | yes | 1 to 100 characters. No other field is accepted |
json
{"label": "Acquisition source"}Example
bash
curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
-d '{"label":"Acquisition source"}' \
"https://www.agentsmail.io/api/v1/custom-fields/$CUSTOM_FIELD_ID"Response
200 OK— the renamed field.400 Bad Request— the label is missing, empty or over 100 characters, or the body carries another field such askeyortype;detailscarries the issues.401 Unauthorized— missing or invalid key, or its owner left the organization.403 Forbidden— the key's owner is amemberof the organization, not anadmin.404 Not Found— no such field, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.429 Too Many Requests— over 120 requests in a minute for this key.
Response fields
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the operation was successful |
data.id | string | Unique identifier for the field |
data.key | string | The key, unchanged |
data.label | string | Its new label |
data.type | string | The type, unchanged |
data.createdAt | string | ISO creation date |
data.updatedAt | string | ISO date of the last change |
Example response
json
{
"success": true,
"data": {
"id": "4f1a9c2e",
"key": "utm_source",
"label": "Acquisition source",
"type": "text",
"createdAt": "2026-11-02T08:11:00.000Z",
"updatedAt": "2026-11-15T10:22:05.000Z"
}
}Notes
- Two fields may share a label, never a key: a rename is never refused for a label already in use.