Campos personalizados

Las definiciones pertenecen al workspace y los valores pertenecen a cada contacto. Consulta GET /fields o GET /fields/{id} con contacts:read. Crear con POST /fields y guardar con POST /fields/{id}/save requiere segments:write; guardar exige también If-Match.

Crea una definición

Incluye Idempotency-Key y un cuerpo como este:

{"key": "loyalty_points", "label": "Puntos", "type": "number"}

Los tipos son text, number, boolean, date, datetime, single_select y multi_select. Los dos tipos de selección requieren entre 1 y 30 opciones con {id, label} e IDs únicos. Los demás omiten options, incluso si sería un array vacío.

La clave es única en el workspace. Clave, tipo e IDs de opciones existentes se conservan al editar; puedes cambiar etiquetas y añadir opciones. Cambiar una etiqueta no cambia el valor almacenado.

Guarda un valor

En el perfil, custom se indexa por ID de definición, no por su clave ni etiqueta. Este fragmento puede formar parte de un PATCH de contacto con revisión actual:

{
  "custom": {
    "FIELD_ID": {"type": "number", "value": 120}
  }
}

Fechas usan YYYY-MM-DD; datetime usa UTC con Z y precisión máxima de microsegundos. Una selección guarda un ID de opción y selección múltiple guarda un array de IDs. false, 0 y [] son valores presentes; null en el patch elimina el valor.

POST /contacts/{id}/custom-fields permite {fieldId, value} con contacts:write y revisión del contacto. También permite {definition: {key, label, type, options?}, value} para crear definición y valor atómicamente; esta variante exige además segments:write. Si falla la validación, no queda una definición huérfana.

Usa los datos

Los valores sirven para personalización y reglas de audiencia. El servidor comprueba workspace, tipo y opciones antes de guardar; crear la definición no asigna un valor a los demás contactos. Puedes administrar las definiciones desde Configuración → Campos personalizados.