How it works
The integration is built around three resources: subscriptions, deliveries, and lyrics. A subscription event notifies Musixmatch when a user subscribes to or unsubscribes from a plan on your platform. Musixmatch maps your plan identifiers to the corresponding Musixmatch plans and grants or revokes access accordingly. Activating a subscription also claims the user’s artists, and an active subscription is required before the user can deliver releases. A delivery is a release package — a ZIP file containing the ERN metadata and audio files for one release. Submitting a delivery makes the release known to Musixmatch and gives us the audio we need to generate time-synced lyrics. A lyrics submission publishes plain-text lyrics for a track, identified by ISRC.lyrics is required on distribution.lyrics.post. To have Musixmatch generate the lyrics, call distribution.transcription.post first, then send that result with distribution.lyrics.post. The transcription request does not publish them.
The two steps are independent by design — a delivery can arrive before lyrics are ready, and lyrics can be submitted as soon as they exist, even before release date. The only requirement is that a delivery containing the audio must be processed before AI generation can run.
1
Register as a partner
Contact apisupport@musixmatch.com to receive your API key,
client_id, client_secret, and partner base URL. You will also provide your redirect_uri for the OAuth flow.2
Authenticate
Use the Authorization Code flow to authenticate an artist in your app and retrieve their Musixmatch user ID.
3
Manage subscriptions
Call
POST /ws/1.1/distribution.subscription.post when a user subscribes to a plan on your platform to activate their Musixmatch plan, with your partner_user_id and at least one artist identifier (Spotify artist ID, iTunes artist ID, or your internal artist ID) in artists. Musixmatch claims those artists for the user. An active subscription is required before you can open an upload slot. Call POST /ws/1.1/distribution.subscription.delete when they unsubscribe to revoke access. Call GET /ws/1.1/distribution.subscription.get to list the active subscriptions you created for a user.4
Deliver the release
Call
POST /ws/1.1/distribution.files.post to get a pre-signed upload URL and a file_id. Upload the release ZIP to that URL via HTTP PUT, sending the header Content-Type: application/zip (required, otherwise the delivery fails). Then call POST /ws/1.1/distribution.delivery.post with the file_id. Musixmatch creates the delivery, returning a delivery_id. Poll GET /ws/1.1/distribution.delivery.get until the status is success.5
Submit lyrics
Call
POST /ws/1.1/distribution.lyrics.post with the track ISRC and the plain-text lyrics. lyrics is required. A transcription is a separate request: call POST /ws/1.1/distribution.transcription.post, then poll GET /ws/1.1/distribution.transcription.get until status is success. Send the returned lyrics, and subtitle when it is present, with distribution.lyrics.post. The transcription request does not publish anything by itself. Poll GET /ws/1.1/distribution.lyrics.get until the status is success, at which point the lyrics are indexed in the catalog. The integration guide has the full call order.6
Sync lyrics to audio
Call
POST /ws/1.1/distribution.sync.post with the track ISRC, the plain-text lyrics as sung in the recording, and their language (ISO 639-1). Musixmatch aligns the lyrics to the delivered audio and returns a sync_request_id. Poll GET /ws/1.1/distribution.sync.get until the status is success. The response MAY then include synced lyrics timing in LRC format (subtitle), which can be omitted. You can pass that subtitle value straight into POST /ws/1.1/distribution.lyrics.post to publish the synced lyrics into the catalog alongside the plain-text lyrics.Base URL
All Distribution API endpoints are served under:/ws/1.1/.
Authentication
All Distribution API endpoints require your API key, passed as theapikey query parameter (e.g. ?apikey=YOUR_API_KEY). Endpoints that act on behalf of an artist additionally require a user_id query parameter with the artist’s Musixmatch user ID, which you retrieve by introspecting the user’s access token from the Authorization Code flow.