Crear un campo

POST/v1/fields

Para desarrolladores

Descripción

Crea un campo del catálogo de la instancia, reutilizable por cualquier formulario.

Sirve para poblar un catálogo de una sola vez: al migrar desde otra plataforma los campos ya vienen definidos, y recrearlos uno por uno en el panel es lento y propenso a errores de tipeo en las claves.

Editar, desactivar y eliminar un campo se hacen desde el panel. Esta API solo crea.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope field:write. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Body:

{
  "name": "Cómo nos conociste",
  "field_key": "FUENTE",
  "type": "select",
  "config": {
    "options": [
      { "value": "GOOGLE", "label": "Búsqueda en Google" },
      { "value": "RECOMENDACION", "label": "Recomendación de un colega" }
    ]
  }
}

namestringobligatorio

Nombre visible del campo. Máx. 255 caracteres. No puede repetir el de otro campo (sin contar los eliminados), aunque cambien mayúsculas o tildes: Árbol y arbol son el mismo nombre.

field_keystringobligatorio

Clave canónica del campo. Solo MAYÚSCULAS, números y guion bajo, máx. 64 caracteres. No puede empezar con FIDE_, reservado para los campos de la plataforma. Inmutable, y queda reservada para siempre aunque el campo se elimine.

typestringobligatorio

text, textarea, email, phone, number, date, select, multiselect, boolean, url o address.

configobject

Configuración específica del tipo (ver Opciones de selección).

Opciones de selección

Un campo select o multiselect declara sus opciones en config.options. Cada opción es un par:

{ "value": "GOOGLE", "label": "Búsqueda en Google" }

• value es lo que queda guardado en cada respuesta y lo que se lee en el archivo exportado. Admite solo MAYÚSCULAS, números y guion bajo, máx. 32 caracteres. Use un valor corto y reconocible, porque se guarda completo en cada respuesta.
• label es lo que lee quien completa el formulario. Puede cambiarse cuando haga falta.

Declararlos por separado es lo que permite corregir el texto visible sin alterar lo que guardaron las respuestas anteriores. Dos opciones no pueden declarar el mismo value. Lo que se registra se compara con value: si manda el label, se rechaza.

Response

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).

idintegersiempre presente

Identificador del campo.

namestringsiempre presente

Nombre visible del campo.

field_keystringsiempre presente

Clave canónica del campo (mayúsculas, guion bajo). Es la que nombra el dato al registrar un contacto en un dataset.

typestring, enum: `email | phone | text | textarea | number | date | select | multiselect | boolean | url | address`siempre presente

Tipo de dato del campo.

is_systembooleansiempre presente

true para los campos que vienen con la cuenta (EMAIL, PHONE, FIRST_NAME, LAST_NAME, UNIQUECODE, ADDRESS) y no se pueden eliminar.

is_activebooleansiempre presente

Un campo inactivo queda de solo lectura: no se puede asociar a nuevos formularios.

configobject | null

Configuración específica del tipo (por ejemplo, opciones de un select o un multiselect, que comparten la misma lista). Forma libre, depende de type.

created_atstring (date-time)siempre presente

—

updated_atstring (date-time)siempre presente

—

Un campo select o multiselect declara sus opciones en config.options, y cada opción es un par:

Campo	Qué es
value	Lo que queda guardado en cada respuesta y lo que se lee en el archivo exportado. Solo MAYÚSCULAS, números y guion bajo, máx. 32 caracteres.
label	Lo que lee quien completa el formulario. Puede cambiarse sin alterar lo ya respondido.

Nota

Lo que se registra se compara con value: si manda el label, se rechaza. Use valores cortos y reconocibles, porque se guardan completos en cada respuesta.

Errores

Código	code	Cuándo
403	forbidden	La API key no tiene el scope field:write, o la IP no está en la lista permitida.
409	field_key_already_exists	Ya existe un campo activo con ese field_key.
409	field_key_reserved	Ese field_key perteneció a un campo eliminado y no puede reutilizarse.
409	field_name_taken	Ya existe otro campo con ese name (sin contar los eliminados).
422	validation_error	El body no cumple el contrato (por ejemplo, un field_key que empieza con FIDE_ o un name de solo espacios). errors[] indica el campo y el motivo.

El catálogo completo está en Errores.

Request

curl -X POST "https://cl2api.fidelizador.com/v1/fields" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Instance-Slug: <slug>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Cómo nos conociste",
  "field_key": "FUENTE",
  "type": "select",
  "config": {
    "options": [
      {
        "value": "GOOGLE",
        "label": "Búsqueda en Google"
      },
      {
        "value": "RECOMENDACION",
        "label": "Recomendación de un colega"
      }
    ]
  }
}'

Response

{
"id": 7,
"name": "Cómo nos conociste",
"field_key": "FUENTE",
"type": "select",
"is_system": false,
"is_active": true,
"config": {
  "options": [
    {
      "value": "GOOGLE",
      "label": "Búsqueda en Google"
    },
    {
      "value": "RECOMENDACION",
      "label": "Recomendación de un colega"
    }
  ]
},
"created_at": "2026-09-15T03:54:00Z",
"updated_at": "2026-09-15T03:54:00Z"
}