# Custom Field API - Insert

Use this endpoint to create a new contact-scoped custom field for your account.

---

## Endpoint

```
POST https://e1.envoke.com/v2/customfields
```

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | The field identifier. Alphanumeric characters and underscores only. Must be unique per account. |
| `field_type` | string | Yes | The data type for this field. One of: `text`, `note`, `date`, `url`. Cannot be changed after creation. |
| `description` | string | No | A human-readable description of the field. |

### `field_type` Values

| Value | Description |
|---|---|
| `text` | Single-line text input. |
| `note` | Multi-line text area. |
| `date` | Date value, displayed with a date selector in the UI. |
| `url` | URL value. Can be used as a merge field link target in email campaigns. |

---

## Response

On success, the API returns the newly created custom field object:

```json
{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "42",
    "name": "phone_number",
    "description": "Customer's mobile phone number",
    "field_type": "text"
  }
}
```

The `result_data.id` value is the Envoke custom field ID. Store this if you need to reference the field in subsequent API calls.

---

## Validation Errors

If the request body 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 'name' is required",
      "field_type is required"
    ]
  }
}
```

Common validation errors:

| Error | Cause |
|---|---|
| `Request body may not be empty` | No JSON body was provided. |
| `The field 'name' is required` | `name` was missing or empty. |
| `Only alphanumeric and underscore characters are permitted in the name field` | `name` contained spaces or special characters. |
| `field_type is required` | `field_type` was missing. |
| `Invalid 'field_type'; allowed values are: text, note, date, url` | `field_type` was not one of the allowed values. |
| `A custom field named '{name}' already exists` | A custom field with that name already exists in your account. |

---

## Examples

### Create a text field

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "phone_number", "field_type": "text", "description": "Customer mobile number"}' \
  "https://e1.envoke.com/v2/customfields"
```

### Create a date field

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "birthday", "field_type": "date"}' \
  "https://e1.envoke.com/v2/customfields"
```

### Create a URL field

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "company_website", "field_type": "url", "description": "Company website URL"}' \
  "https://e1.envoke.com/v2/customfields"
```

---

**Important:** The `field_type` of a custom field cannot be changed after creation. If you need to change a field's type, you must delete the existing field and create a new one. Deleting a custom field also permanently removes all stored values for that field across all of your contacts.

---

*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).*