PATCH /api/v1/custom-fields/{customFieldId}
Change le libellé d'un champ personnalisé. Rien d'autre ne bouge : les valeurs sont rangées sous la clé, qui reste la même.
Le libellé est la seule chose que cet appel change. Un corps qui porte key ou type est refusé en 400 plutôt qu'appliqué à moitié — pour changer l'un ou l'autre, créez un nouveau champ.
Autorisation
| Rôle dans l'organisation | Cet endpoint |
|---|---|
OWNER | Autorisé |
ADMIN | Autorisé |
MEMBER | Refusé — 403 |
Paramètres de chemin
| Paramètre | Type | Description |
|---|---|---|
customFieldId | string | Obligatoire. Le champ à renommer |
Corps de la requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
label | string | oui | De 1 à 100 caractères. Aucun autre champ n'est accepté |
json
{"label": "Origine du contact"}Exemple
bash
curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
-d '{"label":"Origine du contact"}' \
"https://www.agentsmail.io/api/v1/custom-fields/$CUSTOM_FIELD_ID"Réponse
200 OK— le champ renommé.400 Bad Request— le libellé est absent, vide ou dépasse 100 caractères, ou le corps porte un autre champ commekeyoutype;detailsporte les erreurs.401 Unauthorized— clé absente ou invalide, ou son propriétaire a quitté l'organisation.403 Forbidden— le propriétaire de la clé estmemberde l'organisation, pasadmin.404 Not Found— champ inexistant, ou il appartient à une autre organisation. L'API ne confirme jamais qu'un identifiant existe à un appelant qui n'y a pas droit.429 Too Many Requests— plus de 120 requêtes en une minute pour cette clé.
Champs de la réponse
| Champ | Type | Description |
|---|---|---|
success | boolean | Indique si l'opération a réussi |
data.id | string | Identifiant unique du champ |
data.key | string | La clé, inchangée |
data.label | string | Son nouveau libellé |
data.type | string | Le type, inchangé |
data.createdAt | string | Date de création ISO |
data.updatedAt | string | Date ISO de la dernière modification |
Exemple de réponse
json
{
"success": true,
"data": {
"id": "4f1a9c2e",
"key": "utm_source",
"label": "Origine du contact",
"type": "text",
"createdAt": "2026-11-02T08:11:00.000Z",
"updatedAt": "2026-11-15T10:22:05.000Z"
}
}Remarques
- Deux champs peuvent partager un libellé, jamais une clé : un renommage n'est jamais refusé pour un libellé déjà utilisé.