Custom Field API - Read

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 10,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.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.