# 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.

```json
[
  {
    "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

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

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

### Return the second page of results (10 per page)

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

### Filter by field type

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

### Sort by name ascending

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

### Sort by name descending

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

### Sort by field type

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

### Return only specific fields

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

Response:

```json
[
  { "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.

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

Response:

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

### Return a single field by ID

```bash
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](https://developers.envoke.com).*