# 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:

```json
{
  "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:

```json
{
  "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

```bash
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

```bash
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

```bash
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

```bash
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](https://developers.envoke.com).*