Create a custom field definition
POST
/api/v3/contacts/custom-fields
const url = 'https://api.tryletterhead.com/api/v3/contacts/custom-fields';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"api":true,"name":"favoriteColor","label":"Favorite color","type":"text"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tryletterhead.com/api/v3/contacts/custom-fields \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "api": true, "name": "favoriteColor", "label": "Favorite color", "type": "text" }'Creates a company-level custom field. Once created, set its values per contact with customFields on Create or update a contact / Update a contact.
This is a company-level (v3) write. Authenticate with a company API key as a Bearer token.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ” Media type application/json
object
api
required
Required. Set to true to authenticate with an API key.
boolean
name
required
The field’s key. Letters, numbers, underscores, and spaces only. Max 255 characters.
string
label
required
The human-readable label shown in the UI. Max 255 characters.
string
type
required
text, number, boolean, or date.
string
required
Whether the field must be filled in. Defaults to false.
boolean
sortOrder
Display position. Omit to have one assigned automatically.
integer
Example
{ "api": true, "name": "favoriteColor", "label": "Favorite color", "type": "text"}Responses
Section titled “ Responses ”Custom field definition created.
Media type application/json
object
items
object
id
The field’s numeric identifier.
integer
name
string
label
string
type
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-08-30T15:01:21+00:00", "updatedAt": "2026-08-30T15:01:21+00:00", "source": "user" }, "message": "Custom field definition created.", "total": 1}Still can’t find what you need? Contact support.