Custom Field API - Update

Use this endpoint to update an existing custom field. You can update a field’s name and/or description. The field_type cannot be changed after creation.

---

Endpoint

PATCH https://e1.envoke.com/v2/customfields/{ID}

Replace {ID} with the Envoke custom field ID you want to update. Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

Request Body

Field	Type	Description
name	string	New name for the field. Alphanumeric characters and underscores only. Must be unique per account.
description	string	New description for the field. Pass an empty string ("") to clear an existing description.

At least one of name or description must be provided.

Note: field_type is read-only and cannot be included in an update request. Attempting to change it will return a validation error. If id is included in the request body, it must match the {ID} in the URL — if they differ, a validation error is returned: "Provided 'id': {url_id} does not match 'id' in request body ({body_id})".

---

Response

On success, the API returns the updated custom field object:

{
  "success": true,
  "result_text": "Updated",
  "result_data": {
    "id": "42",
    "name": "mobile_number",
    "description": "Customer's mobile phone number",
    "field_type": "text"
  }
}

---

Validation Errors

If the request is invalid, the API returns a 400 response with an errors array:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "The field 'field_type' cannot be changed after creation"
    ]
  }
}

Common errors:

Error	Cause
Request body may not be empty	No JSON body was provided.
The field 'field_type' cannot be changed after creation	field_type was included in the request body.
Only alphanumeric and underscore characters are permitted in the name field	New name contained spaces or special characters.
A custom field named '{name}' already exists	The new name conflicts with an existing custom field in your account.
Item with id '{id}' not found	The {ID} in the URL does not match any custom field in your account.
Provided 'id': {url_id} does not match 'id' in request body ({body_id})	id in the request body differs from {ID} in the URL.

---

Examples

Update a field’s description

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Customer primary mobile number"}' \
  "https://e1.envoke.com/v2/customfields/42"

Rename a field

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mobile_number"}' \
  "https://e1.envoke.com/v2/customfields/42"

Update both name and description

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mobile_number", "description": "Customer primary mobile number"}' \
  "https://e1.envoke.com/v2/customfields/42"

Clear a field’s description

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": ""}' \
  "https://e1.envoke.com/v2/customfields/42"

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.