Listar suscriptores
Consulta una lista paginada por cursor, ordenada por fecha de creación.
GET /v1/subscribers
Requiere el permiso subscribers:read o full. Los permisos se comprueban en el servidor. Las claves test se rechazan con 403 test_mode_unavailable; no existe un sandbox aislado.
Devuelve suscriptores de la marca asociada a la clave. Por defecto se ordenan por created_at descendente. Consulta las convenciones de paginación.
Parámetros de consulta
| Parámetro | Tipo | Descripción |
|---|---|---|
limit | integer | Tamaño de página de 1 a 100; por defecto 25. |
cursor | string | next_cursor de la página anterior. Omítelo en la primera petición. |
sort | string | created_at para los más antiguos primero o -created_at para los más recientes; este último es el predeterminado. |
filter[email] | string | Coincidencia exacta por email, comparado en minúsculas. |
filter[external_id] | string | Coincidencia exacta por tu identificador externo. |
filter[created_at_gte] | string | Fecha ISO 8601; incluye registros creados desde ese instante. |
filter[created_at_lte] | string | Fecha ISO 8601; incluye registros creados hasta ese instante. |
filter[has_consent] | string | email, sms o whatsapp: solo altas vigentes en el canal. |
Los filtros se combinan con AND. Todavía no hay otros filtros, operadores ni búsqueda por texto libre.
Respuesta
object vale list; data contiene los suscriptores; has_more indica si quedan resultados. Envía next_cursor como cursor en la siguiente petición; vale null cuando no quedan páginas.
Ejemplo
curl -g "https://fluyio.com/api/v1/subscribers?limit=50&filter[has_consent]=email&sort=-created_at" \
-H "Authorization: Bearer $FLUYIO_API_KEY" \
-H "Fluyio-Version: 2026-05-15"Respuesta
{
"object": "list",
"data": [
{
"id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"object": "subscriber",
"email": "[email protected]",
"phone": "+34600000000",
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": { "email": "subscribed", "sms": "subscribed", "whatsapp": "never_subscribed" },
"properties": { "company": "Analytical Engines", "plan": "pro", "country": "ES" },
"lists": ["lst_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"],
"tags": ["beta", "vip"],
"created_at": "2026-05-11T12:34:56.000Z",
"updated_at": "2026-05-11T12:34:56.000Z",
"last_active_at": "2026-05-11T15:00:00.000Z"
}
],
"has_more": true,
"next_cursor": "MjAyNi0wNS0xMVQxMjozNDo1Ni4wMDBafDlmMWMyYjNhLTRkNWUtNmY3MC04MTkyLWEzYjRjNWQ2ZTdmOA"
}Los cursores son opacos: no los interpretes. Conserva sort y todos los filtros durante el recorrido. En cURL usa -g para enviar los corchetes literalmente.
Errores
| HTTP | code | Descripción |
|---|---|---|
| 401 | missing_api_key / invalid_api_key | Falta la clave, no es válida, ha caducado o está revocada. |
| 403 | missing_scope | La clave no permite esta operación. |
| 403 | test_mode_unavailable | El modo de pruebas no está disponible. |
| 400 | invalid_param | Límite, orden, fecha o canal de filtro no válido; param identifica el parámetro. |
| 400 | invalid_cursor | Cursor inválido o incompatible con los parámetros; reinicia desde la primera página. |