Allo

Create custom field

Creates a custom field on your team's people. The key is derived from the label. DROPDOWN fields need a non-empty options list. Creating the same label with…

POST/v2/api/crm/attributes

Body fields

FieldTypeRequiredDescription
labelstringyesDisplay name, 1 to 255 characters, with at least one letter or digit
typestringyesTEXT, NUMBER, DATE, BOOLEAN or DROPDOWN
optionsarrayDROPDOWN onlyAt least one { label, key? } object. Rejected for other types

A DROPDOWN field holds one value out of its options. An option without a key gets one derived from its label, the same way as the field key. Option labels must be unique within the field.

{
  "label": "Lead status",
  "type": "DROPDOWN",
  "options": [{ "label": "Hot" }, { "label": "Cold" }]
}

Key derivation

The key is derived from the label: lowercase, accents removed, runs of non-alphanumeric characters replaced by _, truncated to 64 characters. Lead Source becomes lead_source.

A label that resolves to a built-in field key is rejected with ATTRIBUTE_KEY_RESERVED. The reserved keys are name, phone_numbers, company, job_title, emails, last_activity, website, created_at and updated_at.

Response

Returns 201 with the field. options is only present for DROPDOWN.

{
  "data": {
    "key": "lead_status",
    "label": "Lead status",
    "type": "DROPDOWN",
    "options": [
      { "key": "hot", "label": "Hot" },
      { "key": "cold", "label": "Cold" }
    ],
    "already_existed": false
  }
}

Creating the same field twice

The call is safe to repeat. If a field with the same key and type already exists, the endpoint returns 201 with already_existed set to true and the label it was first created with. Nothing is created.

If the key exists with a different type, the request returns 409 ATTRIBUTE_KEY_CONFLICT.

Restoring a deleted field

Creating a field whose key matches a field you deleted, with the same type, restores it. The values previously stored on people come back with it, and the response has already_existed set to true. A different type returns 409 ATTRIBUTE_KEY_CONFLICT.

Limits

A team can hold up to 150 TEXT, 50 NUMBER, 30 DATE and 30 BOOLEAN custom fields. DROPDOWN fields count toward the TEXT limit. Once a type is full, creating another field of that type returns 409 ATTRIBUTE_SLOTS_EXHAUSTED.

Errors

StatusCodeWhen
400ATTRIBUTE_LABEL_INVALIDlabel is blank, longer than 255 characters, or has no letter or digit
400ATTRIBUTE_KEY_RESERVEDThe label resolves to a built-in field key
400ATTRIBUTE_OPTION_INVALIDA DROPDOWN field has no options, or an option label is blank, longer than 255 characters or duplicated
400ATTRIBUTE_OPTIONS_NOT_SUPPORTEDoptions sent for a type other than DROPDOWN
400INVALID_REQUEST_BODYtype is missing or is not one of TEXT, NUMBER, DATE, BOOLEAN, DROPDOWN
403API_KEY_INSUFFICIENT_SCOPEThe key does not hold CRM_WRITE
404TEAM_NOT_FOUNDThe workspace is not on the new contact model
409ATTRIBUTE_KEY_CONFLICTA field with this key already exists with another type
409ATTRIBUTE_SLOTS_EXHAUSTEDNo free slot is left for this type

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Body

labelstringrequired

Display name of the field. The key is derived from it: lowercase, accents removed, runs of non-alphanumeric characters replaced by _, truncated to 64 characters. Must contain at least one letter or digit and must not resolve to a built-in field key such as name, company or website.

typeenum<string>required

Value type of the field

TEXTNUMBERDATEBOOLEANDROPDOWN

optionsobject[]

Allowed values. Required, with at least one option, for DROPDOWN; rejected for other types.

2 fields
labelstringrequired

Display name of the option

keystring

Existing option key. Send it when editing an attribute to keep the option's key stable while its label changes. Keys that do not match an existing option are ignored and a key is derived from the label.

Responses

201The custom field that was created, restored or already existing
dataobject
5 fields
keystring

Key derived from the label

labelstring

Stored label. When the field already existed, this is the label it was first created with.

typeenum<string>

TEXTNUMBERDATEBOOLEANDROPDOWN

optionsobject[]

Allowed values. Only set for DROPDOWN fields.

2 fields
keystring
labelstring
already_existedboolean

true when a field with the same key and type already existed, or a deleted one was restored, and nothing new was created

400
401
403
404
409
429