Renombrar un campo personalizado

PATCH /api/v1/custom-fields/{customFieldId} Cambia la etiqueta de un campo personalizado. Nada más se mueve: los valores se guardan bajo la clave, que sigue siendo la misma. La etiqueta es lo único que cambia esta llamada. Un cuerpo que lleva key o type se rechaza con 400 en lugar de aplicarse a medias; para cambiar cualquiera de los dos, crea un campo nuevo.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERRechazado — 403
Una clave lleva el rol que su creador tiene en esta organización, nunca un rol sobre AgentsMail en sí. Consulta Claves de API.

Parámetros de ruta

ParámetroTipoDescripción
customFieldIdstringObligatorio. El campo que se renombra

Cuerpo de la solicitud

CampoTipoObligatorioDescripción
labelstringsíDe 1 a 100 caracteres. No se acepta ningún otro campo
json
{"label": "Origen del contacto"}

Ejemplo

bash
curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"label":"Origen del contacto"}' \
  "https://www.agentsmail.io/api/v1/custom-fields/$CUSTOM_FIELD_ID"

Respuesta

  • 200 OK: el campo renombrado.
  • 400 Bad Request: la etiqueta falta, está vacía o supera los 100 caracteres, o el cuerpo lleva otro campo como key o type; details lleva los problemas.
  • 401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
  • 403 Forbidden: el propietario de la clave es member de la organización, no admin.
  • 404 Not Found: no existe ese campo, o pertenece a otra organización. La API nunca confirma que un id existe a un llamante que no tiene derecho sobre él.
  • 429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

CampoTipoDescripción
successbooleanIndica si la operación tuvo éxito
data.idstringIdentificador único del campo
data.keystringLa clave, sin cambios
data.labelstringSu nueva etiqueta
data.typestringEl tipo, sin cambios
data.createdAtstringFecha de creación ISO
data.updatedAtstringFecha ISO del último cambio

Ejemplo de respuesta

json
{
  "success": true,
  "data": {
    "id": "4f1a9c2e",
    "key": "utm_source",
    "label": "Origen del contacto",
    "type": "text",
    "createdAt": "2026-11-02T08:11:00.000Z",
    "updatedAt": "2026-11-15T10:22:05.000Z"
  }
}

Notas

  • Dos campos pueden compartir una etiqueta, nunca una clave: un renombrado nunca se rechaza por una etiqueta ya en uso.

Relacionado