Saltar al contenido principal

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/api. 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​

CampoTipoObligatorioDescripción
namecadenaSíNombre del segmento (máx. 255 caracteres).
descriptioncadenaNoDescripción del segmento (máx. 1000 caracteres).
filterGroupsmatrizSíMatriz de grupos de filtros (máx. 20).
excludeFilterGroupsmatrizNoSe eliminan los usuarios que coincidan con cualquiera de estos grupos (máx. 20).
groupOperatorcadenaSíCómo combinar grupos: AND u OR.
includeCrawlersbooleanoNoCuenta los perfiles de rastreadores (bots) como miembros. Por defecto false - la página Audiencia también los oculta.
tagsmatrizNoNombres 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'
          | 'warehouse_sync' | 'device' | 'random_bucket'
          | 'contact_import' | 'message_activity',
      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'
}

Un filtro random_bucket compara el número de grupo aleatorio estable del contacto (0-9999, nunca cambia para una persona): operator es uno de equals, not_equals, less_than, less_than_or_equal, greater_than, greater_than_or_equal, between; value es un número entero del 0 al 9999, o [from, to] para between (ambos extremos incluidos). Cualquier otro valor se rechaza con un 400. Consulta Número de grupo aleatorio.

Un filtro contact_import ("Vino de una importación") selecciona contactos según las importaciones de contactos que los crearon o actualizaron: operator es any_of o none_of, y value es una lista de 1 a 100 ids de importación de GET /users/import/sources. none_of incluye los contactos que ninguna importación tocó. Una lista vacía se rechaza con un 400. Los contactos importados antes de que se publicara esta función no están marcados, así que solo coinciden con none_of. Consulta Vino de una importación.

Un filtro message_activity ("Actividad de mensajes") selecciona personas según lo que pasó con los mensajes que se les enviaron. operator es la acción: received (el evento message.sent), delivered, opened, clicked, bounced, unsubscribed o failed. messageSource es campaign (con campaignId), campaign_tag (con tagIds), any_campaign, journey (con canvasId), journey_step (con canvasId y nodeId), journey_tag (con tagIds) o any. messageChannel es any o uno de email, sms, push, whatsapp, in_app, webhook, viber: solo un canal que informa de la acción (no hay opened para sms, push ni webhook; bounced es solo email). messageWindow es ever, in_last_days o not_in_last_days (value = días, de 1 a 3650), between_dates (startDate y endDate), at_least (value = veces, al menos 1) o at_most (value = veces, 0 o más). tagIds es una lista de ids de etiqueta (de GET /tags), y varios significan cualquiera de esas etiquetas; coincide con las campañas o recorridos que llevan la etiqueta cuando se calcula la audiencia, y cambiar el nombre de la etiqueta no lo altera. Un filtro guardado con un nombre de etiqueta en tag sigue funcionando y se guarda por id en el siguiente guardado; un nombre que ninguna etiqueta lleva se rechaza con un 400. Cualquier otra cosa se rechaza con un 400. Ejemplo: { "type": "message_activity", "operator": "opened", "messageSource": "any_campaign", "messageChannel": "email", "messageWindow": "in_last_days", "value": 30 }. Consulta Actividad de mensajes.

opened en email o any sigue la regla de apertura: también incluye el clic de una persona en el email, porque un clic demuestra que el email se abrió, y con at_least / at_most compara el mayor de los recuentos de aperturas y de clics en el email. Las aperturas de bots y los clics de escáneres de enlaces nunca cuentan.

Un filtro canvas_execution también admite nodeId junto con un canvasId (la ejecución de la persona llegó a ese paso del recorrido, de cualquier tipo de nodo) y los operadores in_tagged_canvas / not_in_tagged_canvas con tagIds en lugar de canvasId: en (o no en) algún recorrido que lleve la etiqueta. Con nodeId, stepWindow lo limita a cuándo la ejecución entró por última vez en el paso: ever (por defecto), in_last_days (withinDays, de 1 a 3650) o between_dates (startDate y endDate). Un operador de un solo recorrido (in_canvas, not_in_canvas, completed_canvas, exited_canvas) guardado sin canvasId no coincide con nadie. Consulta Ejecución de Canvas.

Solicitud de ejemplo: filtro de atributo simple​

curl -X POST https://api-eu1.joryio.com/api/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/api/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/api/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ámetroTipoDescripción
idcadenaID de segmento.

Solicitud de ejemplo​

curl -X GET https://api-eu1.joryio.com/api/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ámetroTipoPredeterminadoDescripción
limitnúmero100Resultados por página (máx. 100).
offsetnúmero0Número de segmentos que se omitirán.
qcadenaBúsqueda de texto libre en el nombre del segmento.
statuscadenaFiltra por estado: active o archived.
tagscadenaNombres de etiqueta separados por comas.
createdBycadenaID de usuario creador separados por comas.
editedBycadenaID de usuario del último editor separados por comas.

Solicitud de ejemplo​

curl -X GET "https://api-eu1.joryio.com/api/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/api/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/api/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ámetroTipoPredeterminadoDescripción
limitnúmero100Número de usuarios que se devolverán.
offsetnúmero0Número de usuarios que se omitirán.

Solicitud de ejemplo​

curl -X GET "https://api-eu1.joryio.com/api/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": "[email protected]",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  },
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9d",
    "externalId": "user_456",
    "email": "[email protected]",
    "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ámetroTipoPredeterminadoDescripción
exactbooleanofalsetrue devuelve el recuento preciso (más lento en espacios de trabajo grandes).

Solicitud de ejemplo​

curl -X GET https://api-eu1.joryio.com/api/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​

OperadorDescripciónEjemplo
equalsCoincidencia exacta.plan equals "premium"
not_equalsNo es igual.plan not_equals "free"
inValor incluido en la lista.plan in ["premium", "enterprise"]
not_inValor no incluido en la lista.plan not_in ["free", "trial"]
containsLa cadena contiene.email contains "@company.com"
not_containsLa cadena no contiene.email not_contains "@competitor.com"
gtMayor que.lifetimeValue > 1000
gteMayor o igual que.age >= 18
ltMenor que.loginCount < 5
lteMenor o igual que.mrr <= 99
existsEl campo existe.phone exists
not_existsEl campo no existe.referralCode not_exists
within_next_daysFecha dentro de los próximos N días.trialEndsDate within_next_days 7
Contactos sin valor

Un contacto sin valor en el campo coincide con los operadores negativos (not_equals, not_contains, not_in, not_exists) y con ninguno de los positivos (equals, contains, in, exists, gt, gte, lt, lte). Consulta Contactos sin valor.

Los identificadores se comparan de forma flexible

email se compara sin distinguir mayúsculas de minúsculas con equals, not_equals, in y not_in: [email protected] y [email protected] son la misma dirección. phone se compara por sus dígitos con esos mismos cuatro operadores, de modo que +972501234567, 972501234567 y +972 50-123-4567 coinciden con el mismo contacto. Los demás campos se comparan exactamente como los escribes, incluido externalId: tus propios identificadores siguen distinguiendo mayúsculas.

Operadores de evento​

OperadorDescripciónEjemplo
performedEl usuario realizó el evento.Performed "Order Completed"
not_performedEl usuario no realizó el evento.Not performed "Onboarding Completed"
performed_count_gteRecuento de eventos mayor o igual (N en value).Performed "Login" >= 10 times
performed_count_lteRecuento de eventos menor o igual (N en value).Performed "Login" <= 5 times
performed_in_last_daysRealizado en los últimos N días (N en value).Performed "Login" in last 7 days
not_performed_in_last_daysNo 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/api/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

Mantener un segmento listo para los informes​

Los informes de analítica que filtran por segmento tienen que calcular primero quién pertenece a él y entregar esa lista de personas a la base de datos de analítica junto con la consulta. La lista es el límite: una comparación de retención analiza como mucho 50.000 miembros de un segmento y toma una muestra aleatoria cuando el segmento es mayor.

Materializar un segmento guarda su pertenencia en la base de datos de analítica, de modo que el informe hace un JOIN y no viaja ninguna lista. El límite desaparece a cualquier tamaño.

Está desactivado por defecto y se activa segmento a segmento, porque el coste es una reconstrucción nocturna y la mayoría de los segmentos nunca aparecen en un informe. Cada organización tiene una asignación compartida entre todos sus espacios de trabajo: veinte por defecto. Pídenos ampliarla.

El intercambio es la frescura. Un segmento materializado se reconstruye cada noche y cuando tú lo pidas, así que un informe lee la pertenencia de la última reconstrucción, no la de este instante. Los informes indican qué marca de tiempo usaron.

Consultar el estado​

GET /segments/:id/materialization
curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/materialization \
  -H "Authorization: Bearer jry_live_your_api_key"
{
  "materialized": true,
  "refreshedAt": "2026-09-03T03:00:00.000Z",
  "memberCount": 482103,
  "error": null,
  "used": 4,
  "quota": 20
}

refreshedAt es null hasta que termina la primera reconstrucción. error indica por qué falló la última, de modo que una instantánea antigua pueda decir por qué lo es; mientras tanto sigue sirviendo la pertenencia anterior en lugar de vaciarse el segmento. Un quota de -1 significa ilimitado.

Todos los segmentos materializados de la organización​

GET /segments/materialization/usage

La asignación, lo consumido y qué segmentos lo consumen, en todos los espacios de trabajo de la organización, algo que ninguna vista limitada a un espacio de trabajo puede mostrar.

{
  "quota": 20,
  "used": 2,
  "segments": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Champions",
      "workspaceId": "8c1f0b2a-91d4-4a77-9a3e-2d6f7b5c1e40",
      "refreshedAt": "2026-09-03T03:00:00.000Z",
      "memberCount": 1200,
      "error": null
    }
  ]
}

Activarlo​

POST /segments/:id/materialization

La primera construcción se ejecuta de inmediato, sin esperar a la noche. Devuelve el mismo objeto de estado.

Devuelve 400 cuando la organización no tiene plazas libres, nombrando los segmentos que las ocupan para que elijas cuál desactivar.

Desactivarlo​

DELETE /segments/:id/materialization

Borra la pertenencia almacenada y libera la plaza.

Reconstruir ahora​

POST /segments/:id/materialization/refresh

Recalcula la pertenencia de inmediato. La pertenencia se reconstruye entera en vez de añadirse, así que quienes ya no cumplen los criterios se eliminan igual que se añaden los nuevos, algo que importa porque la gente sale de un segmento sin hacer nada: un comprador deja de estar en "sin compras en 30 días" solo porque avanza el calendario.

Probar los filtros antes de usarlos​

Es fácil equivocarse sutilmente en un conjunto de filtros, y el error es silencioso: devuelve una audiencia más pequeña, no un error. Estas rutas permiten que una integración compruebe su trabajo antes de que un envío dependa de él.

Previsualizar una audiencia​

POST /segments/preview

Cuántos contactos coinciden con un conjunto de filtros, sin guardar un segmento.

{ "count": 4820 }

Muestra de usuarios coincidentes​

POST /segments/preview-users

La misma consulta, devolviendo una muestra de los contactos reales para que compruebes si son las personas que querías.

Comprobar un usuario​

POST /segments/check-user

¿Coincide este contacto con este conjunto de filtros? La comprobación individual que necesita una integración cuando decide sobre una persona y no construye una audiencia.

Respuesta:

{ "userId": "user_123", "matches": true }

Desglose por canal​

POST /segments/channel-breakdown

Cuántos de los contactos coincidentes son realmente alcanzables en cada canal. Un segmento de 10.000 con 400 teléfonos no es una audiencia de SMS de 10.000, y aquí se ve antes de programar el envío.

Respuesta:

{
  "email": 9210,
  "sms": 400,
  "push": 3110,
  "whatsapp": 280,
  "viber": 95,
  "matched": 10000,
  "capped": false
}

matched es la población de la que los recuentos por canal son un subconjunto, y capped es true cuando el segmento era demasiado grande para resolverse con exactitud (los recuentos son entonces de la muestra resuelta). El recuento de un canal es lo que la ruta de envío puede alcanzar realmente: un contacto suscrito sin dirección, sin teléfono o sin dispositivo registrado no cuenta. El registro STOP y las listas de supresión de direcciones se vuelven a comprobar en el envío, así que un envío real solo puede ser menor.

Creación masiva y exportaciones​

POST /segments/bulk
GET /segments/exports

POST /segments/bulk crea varios segmentos en una llamada, para aprovisionar un espacio de trabajo desde tu propia configuración en lugar de a base de clics. GET /segments/exports muestra los trabajos de exportación con su estado y la URL de descarga prefirmada cuando terminan.

Siguientes pasos​

Eliminar frente a archivar​

POST   /segments/{segmentId}/archive
DELETE /segments/{segmentId}

Archivar es la opción por defecto. Un segmento archivado deja de aparecer en los selectores y en las comprobaciones de pertenencia, mientras que toda campaña o recorrido que ya apunte a él sigue funcionando. Para revertirlo: POST /segments/{segmentId}/unarchive.

Eliminar lo borra de forma permanente, y solo cuando nada lo referencia. Si una campaña, un recorrido, una campaña in-app u otro segmento aún lo usa, la petición devuelve 409 y los nombra.

GET /users/{userId}/segments evalúa cada segmento ACTIVO frente al contacto, así que un espacio de trabajo que acumula segmentos los paga en cada comprobación de pertenencia. Archivar o eliminar los que ya no usas es la solución.