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:

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

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

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

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

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.