Skip to main content
Use the Soundlinks API to discover soundlinks that belong to your organization and are not tied to a Soundlink-funded campaign. Those soundlinks do not appear in GET /v1/campaigns. For paid campaigns, use Syncing campaigns. For the monthly Self-Serve plan and listener cap, see Self-Serve. Requires soundlinks:read. See Authentication. To create, archive, or send a test event, see Creating soundlinks.
Existing API keys keep the scopes they were minted with. Create a new key and add soundlinks:read to call these routes.
Campaign-linked soundlinks are the campaign’s underlying resource. List and detail them with the Campaigns API. A campaign-backed soundlinkId on these routes returns 404. Missing soundlinks:read returns 403 insufficient_scope. See Errors for the full list. GET /v1/soundlinks Includes archived rows (status: archived). Supports pagination: sortBy is createdAt. soundlinkId is a URL-safe string — the same ID in the public sndl.ink URL — not a campaign UUID.
Walk pages until pagination.page >= pagination.totalPages. GET /v1/soundlinks/{soundlinkId} Returns catalog fields plus autoFollow, artistIdFollow, metaPixelId, tiktokPixelId, appleMusicUrl, youtubeMusicUrl, attributionEnabled, and streamValueEventEnabled. appleMusicUrl and youtubeMusicUrl are the stored URLs, or null when unset. An Apple album share-sheet link is returned as the canonical song URL. attributionEnabled is false when the landing page skips Spotify login. streamValueEventEnabled is true when Soundlink Stream Value was turned on at creation. List items do not include appleMusicUrl, youtubeMusicUrl, attributionEnabled, or streamValueEventEnabled. Archived soundlinks still appear (status: archived). Unknown, cross-org, or campaign-linked IDs return 404. The Meta CAPI token is never returned. Use the soundlinkId from the list response in all /metrics/* paths.

Typical sync flow

  1. Daily: GET /v1/soundlinks — upsert catalog
  2. Daily: soundlink metrics per active soundlink

Organization scope

Your organization is determined only from the API key (or OAuth token). You never pass an organization id in query params.
  • Soundlink list and detail JSON uses organizationId.
  • Metrics JSONL / warehouse rows use account_id for the same organization UUID. Join catalog to metrics on soundlink_id.
Node.js: soundlink.soundlinks.list — TypeScript SDK. DuckDB or BigQuery: warehouse connector.

Next

Creating soundlinks · Warehouse connector · Soundlink metrics → API Reference