Listar campos

GET/v1/fields

Para desarrolladores

Descripción

Lista el catálogo de campos disponibles para asociar a un dataset. Cada campo tiene una field_key canónica — la clave que se usa para mapear columnas al importar filas a un dataset.

Los endpoints de dataset no están disponibles todavía. Este endpoint sí lo está y devuelve el catálogo, pero las rutas /v1/datasets que consumirían la field_key responden 404: quedan diferidas a V4.3. Hoy los campos se usan desde los formularios y desde el panel.

Guía relacionada

• Campos de contacto — Defina los campos de contacto que usan sus plantillas y formularios.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope field:read. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Query params:

pageinteger

Página, 1-indexed. Default: 1.

page_sizeinteger

Tamaño de página, 1–100. Default: 20.

is_activeboolean | null

Filtra por estado activo/inactivo. Omitido: sin filtro.

Response

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene los campos que siguen.

idintegerobligatorio

Identificador del campo.

namestringobligatorio

Nombre visible del campo.

field_keystringobligatorio

Clave canónica del campo (mayúsculas, guion bajo). Se usa para mapear columnas al importar un dataset.

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

Tipo de dato del campo.

is_systembooleanobligatorio

true para los campos sembrados por la cuenta (EMAIL, PHONE, FIRST_NAME, LAST_NAME, UNIQUECODE, ADDRESS) — no se pueden eliminar.

is_activebooleanobligatorio

Un campo inactivo queda de solo lectura: no se puede asociar a nuevos datasets ni 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.

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.

{ "options": [{ "value": "CL", "label": "Chile" }] }

Nota

El envío se compara contra value, así que un envío que mande el label se rechaza. Conviene que las llaves sean cortas y reconocibles: viajan enteras dentro de cada respuesta.

Para crear un campo con sus opciones, ver POST /v1/fields. | created_at | string (date-time) | sí | — | | updated_at | string (date-time) | sí | — |

Request

curl -X GET "https://$API_HOST/v1/fields?is_active=true" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"data": [
  {
    "id": 1,
    "name": "Email",
    "field_key": "EMAIL",
    "type": "email",
    "is_system": true,
    "is_active": true,
    "config": {
      "patternPreset": "email"
    },
    "created_at": "2026-05-08T14:22:31Z",
    "updated_at": "2026-05-08T14:22:31Z"
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 6,
  "total_pages": 1
}
}