# Custom Field API - Fields Reference

This article describes all fields available through the Custom Field API. Use this as a reference when reading, creating, or updating custom fields.

---

## Overview

Custom fields let you store additional data about your contacts beyond the standard Envoke contact fields. The Custom Field API allows you to manage these field definitions (create, read, update, delete). To store or retrieve values for a custom field on a specific contact, use the Contact API.

All endpoints in the Custom Field API require [HTTP Basic Auth](https://envoke-developers.pages.dev/guides/authentication/) using your API ID and API Key.

---

## Fields

| Field | Type | Read-only | Required on Create | Description |
|---|---|---|---|---|
| `id` | string | Yes | — | Unique identifier assigned on creation. |
| `name` | string | No | Yes | The field identifier used to reference this custom field. |
| `description` | string | No | No | Optional human-readable description of the field. |
| `field_type` | string (enum) | Yes | Yes | The data type for values stored in this field. Cannot be changed after creation. |

---

## Field Details

### `id`

- **Type:** String
- **Read-only:** Yes — assigned automatically on creation.
- **Example:** `"42"`

The `id` is used to identify the custom field in update and delete requests, and to associate values with the field in the Contact API.

---

### `name`

- **Type:** String
- **Read-only:** No — can be updated via PATCH.
- **Required on create:** Yes
- **Validation:** Must contain only alphanumeric characters and underscores (`a-z`, `A-Z`, `0-9`, `_`). Must be unique per account.
- **Example:** `phone_number`

The `name` is how you reference the custom field in other contexts (e.g., when reading or writing contact values). Choose a name that is descriptive and consistent with your existing naming conventions.

---

### `description`

- **Type:** String
- **Read-only:** No — can be updated via PATCH.
- **Required on create:** No
- **Example:** `"Customer's mobile phone number"`

An optional human-readable label for the field. Returns an empty string (`""`) when not set.

---

### `field_type`

- **Type:** String (enum)
- **Read-only:** Yes — **cannot be changed after creation.**
- **Required on create:** Yes
- **Allowed values:** `text`, `note`, `date`, `url`

Controls what kind of value is stored in this field for each contact and how it is displayed in the Envoke UI.

| Value | Description |
|---|---|
| `text` | A standard single-line text input. |
| `note` | A multi-line text area. |
| `date` | A date value. Displays with a date selector in the UI. |
| `url` | A URL. Can be used as a merge field link target in email campaigns. |

**Important:** `field_type` is immutable. If you need to change the type of an existing field, you must delete it and create a new one. Note that deleting a custom field also removes all stored values for that field across all contacts.

---

## Error Responses

All error responses follow this structure:

**Validation errors** (e.g., missing required field, invalid `field_type`):

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "field_type is required"
    ]
  }
}
```

**Not-found behaviour varies by method:**

- **GET** `/customfields/{id}` — when the ID is not found, returns an empty array (`[]`).
- **PATCH / DELETE** `/customfields/{id}` — when the ID is not found, returns a validation error:

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Item with id '42' not found"]
  }
}
```

---

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*