API de segmentos

Crea y gestiona segmentos dinámicos de usuarios mediante programación.

Todos los endpoints de esta página son relativos a la URL base: https://api-eu1.joryio.com. Consulta el resumen de la API.

Autenticación

Todas las solicitudes requieren autenticación mediante clave de API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

---

Crear un segmento

Crea un segmento de usuarios nuevo con filtros.

Endpoint

POST /segments

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
name	cadena	Sí	Nombre del segmento (máx. 255 caracteres).
description	cadena	No	Descripción del segmento (máx. 1000 caracteres).
filterGroups	matriz	Sí	Matriz de grupos de filtros (máx. 20).
excludeFilterGroups	matriz	No	Se eliminan los usuarios que coincidan con cualquiera de estos grupos (máx. 20).
groupOperator	cadena	Sí	Cómo combinar grupos: AND u OR.
tags	matriz	No	Nombres de etiquetas para organizar segmentos.

Estructura de filtros

Cada grupo de filtros contiene hasta 50 filtros:

{
  filters: [
    {
      type: 'attribute' | 'default_attribute' | 'event' | 'ecommerce'
          | 'behavioral' | 'segment' | 'canvas_execution'
          | 'list_membership' | 'channel_subscription' | 'app'
          | 'entity' | 'bounce_status' | 'wallet_pass',
      field?: string,           // Para filtros de atributo
      operator: string,         // Consulta Operadores de filtro más abajo
      value?: any,              // Valor de comparación (también lleva N para operadores de recuento)
      eventName?: string,       // Para filtros de evento
      withinDays?: number,      // Ventana temporal para filtros de evento
      startDate?: string,       // Inicio de ventana absoluta (ISO 8601, filtros de evento)
      endDate?: string,         // Fin de ventana absoluta (ISO 8601, filtros de evento)
      segmentId?: string,       // Para filtros de segmento
      listId?: string,          // Para filtros list_membership
      channel?: string          // Para filtros channel_subscription
    }
  ],
  operator: 'AND' | 'OR'
}

Solicitud de ejemplo: filtro de atributo simple

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Users",
    "description": "Users on premium plan",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "equals",
            "value": "premium"
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

Solicitud de ejemplo: segmento de comportamiento

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Trial Users",
    "description": "Trial users active in last 7 days",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "equals",
            "value": "trial"
          },
          {
            "type": "event",
            "eventName": "Session Started",
            "operator": "performed",
            "withinDays": 7
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

Solicitud de ejemplo: segmento complejo

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value At-Risk Users",
    "description": "Paid users with high LTV who haven'\''t logged in recently",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "in",
            "value": ["premium", "enterprise"]
          },
          {
            "type": "attribute",
            "field": "lifetimeValue",
            "operator": "gte",
            "value": 500
          }
        ],
        "operator": "AND"
      },
      {
        "filters": [
          {
            "type": "event",
            "eventName": "Login",
            "operator": "not_performed",
            "withinDays": 14
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

Respuesta

El objeto de segmento se devuelve directamente, sin envoltorio. Los ID de segmento son UUID. Los recuentos de miembros no se guardan en el segmento: usa GET /segments/:id/size.

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "equals",
          "value": "premium"
        }
      ],
      "operator": "AND"
    }
  ],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

---

Obtener un segmento

Recupera los detalles de un segmento.

Endpoint

GET /segments/:id

Parámetros de ruta

Parámetro	Tipo	Descripción
id	cadena	ID de segmento.

Solicitud de ejemplo

curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
  -H "Authorization: Bearer jry_live_your_api_key"

Respuesta

El objeto de segmento, devuelto directamente (para el recuento actual de miembros, llama a GET /segments/:id/size):

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [...],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

---

Listar segmentos

Obtiene todos los segmentos con paginación.

Endpoint

GET /segments

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
limit	número	100	Resultados por página (máx. 100).
offset	número	0	Número de segmentos que se omitirán.
q	cadena	-	Búsqueda de texto libre en el nombre del segmento.
status	cadena	-	Filtra por estado: active o archived.
tags	cadena	-	Nombres de etiqueta separados por comas.
createdBy	cadena	-	ID de usuario creador separados por comas.
editedBy	cadena	-	ID de usuario del último editor separados por comas.

Solicitud de ejemplo

curl -X GET "https://api-eu1.joryio.com/segments?limit=50&status=active" \
  -H "Authorization: Bearer jry_live_your_api_key"

Respuesta

{
  "data": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Premium Users",
      "status": "active",
      "createdAt": "2024-01-20T10:30:00.000Z"
    },
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "name": "Trial Users",
      "status": "active",
      "createdAt": "2024-01-19T09:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 23,
    "page": 1,
    "limit": 50,
    "offset": 0,
    "totalPages": 1,
    "hasMore": false
  }
}

---

Actualizar un segmento

Actualiza el nombre, la descripción o los filtros del segmento. Usa PUT (no hay ruta PATCH); los campos que omitas no se modifican.

Endpoint

PUT /segments/:id

Cuerpo de la solicitud

{
  "name": "Updated Name",
  "description": "Updated description",
  "filterGroups": [...]
}

Solicitud de ejemplo

curl -X PUT https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Premium users who have made at least one purchase"
  }'

Respuesta

El objeto de segmento actualizado, devuelto directamente:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Premium users who have made at least one purchase",
  "status": "active",
  "updatedAt": "2024-01-21T14:30:00.000Z"
}

---

Archivar un segmento

Los segmentos no se pueden eliminar de forma permanente: las campañas y los journeys mantienen referencias a ellos, por lo que solo se pueden archivar. Los segmentos archivados dejan de aparecer en las listas activas y se pueden restaurar en cualquier momento.

Endpoints

POST /segments/:id/archive
POST /segments/:id/unarchive

Solicitud de ejemplo

curl -X POST https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/archive \
  -H "Authorization: Bearer jry_live_your_api_key"

Respuesta

El objeto de segmento con su nuevo estado:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "status": "archived",
  "updatedAt": "2024-01-21T14:30:00.000Z"
}

Notas

• Archivar un segmento no elimina los usuarios que contiene.
• Las campañas activas que usan este segmento se verán afectadas.
• Usa POST /segments/:id/unarchive para restaurarlo.

---

Obtener usuarios de un segmento

Obtiene la lista de usuarios de un segmento.

Endpoint

GET /segments/:id/users

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
limit	número	100	Número de usuarios que se devolverán.
offset	número	0	Número de usuarios que se omitirán.

Solicitud de ejemplo

curl -X GET "https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/users?limit=100" \
  -H "Authorization: Bearer jry_live_your_api_key"

Respuesta

Una matriz JSON sin envoltorio de documentos de usuario (sin envoltorio de paginación; pagina con limit / offset):

[
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9c",
    "externalId": "user_123",
    "email": "user1@example.com",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  },
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9d",
    "externalId": "user_456",
    "email": "user2@example.com",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-18"
    }
  }
]

---

Obtener tamaño de segmento

Obtiene el número actual de usuarios de un segmento. De forma predeterminada es una estimación rápida aproximada; envía ?exact=true para un recuento preciso. El tamaño es lo único que puede ser aproximado: la pertenencia y los envíos reales siempre son exactos.

Endpoint

GET /segments/:id/size

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
exact	booleano	false	true devuelve el recuento preciso (más lento en espacios de trabajo grandes).

Solicitud de ejemplo

curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

Respuesta

{
  "segmentId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "size": 1234,
  "approximate": true
}

---

Operadores de filtro

Operadores de atributo

Operador	Descripción	Ejemplo
equals	Coincidencia exacta.	plan equals "premium"
not_equals	No es igual.	plan not_equals "free"
in	Valor incluido en la lista.	plan in ["premium", "enterprise"]
not_in	Valor no incluido en la lista.	plan not_in ["free", "trial"]
contains	La cadena contiene.	email contains "@company.com"
not_contains	La cadena no contiene.	email not_contains "@competitor.com"
gt	Mayor que.	lifetimeValue > 1000
gte	Mayor o igual que.	age >= 18
lt	Menor que.	loginCount < 5
lte	Menor o igual que.	mrr <= 99
exists	El campo existe.	phone exists
not_exists	El campo no existe.	referralCode not_exists
within_next_days	Fecha dentro de los próximos N días.	trialEndsDate within_next_days 7

Operadores de evento

Operador	Descripción	Ejemplo
performed	El usuario realizó el evento.	Performed "Order Completed"
not_performed	El usuario no realizó el evento.	Not performed "Onboarding Completed"
performed_count_gte	Recuento de eventos mayor o igual (N en value).	Performed "Login" >= 10 times
performed_count_lte	Recuento de eventos menor o igual (N en value).	Performed "Login" <= 5 times
performed_in_last_days	Realizado en los últimos N días (N en value).	Performed "Login" in last 7 days
not_performed_in_last_days	No realizado en los últimos N días (N en value).	No "Login" in last 14 days

---

Ejemplos de filtros

Filtros de atributo

// Coincidencia de cadenas
{
  "type": "attribute",
  "field": "email",
  "operator": "contains",
  "value": "@company.com"
}

// Comparación numérica
{
  "type": "attribute",
  "field": "lifetimeValue",
  "operator": "gte",
  "value": 500
}

// Varios valores
{
  "type": "attribute",
  "field": "plan",
  "operator": "in",
  "value": ["premium", "enterprise"]
}

// El campo existe
{
  "type": "attribute",
  "field": "phone",
  "operator": "exists"
}

// Fecha dentro de los próximos N días (fechas futuras)
{
  "type": "attribute",
  "field": "trialEndsDate",
  "operator": "within_next_days",
  "value": 7
}

Filtros de evento

// Evento realizado dentro del período
{
  "type": "event",
  "eventName": "Order Completed",
  "operator": "performed",
  "withinDays": 30
}

// Evento no realizado
{
  "type": "event",
  "eventName": "Onboarding Completed",
  "operator": "not_performed"
}

// Recuento de eventos (N se indica en `value`)
{
  "type": "event",
  "eventName": "Login",
  "operator": "performed_count_gte",
  "value": 10,
  "withinDays": 30
}

Filtros de segmento

// Usuario en otro segmento
{
  "type": "segment",
  "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "operator": "in_segment"
}

// Usuario que no está en otro segmento
{
  "type": "segment",
  "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "operator": "not_in_segment"
}

---

Ejemplos comunes de segmentos

Oportunidad de conversión de prueba

{
  "name": "Trial Expiring Soon",
  "description": "Users whose trial ends in the next 3 days and haven't purchased",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "equals",
          "value": "trial"
        },
        {
          "type": "attribute",
          "field": "trialEndsDate",
          "operator": "within_next_days",
          "value": 3
        },
        {
          "type": "event",
          "eventName": "Order Completed",
          "operator": "not_performed"
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

Usuarios avanzados

{
  "name": "Power Users",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "event",
          "eventName": "Login",
          "operator": "performed_count_gte",
          "value": 20,
          "withinDays": 30
        },
        {
          "type": "event",
          "eventName": "Feature Used",
          "operator": "performed_count_gte",
          "value": 50,
          "withinDays": 30
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

Clientes en riesgo

{
  "name": "At-Risk Premium Users",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "in",
          "value": ["premium", "enterprise"]
        },
        {
          "type": "attribute",
          "field": "lifetimeValue",
          "operator": "gte",
          "value": 500
        }
      ],
      "operator": "AND"
    },
    {
      "filters": [
        {
          "type": "event",
          "eventName": "Login",
          "operator": "not_performed",
          "withinDays": 14
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

---

Actualizaciones dinámicas

Los segmentos son dinámicos: la pertenencia no es una lista almacenada. Los filtros del segmento se evalúan con los datos actuales de perfil y eventos cada vez que se usa el segmento (segmentación de campañas, barreras de journey y comprobaciones de pertenencia). No hay nada que actualizar ni recalcular mediante la API.

Comprobar el tamaño del segmento

# Obtiene el tamaño actual (aproximado de forma predeterminada; añade ?exact=true para un recuento preciso)
curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

---

Respuestas de error

Todos los errores usan el cuerpo de error estándar. Consulta resumen de la API: respuesta de error.

400 Solicitud incorrecta: filtro no válido

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments",
  "errors": [
    "filterGroups.0.filters.0.operator must be one of the following values: equals, not_equals, contains, ..."
  ]
}

404 No encontrado

{
  "statusCode": 404,
  "message": "Segment with ID 3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d not found",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d"
}

---

Límites de frecuencia

La API de segmentos no tiene hoy límites de frecuencia fijos por endpoint. Consulta resumen de la API: límites de frecuencia.

---

Prácticas recomendadas

1. Mantener los segmentos focalizados

Bien: segmentos específicos y bien dirigidos.

{
  "name": "Premium US Users - Active Last 7 Days",
  "filters": [...]
}

Mal: segmentos demasiado amplios.

{
  "name": "All Users",
  "filters": []
}

2. Usar nombres descriptivos

Bien: nombres autoexplicativos.

• "Trial Users - Expiring This Week"
• "High-Value At-Risk Customers"
• "New Signups - Not Onboarded"

Mal: nombres poco claros.

• "Segment 1"
• "Test"
• "Users ABC"

3. Combinar filtros de forma lógica

Usa AND para acotar y OR para ampliar:

// AND: usuarios premium que están activos
{
  "filters": [
    { "field": "plan", "operator": "equals", "value": "premium" },
    { "eventName": "Login", "operator": "performed", "withinDays": 7 }
  ],
  "operator": "AND"
}

// OR: usuarios con cualquier plan de pago
{
  "filters": [
    { "field": "plan", "operator": "equals", "value": "premium" },
    { "field": "plan", "operator": "equals", "value": "enterprise" }
  ],
  "operator": "OR"
}

4. Supervisar el tamaño del segmento

Rastrea el tamaño del segmento a lo largo del tiempo:

// Consulta periódicamente el tamaño del segmento
setInterval(async () => {
  const { size, approximate } = await fetch(`/segments/${segmentId}/size`).then(r => r.json());
  console.log(`Segment size: ${approximate ? '≈' : ''}${size}`);
}, 60000); // Cada minuto

---

Siguientes pasos

• Guía para crear segmentos
• Usar segmentos en campañas
• Documentación de atributos de usuario
• Guía de rastreo de eventos