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 using your API ID and API Key.
Fields
Field | Type | Read-only | Required on Create | Description |
| string | Yes | — | Unique identifier assigned on creation. |
| string | No | Yes | The field identifier used to reference this custom field. |
| string | No | No | Optional human-readable description of the field. |
| 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 |
| A standard single-line text input. |
| A multi-line text area. |
| A date value. Displays with a date selector in the UI. |
| 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):
{ "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:
{ "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Item with id '42' not found"] } }For code examples and interactive testing, visit api.envoke.com.