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": {
    "oneOf": [
      { "const": "GOOGLE", "title": "Búsqueda en Google" },
      { "const": "RECOMENDACION", "title": "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

Reglas del valor, escritas como un fragmento de JSON Schema 2020-12 (ver Reglas por tipo). Obligatorio en un select o un multiselect, que necesitan sus opciones.

Reglas por tipo

config declara las reglas del valor como palabras clave de JSON Schema. Cada tipo admite solo las reglas de la tabla: una regla que el tipo no admite se rechaza con 422. El contrato completo, con un schema por tipo, se obtiene en GET /v1/fields/format.

Tipo	Reglas que admite
text	minLength, maxLength, pattern o x-patternPreset
textarea	minLength, maxLength, pattern
url	minLength, maxLength, pattern o x-patternPreset (url)
address	minLength, maxLength
email	pattern o x-patternPreset (email)
phone	pattern o x-patternPreset (phone_cl, phone_intl)
number	minimum, maximum
date	formatMinimum, formatMaximum (fechas YYYY-MM-DD)
select	oneOf (la lista de opciones)
multiselect	items.anyOf (la lista de opciones)
boolean	ninguna

• minLength y maxLength cuentan caracteres. minLength admite desde 0 y maxLength desde 1.
• minimum y maximum admiten valores entre -10^15 y 10^15.
• formatMinimum y formatMaximum no son palabras clave de JSON Schema 2020-12. Siguen la convención de los validadores que acotan fechas, como ajv-formats.
• Un rango invertido se rechaza: el mínimo no puede ser mayor que el máximo.

Opciones de selección

Un select declara sus opciones en config.oneOf y un multiselect en config.items.anyOf. Cada opción es un par:

{ "const": "GOOGLE", "title": "Búsqueda en Google" }

• const 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.
• title 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 const. Al registrar un envío de formulario, la opción se compara con const: un envío que mande el title se rechaza. Un campo admite hasta 500 opciones, y cada title hasta 150 caracteres.

Un multiselect declara sus opciones dentro de items:

{ "items": { "anyOf": [{ "const": "DEPORTE", "title": "Deporte" }] } }

Patrón de validación

Un campo text, url, email o phone puede exigir un formato con una de dos reglas en config: x-patternPreset o pattern, nunca las dos a la vez. Un textarea admite solo pattern. El valor tiene que cumplir el formato completo, no solo en una parte.

x-patternPreset elige un formato que la plataforma ya define. Cada tipo admite solo algunos:

x-patternPreset	Acepta, por ejemplo	Tipos
email	[email protected]	text, email
phone_cl	+56 9 1234 5678	text, phone
phone_intl	+56912345678	text, phone
rut	12.345.678-9	text
url	https://ejemplo.cl	text, url

El formato email admite solo caracteres ASCII, antes y después de la @. Una dirección con tildes o eñe (gonzá[email protected], ana@ñandú.cl) no cumple el formato: casi siempre es un error de tipeo en una dirección que se escribe sin ellas.

Un formato que no existe, o que el tipo no admite, se rechaza con 422. x-patternPreset es una palabra clave propia de la plataforma, no de JSON Schema.

Un valor de un campo phone se guarda sin espacios, guiones, puntos ni paréntesis, y su formato se revisa sobre ese valor: con phone_intl, +56 9 1234 5678 se acepta como +56912345678. Aun sin formato propio, un teléfono tiene que ser un + opcional seguido de 6 a 15 dígitos.

pattern es una expresión regular propia, de hasta 1.024 caracteres. A diferencia del pattern de JSON Schema, que se cumple con que una parte del valor coincida, aquí el valor completo tiene que coincidir. Su dialecto es el de JSON Schema (ECMA-262, el de JavaScript). El mismo patrón se evalúa en la plataforma, en la importación de listas y en el navegador de quien llena un formulario, que lo recibe en el <input pattern>. Por eso el catálogo acepta solo la sintaxis que todas esas vías leen igual:

• Admite caracteres literales, ., ^, $, clases como [a-z] y [^0-9], categorías Unicode como \p{L} (letras, con tildes y eñe) o \p{Lu}, los escapes \n, \t, \xHH y \uHHHH, grupos (...), (?:...) y con nombre (?<nombre>...), alternativas a|b, y repeticiones *, +, ?, {n}, {n,} y {n,m} con su variante perezosa.
• Un carácter de sintaxis se escribe escapado. Fuera de corchetes: \., \*, \/, \(, \]. Dentro de corchetes, además: \- para un guion al inicio o al final ([a-z\-]) y \/, \|, \{, \}, \(, \). Escapar un carácter que no lo necesita (\- o \@ fuera de corchetes) se rechaza.
• Rechaza \w, \d, \s y \b, que el navegador lee solo en ASCII: con ^\w+$, el formulario no dejaría enviar «José». Rechaza también los modificadores ((?i)), los grupos con nombre al estilo (?P<nombre>...), las anclas \A y \z, las búsquedas hacia adelante o hacia atrás, las referencias a otro grupo, los grupos atómicos, los cuantificadores posesivos, los condicionales, la recursión, las clases anidadas y las llaves que no indican una repetición.
• Un patrón puede repetir clases de caracteres hasta 200 veces en total, contando las repeticiones anidadas: \p{L}{200} se acepta y (\p{L}{10}){21} no.

En vez de	Escriba
\w	\p{L} para letras, o una clase como [\p{L}0-9_]
\d	[0-9]
\s	el espacio, o una clase como [ \t]
(?i)hola	[Hh][Oo][Ll][Aa]
(?P<nombre>...)	(?<nombre>...)
\pL	\p{L}
[a-z -]	[a-z \-]

El rechazo indica qué usó el patrón y en qué posición. Ver Errores.

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

Las reglas que debe cumplir el valor del campo, en JSON Schema. Dependen del tipo: las opciones de un select o un multiselect, el largo, el rango o el patrón. Ver Reglas por tipo y, para el contrato completo, GET /v1/fields/format.

created_atstring (date-time)siempre presente

Fecha y hora de creación.

updated_atstring (date-time)siempre presente

Fecha y hora de la última modificación.

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.

En un 422 por config, cada ítem de errors[] apunta a la clave que lo causa, por ejemplo /config/minimum o /config/oneOf/0/const, y su code dice el motivo. La revisión tiene dos pasos. Primero se revisa la forma de config contra el schema del tipo, y se informan todos los motivos juntos. Después, con la forma ya válida, se revisa la coherencia: rangos, fechas, claves repetidas y sintaxis del patrón.

errors[].code	params	Cuándo
field_config_key_unknown	key, field_type	config trae una regla que el tipo no admite.
field_options_required		Un select o un multiselect sin opciones.
option_key_required		Una opción sin const.
option_key_invalid		Un const que no es solo MAYÚSCULAS, números y guion bajo, o que supera los 32 caracteres.
option_label_required		Una opción sin title, o con un title de solo espacios.
option_key_duplicated	key	Dos opciones con el mismo const.
field_config_range_invalid	low, high	Un mínimo mayor que su máximo.
field_config_pattern_conflict		pattern y x-patternPreset a la vez.
pattern_preset_unknown	expected, field_type	x-patternPreset no es uno de los formatos que el tipo admite. expected los nombra. En un tipo que no admite ningún formato, la respuesta es field_config_key_unknown.
pattern_unsupported	construct, position	pattern usa una construcción que no se admite. construct la nombra (lookahead, lookbehind, backreference, atomic_group, possessive_quantifier, conditional, recursion, special_group, duplicate_group_name, inline_flag, escape, nested_class, brace, repetition, repetition_size, shorthand_class o unescaped_syntax) y position es su posición en el patrón, contando desde 0.
pattern_invalid	reason	pattern no es una expresión regular válida, por ejemplo con un paréntesis sin cerrar.
field_config_invalid		Un valor con la forma equivocada, por ejemplo una fecha que no existe, un número fuera de rango, más de 500 opciones, un title de más de 150 caracteres o un pattern de más de 1.024.

El catálogo completo está en Respuestas de error.

Una regla que el tipo no admite se rechaza, apuntando a la clave:

{
  "status": 422,
  "code": "validation_error",
  "errors": [
    {
      "pointer": "/config/minLength",
      "code": "field_config_key_unknown",
      "message": "minLength is not a rule a number field takes",
      "params": { "key": "minLength", "field_type": "number" }
    }
  ]
}

Request

curl -X POST "https://$API_HOST/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": {
    "oneOf": [
      {
        "const": "GOOGLE",
        "title": "Búsqueda en Google"
      },
      {
        "const": "RECOMENDACION",
        "title": "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": {
  "oneOf": [
    {
      "const": "GOOGLE",
      "title": "Búsqueda en Google"
    },
    {
      "const": "RECOMENDACION",
      "title": "Recomendación de un colega"
    }
  ]
},
"created_at": "2026-09-15T03:54:00Z",
"updated_at": "2026-09-15T03:54:00Z"
}