Renommer un champ personnalisé

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'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERRefusé — 403
Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Paramètres de chemin

ParamètreTypeDescription
customFieldIdstringObligatoire. Le champ à renommer

Corps de la requête

ChampTypeObligatoireDescription
labelstringouiDe 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 comme key ou type ; details porte les erreurs.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
  • 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

ChampTypeDescription
successbooleanIndique si l'opération a réussi
data.idstringIdentifiant unique du champ
data.keystringLa clé, inchangée
data.labelstringSon nouveau libellé
data.typestringLe type, inchangé
data.createdAtstringDate de création ISO
data.updatedAtstringDate 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é.

Voir aussi