Skip to main content
POST

Authorizations

Authorization
string
header
required

Pass your Soundlink sk_* API key as a Bearer token: Authorization: Bearer sk_<prefix>_<token> (not an OAuth token; see oauthBearer for that). Accepted on all Public API operations. Send only one Authorization header per request.

Headers

Idempotency-Key
string
required

A unique string identifying this request, used to safely retry write operations (campaign create/stop/budget, soundlink create) without repeating side effects. Required on every request that references this parameter. Reusing this key with an unchanged request body replays the original response; reusing it with a different body returns 409 idempotency_key_conflict. Keys are honored for 24 hours.

Required string length: 1 - 255

Body

application/json
name
string
required

Human-readable soundlink name.

Minimum string length: 1
spotifyUrl
string<uri>
required

HTTPS Spotify track or playlist URL. Album, artist, and URI (spotify:track:...) forms are rejected. An optional intl-xx path segment is accepted. Query strings are stripped before lookup. The resource must currently exist on Spotify.

Example:

"https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl"

autoFollow
boolean
default:false

When true, fans who connect Spotify from the landing page are asked to follow the track artist (artistIdFollow, or the track's primary artist when omitted), or the playlist itself when spotifyUrl is a playlist. Defaults to false.

artistIdFollow
string

Spotify artist ID used for auto-follow on track links. Optional. Persisted even when autoFollow is false. For multi-artist tracks, pass the artist that should be followed. Ignored when spotifyUrl is a playlist.

metaPixelId
string

Meta pixel ID. Send with metaConversionAccessToken to save or rotate the token (unchanged). Or send metaPixelId alone to reuse a pixel the organization already saved. Omit both to skip Meta tracking. Never applies an org default.

metaConversionAccessToken
string
write-only

Meta Conversions API access token. Write-only: accepted on create, never returned on GET. When present, metaPixelId is required.

appleMusicUrl
string<uri>

Optional HTTPS Apple Music URL. Accepted shapes: a song (/song/{slug}/{id}), a catalog playlist (pl.), a library playlist (pl.u-), or an album share-sheet link with ?i={songId} (stored as the canonical song URL). Host must be music.apple.com with a two-letter storefront. Songs and catalog playlists are verified in that storefront; missing content returns 400 invalid_request. Provider outages or rate limits warn and allow create. Library playlists are format-checked only. Omit to leave Apple Music unset.

Example:

"https://music.apple.com/us/song/anti-hero/1645937493"

youtubeMusicUrl
string<uri>

Optional HTTPS YouTube Music URL. Accepted shapes: a song (music.youtube.com/watch?v=…, youtube.com/watch?v=…, or youtu.be/…) or a playlist (…/playlist?list=…). Shorts, live, channel, and browse links are rejected. A video or playlist that does not exist on YouTube returns 400 invalid_request. Quota, auth, or upstream failures warn and allow create. Omit to leave YouTube Music unset.

Example:

"https://music.youtube.com/watch?v=dQw4w9WgXcQ"

attributionEnabled
boolean
default:true

When false, the landing page skips Spotify login and only tracks the landing-page click. Omit or send true to keep attribution. Cannot be combined with autoFollow: true.

streamValueEventEnabled
boolean
default:false

When true, Soundlink sends a Meta conversion event named "Soundlink Stream Value" for attributed streams on this soundlink. Requires the organization to be enabled for Soundlink Stream Value, otherwise the request returns 403 stream_value_not_enabled. Cannot be combined with attributionEnabled: false. Omit or send false to leave it off. Can only be set at creation. Events are sent only when the soundlink has a Meta pixel and conversion access token.

Response

Soundlink created

data
object
required
meta
object
required