Champs du body
| Champ | Type | Requis | Description |
|---|---|---|---|
label | string | oui | Nom affiché, de 1 à 255 caractères, avec au moins une lettre ou un chiffre |
type | string | oui | TEXT, NUMBER, DATE, BOOLEAN ou DROPDOWN |
options | array | DROPDOWN uniquement | Au 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
| Statut | Code | Quand |
|---|---|---|
400 | ATTRIBUTE_LABEL_INVALID | label est vide, dépasse 255 caractères ou ne contient ni lettre ni chiffre |
400 | ATTRIBUTE_KEY_RESERVED | Le label correspond à la clé d'un champ natif |
400 | ATTRIBUTE_OPTION_INVALID | Un champ DROPDOWN n'a aucune option, ou un label d'option est vide, dépasse 255 caractères ou est en doublon |
400 | ATTRIBUTE_OPTIONS_NOT_SUPPORTED | options envoyé pour un type autre que DROPDOWN |
400 | INVALID_REQUEST_BODY | type est absent ou n'est pas l'un de TEXT, NUMBER, DATE, BOOLEAN, DROPDOWN |
403 | API_KEY_INSUFFICIENT_SCOPE | La clé n'a pas le scope CRM_WRITE |
404 | TEAM_NOT_FOUND | L'espace de travail n'utilise pas le nouveau modèle de contacts |
409 | ATTRIBUTE_KEY_CONFLICT | Un champ avec cette clé existe déjà avec un autre type |
409 | ATTRIBUTE_SLOTS_EXHAUSTED | Aucun emplacement libre pour ce type |