Saltearse al contenido

Sincronización de audiencias

Las sincronizaciones de audiencias envían una audiencia de graph8 (lista de contactos) a una plataforma publicitaria y la mantienen actualizada de forma periódica. graph8 es compatible con cuatro plataformas: Meta (audiencias personalizadas de Facebook/Instagram), LinkedIn (Matched Audiences), Google Ads (Customer Match) y X (Tailored Audiences).

Cada configuración de sincronización tiene un modo:

  • mirror: mantiene la audiencia de la plataforma sincronizada exactamente con la lista de origen (agrega nuevos miembros y elimina los que ya no están).
  • append_only: solo agrega nuevos miembros; nunca elimina.

Un proceso ejecuta cada sincronización según su refresh_cadence_hours. También puede activar una sincronización de forma manual.

EndpointMétodoDescripción
/audience-syncsGETLista todas las configuraciones de sincronización de la organización
/audience-syncsPOSTCrea una nueva configuración de sincronización
/audience-syncs/{id}GETObtiene una configuración de sincronización individual
/audience-syncs/{id}PATCHActualiza una configuración de sincronización
/audience-syncs/{id}DELETEEliminación lógica de una configuración de sincronización
/audience-syncs/{id}/triggerPOSTActiva manualmente una ejecución de sincronización
/audience-syncs/{id}/runsGETLista las ejecuciones de sincronización recientes
/audience-syncs/{id}/errorsGETLista únicamente las ejecuciones de sincronización fallidas

Para esquemas en formato legible por máquina, consulte la documentación interactiva de la API.

Listar sincronizaciones de audiencias

GET /audience-syncs

Devuelve todas las configuraciones de sincronización de la organización autenticada.

Ejemplo

Ventana de terminal
curl "https://be.graph8.com/api/v1/audience-syncs" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": [
    {
      "id": 12,
      "audience_id": 5,
      "platform": "meta",
      "platform_audience_name": "Q2 Outbound - Mirror",
      "mode": "mirror",
      "refresh_cadence_hours": 24,
      "is_active": true,
      "status": "active",
      "last_sync_at": "2026-04-15T08:00:00Z",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ]
}

Crear sincronización de audiencia

POST /audience-syncs

Crea una nueva configuración de sincronización. Devuelve 409 Conflict si ya existe una configuración para la misma combinación de audience_id + platform.

Cuerpo de la solicitud

CampoTipoRequeridoDescripción
audience_idintegerSíID de la lista de origen (debe ser > 0)
platformstringSíUno de meta, linkedin, google, x
platform_audience_namestringNoNombre visible en la plataforma publicitaria (máx. 255)
modestringNomirror (predeterminado) o append_only
refresh_cadence_hoursintegerNo0-720, predeterminado 24
platform_configobjectNoConfiguración específica de la plataforma (p. ej., ID de cuenta publicitaria, alcances OAuth)
suppression_list_idsinteger[]NoListas cuyos miembros deben excluirse

Ejemplo

Ventana de terminal
curl -X POST "https://be.graph8.com/api/v1/audience-syncs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": 5,
    "platform": "meta",
    "platform_audience_name": "Q2 Outbound",
    "mode": "mirror",
    "refresh_cadence_hours": 24,
    "platform_config": {"ad_account_id": "act_1234567890"}
  }'

Respuesta 201 Created

Devuelve la misma estructura que un elemento de la lista.

Errores

EstadoSignificado
409Ya existe una configuración de sincronización para esta combinación de audiencia + plataforma
422platform no está en el conjunto permitido, o mode no es válido

Obtener sincronización de audiencia

GET /audience-syncs/{config_id}

Devuelve una configuración de sincronización individual por ID.

Ejemplo

Ventana de terminal
curl "https://be.graph8.com/api/v1/audience-syncs/12" \
  -H "Authorization: Bearer $API_KEY"

Errores

EstadoSignificado
404Configuración de sincronización no encontrada

Actualizar sincronización de audiencia

PATCH /audience-syncs/{config_id}

Actualización parcial. Envíe únicamente los campos que desea modificar.

Cuerpo de la solicitud

CampoTipoDescripción
modestringmirror o append_only
refresh_cadence_hoursinteger0-720
is_activebooleanPausar o reanudar sin eliminar
suppression_list_idsinteger[]Reemplaza el conjunto de listas de supresión

Ejemplo

Ventana de terminal
curl -X PATCH "https://be.graph8.com/api/v1/audience-syncs/12" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Eliminar sincronización de audiencia

DELETE /audience-syncs/{config_id}

Eliminación lógica. La audiencia no se elimina de la plataforma publicitaria; graph8 simplemente deja de sincronizarla.

Respuesta

{ "data": { "status": "deleted", "id": 12 } }

Activar sincronización de audiencia

POST /audience-syncs/{config_id}/trigger

Ejecuta la sincronización de inmediato, fuera de su cadencia programada. Devuelve el resultado de la sincronización (recuentos de miembros agregados y eliminados).

Ejemplo

Ventana de terminal
curl -X POST "https://be.graph8.com/api/v1/audience-syncs/12/trigger" \
  -H "Authorization: Bearer $API_KEY"

Errores

EstadoSignificado
500La plataforma publicitaria subyacente devolvió un error. Consulte /runs o /errors para ver el mensaje

Listar ejecuciones de sincronización

GET /audience-syncs/{config_id}/runs

Devuelve las ejecuciones recientes de una configuración (tanto exitosas como fallidas).

Parámetros de consulta

ParámetroTipoPredeterminadoDescripción
limitinteger20Máximo de ejecuciones a devolver (1-100)

Respuesta

{
  "data": [
    {
      "id": 4521,
      "started_at": "2026-04-15T08:00:00Z",
      "finished_at": "2026-04-15T08:00:14Z",
      "status": "success",
      "members_added": 12,
      "members_removed": 3,
      "total_members": 1450,
      "error_message": null
    }
  ]
}

Listar errores de sincronización

GET /audience-syncs/{config_id}/errors

Misma estructura que /runs, filtrada por status = "failed". Use este endpoint para mostrar fallas en su panel.

Parámetros de consulta

ParámetroTipoPredeterminadoDescripción
limitinteger20Máximo de errores a devolver (1-100)

Respuesta

{
  "data": [
    {
      "id": 4520,
      "started_at": "2026-04-15T07:30:00Z",
      "error_message": "Meta API: invalid access token",
      "details": { "config_id": 12, "status": "failed" }
    }
  ]
}