Allo

Créer un champ personnalisé

Champ Type Requis Description ------- ------ -------- ------------- label string oui Nom affiché, de 1 à 255 caractères, avec au moins une lettre ou un…

POST/v2/api/crm/attributes

Champs du body

ChampTypeRequisDescription
labelstringouiNom affiché, de 1 à 255 caractères, avec au moins une lettre ou un chiffre
typestringouiTEXT, NUMBER, DATE, BOOLEAN ou DROPDOWN
optionsarrayDROPDOWN uniquementAu moins un objet { label, key? }. Rejeté pour les autres types

Un champ DROPDOWN contient une valeur parmi ses options. Une option sans key en reçoit une dérivée de son label, comme pour la clé du champ. Les labels d'options doivent être uniques dans le champ.

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

Dérivation de la clé

La key est dérivée du label : minuscules, accents supprimés, séquences de caractères non alphanumériques remplacées par _, tronquée à 64 caractères. Lead Source devient lead_source.

Un label qui correspond à la clé d'un champ natif est rejeté avec ATTRIBUTE_KEY_RESERVED. Les clés réservées sont name, phone_numbers, company, job_title, emails, last_activity, website, created_at et updated_at.

Réponse

Renvoie 201 avec le champ. options n'est présent que pour DROPDOWN.

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

Créer deux fois le même champ

L'appel peut être répété sans risque. Si un champ avec la même clé et le même type existe déjà, l'endpoint renvoie 201 avec already_existed à true et le label avec lequel il a été créé. Rien n'est créé.

Si la clé existe avec un autre type, la requête renvoie 409 ATTRIBUTE_KEY_CONFLICT.

Restaurer un champ supprimé

Créer un champ dont la clé correspond à un champ que vous avez supprimé, avec le même type, le restaure. Les valeurs précédemment stockées sur les personnes reviennent avec lui, et la réponse a already_existed à true. Un type différent renvoie 409 ATTRIBUTE_KEY_CONFLICT.

Limites

Une équipe peut avoir jusqu'à 150 champs personnalisés TEXT, 50 NUMBER, 30 DATE et 30 BOOLEAN. Les champs DROPDOWN comptent dans la limite des TEXT. Lorsqu'un type est plein, créer un autre champ de ce type renvoie 409 ATTRIBUTE_SLOTS_EXHAUSTED.

Erreurs

StatutCodeQuand
400ATTRIBUTE_LABEL_INVALIDlabel est vide, dépasse 255 caractères ou ne contient ni lettre ni chiffre
400ATTRIBUTE_KEY_RESERVEDLe label correspond à la clé d'un champ natif
400ATTRIBUTE_OPTION_INVALIDUn champ DROPDOWN n'a aucune option, ou un label d'option est vide, dépasse 255 caractères ou est en doublon
400ATTRIBUTE_OPTIONS_NOT_SUPPORTEDoptions envoyé pour un type autre que DROPDOWN
400INVALID_REQUEST_BODYtype est absent ou n'est pas l'un de TEXT, NUMBER, DATE, BOOLEAN, DROPDOWN
403API_KEY_INSUFFICIENT_SCOPELa clé n'a pas le scope CRM_WRITE
404TEAM_NOT_FOUNDL'espace de travail n'utilise pas le nouveau modèle de contacts
409ATTRIBUTE_KEY_CONFLICTUn champ avec cette clé existe déjà avec un autre type
409ATTRIBUTE_SLOTS_EXHAUSTEDAucun emplacement libre pour ce type

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Corps

labelstringrequis

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>requis

Value type of the field

TEXTNUMBERDATEBOOLEANDROPDOWN

optionsobject[]

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

2 champs
labelstringrequis

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.

Réponses

201The custom field that was created, restored or already existing
dataobject
5 champs
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 champs
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