Custom fields

A custom field is one piece of data you keep on every contact, beyond the email and the name — utm_source, plan_tier, signup_date. It is defined once for the whole organization, and every contact can then carry a value for it. See What a custom field does for the rules behind it. These calls manage the definitions: the key, the label and the type. The values themselves are written on the contact, with customFields on Add or update one contact.
  • The key and the type are fixed at creation. Only the label can be renamed. To change either, create a new field.
  • An organization has at most 50 custom fields.
  • Some keys are reserved because every contact already has them (email, first_name, status…) and are refused.

The loop, end to end

  1. Read the fields. GET /api/v1/custom-fields lists every key the organization has defined.
  2. Create what is missing. POST /api/v1/custom-fields with a key, a label and a type.
  3. Write the values. Send customFields on Add or update one contact. A key that is not defined here is refused, so create the field first.