Skip to main content

Custom Field API - Insert

Written by Marcus Warren

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.

For code examples and interactive testing, visit api.envoke.com.

Did this answer your question?