Custom Field API - Read | Envoke Help Center

Use the read endpoints to retrieve custom field definitions for your account. You can retrieve all fields at once or look up a single field by its ID.

Endpoints

Method	URL	Description
GET	`https://e1.envoke.com/v2/customfields`	Return a list of custom fields.
GET	`https://e1.envoke.com/v2/customfields/{ID}`	Return a single custom field.

Authentication is via HTTP Basic Auth using your API ID and API Key.

List Custom Fields

GET https://e1.envoke.com/v2/customfields

Returns a JSON array of all contact-scoped custom fields for your account, sorted alphabetically by name by default. Supports filtering, sorting, pagination, and field selection.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`10`	Maximum number of results to return. Hard cap is `100` unless `?fields=` or `?result_type=kvp` is also set (see note below).
`skip`	integer	`0`	Number of records to skip. Use with `limit` to paginate through results.
`fields`	string	(all)	Comma-separated list of fields to include in each result object. See note below about limit behaviour.
`result_type`	string	(array)	Set to `kvp` to receive results as a key-value object (`{ "id": "name" }`) instead of an array. See note below about limit behaviour.
`filter[id]`	string	—	Filter by custom field ID (exact match).
`filter[name]`	string	—	Filter by field name (exact match).
`filter[field_type]`	string	—	Filter by field type (exact match). Values: `text`, `note`, `date`, `url`.
`filter[description]`	string	—	Filter by description (exact match).
`sort[name]`	string	—	Sort by field name. Value: `asc` or `desc`.
`sort[field_type]`	string	—	Sort by field type. Value: `asc` or `desc`.

Note — limit behaviour with ?fields= and ?result_type=kvp: When either of these parameters is present, the request is treated as a "shaped" response. In this mode the default limit increases to 100,000 (returning all records if no limit is specified) and an explicit ?limit= value above 100 is honoured as-is. This is intentional so that callers building dropdowns or full exports do not need to paginate.

Response

A JSON array of custom field objects. Returns an empty array ([]) if no custom fields have been created.

[   {     "id": "1",     "name": "phone_number",     "description": "Customer's mobile phone number",     "field_type": "text"   },   {     "id": "2",     "name": "birthday",     "description": "",     "field_type": "date"   } ]

Get a Single Custom Field

GET https://e1.envoke.com/v2/customfields/{ID}

Returns a single custom field object. Replace {ID} with the Envoke custom field ID.

Response

{   "id": "1",   "name": "phone_number",   "description": "Customer's mobile phone number",   "field_type": "text" }

If the ID is not found, the API returns an empty array ([]) rather than an error object.

Examples

Return all custom fields

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields"

Return the second page of results (10 per page)

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?limit=10&skip=10"

Filter by field type

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?filter%5Bfield_type%5D=text"

Sort by name ascending

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?sort%5Bname%5D=asc"

Sort by name descending

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?sort%5Bname%5D=desc"

Sort by field type

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?sort%5Bfield_type%5D=asc"

Return only specific fields

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?fields=id,name,field_type"

Response:

[   { "id": "1", "name": "phone_number", "field_type": "text" },   { "id": "2", "name": "birthday", "field_type": "date" } ]

Return results as a key-value map

Use result_type=kvp to get a flat object mapping each field's ID to its name. This is useful for populating UI dropdowns.

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields?result_type=kvp"

Response:

{   "1": "phone_number",   "2": "birthday" }

Return a single field by ID

curl -gs -u "$API_ID:$API_KEY" \   "https://e1.envoke.com/v2/customfields/1"

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.