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ón | Este endpoint |
|---|---|
OWNER | Permitido |
ADMIN | Permitido |
MEMBER | Rechazado — 403 |
Parámetros de ruta
| Parámetro | Tipo | Descripción |
|---|---|---|
customFieldId | string | Obligatorio. El campo que se renombra |
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
label | string | sí | 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 comokeyotype;detailslleva 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 esmemberde la organización, noadmin.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
| Campo | Tipo | Descripción |
|---|---|---|
success | boolean | Indica si la operación tuvo éxito |
data.id | string | Identificador único del campo |
data.key | string | La clave, sin cambios |
data.label | string | Su nueva etiqueta |
data.type | string | El tipo, sin cambios |
data.createdAt | string | Fecha de creación ISO |
data.updatedAt | string | Fecha 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.