Saltar al contenido principal

Listar campos

GET/v1/fields

Para desarrolladores

Descripción​

Devuelve el catálogo de campos de contacto de la instancia: el nombre, el tipo y las reglas de validación de cada campo. Los formularios y las columnas de los datasets usan estos mismos campos.

Consúltelo antes de enviar datos de contacto. La field_key de cada campo es la clave con que se nombra ese dato en el resto de la API: en cada columna de un dataset y al registrar un contacto. El type y el config indican qué forma debe tener cada valor, porque la plataforma valida contra ellos.

El catálogo no es fijo: trae seis campos de sistema y los que haya creado usted. Léalo en vez de asumirlo.

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 <API_KEY>.
X-Instance-Slugstringheaderobligatorio
Identificador de su instancia. Ver Autenticación.

Request​

Query params:

pageinteger
Número de página; la primera es la 1. Default: 1.
page_sizeinteger
Tamaño de página, 1–100. Default: 20.
is_activeboolean | null
Filtra por estado activo/inactivo. Si se omite, no se filtra.

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.
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.

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

CampoQué es
constLo 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.
titleLo que lee quien completa el formulario. Puede cambiarse sin alterar lo ya respondido.
{ "oneOf": [{ "const": "CL", "title": "Chile" }] }
Notas
  • Al registrar un envío de formulario, la opción se compara con const: un envío que mande el title se rechaza. Use valores de const cortos y reconocibles, porque se guardan completos en cada respuesta.
  • Para crear un campo con sus opciones, use POST /v1/fields.
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": {
      "x-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
}
}