List custom field definitions

GET

/api/v3/contacts/custom-fields

const url = 'https://api.tryletterhead.com/api/v3/contacts/custom-fields?api=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/custom-fields?api=true' \
  --header 'Authorization: Bearer <token>'

Lists your company’s custom field definitions — the fields the audience page’s Custom Fields panel and Audience Settings manage. System-managed fields (the __lh.* namespace) are not included here; see List custom fields for segment criteria for those.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

application/json

object

items

Array<object>

object

The field’s numeric identifier.

integer

name

The field’s key.

string

label

string

type

text, number, boolean, or date.

string

required

boolean

sortOrder

integer

createdAt

string

updatedAt

string

source

user or system.

string

message

string

total

integer

Example

{
  "items": [
    {
      "id": 4,
      "name": "favoriteColor",
      "label": "Favorite color",
      "type": "text",
      "required": false,
      "sortOrder": 0,
      "createdAt": "2026-05-01T10:00:00+00:00",
      "updatedAt": "2026-05-01T10:00:00+00:00",
      "source": "user"
    }
  ],
  "message": "Custom field definitions retrieved.",
  "total": 1
}

Still can’t find what you need? Contact support.