Skip to main content

​
Concept

Custom Fields let you add extra fields to contact profiles in the Timely.ai CRM, beyond the default fields like name, email, and phone. They are useful when you need to store business-specific information — order number, subscribed plan, customer segment, last purchase date, tax ID, company name, and so on. Fields are defined at the workspace level and apply to all contacts. Each field has a data type (text, number, date, boolean, select) and can be marked as required or optional. Each contact’s field values are accessed via contact.custom_fields in the Contacts API.

​
Available Field Types

TypeValue in typeExample use
Free texttextNotes, protocol number
NumbernumberContract value, order count
DatedateBirthday, due date
BooleanbooleanVIP, overdue, newsletter
Single selectselectSegment, plan, status
Multi-selectmultiselectInterests, contracted products

​
Main Fields

FieldTypeDescription
idstring (UUID)Unique field ID
namestringField name (displayed in UI)
keystringAPI access key (snake_case)
typeenumField data type
requiredbooleanWhether the field is required
optionsarrayAvailable options for select and multiselect
default_valueanyDefault value for new contacts
created_atstringISO 8601 creation timestamp

​
Using Together with Contacts

When creating or updating a contact, pass custom field values in the custom_fields object using each field’s key: 
{
  "name": "Lucas Ferreira",
  "email": "lucas@company.com",
  "custom_fields": {
    "plan": "pro",
    "customer_number": "CLT-00123",
    "vip": true
  }
}

​
Available Endpoints

See the left sidebar for the full list of endpoints in this group. Each endpoint has its own page with request/response schema, cURL/JS/Python examples, and an interactive playground.

​
Next Steps

Your first request

If you haven’t made your first call yet, start here.