> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musixmatch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration guide

> Order of Distribution API calls when an artist signs in with their Musixmatch account

Follow this order when an artist signs in with their own Musixmatch account. This page is the flow only. Parameters and responses stay on the linked endpoint pages.

Every Distribution API call goes to `https://api.musixmatch.com/ws/1.1/` with `apikey` and `user_id` query parameters.

Tracks are always identified by ISRC, not by `commontrack_id`.

## Call order

```mermaid theme={null}
flowchart TD
  A[Get credentials] --> B[Artist signs in]
  B --> C[Exchange the code for tokens]
  C --> D[Read sub from token-metadata]
  D --> E[Activate the subscription]
  E --> F[Request an upload URL]
  F --> G[PUT the release ZIP]
  G --> H[Create the delivery]
  H --> I[Poll until the delivery succeeds]
  I --> J{Prepare lyrics}
  J -->|No lyrics| K[Transcribe and poll]
  J -->|Lyrics and sync| L[Sync and poll]
  J -->|Lyrics only| M[Publish with lyrics.post]
  K --> M
  L --> M
  M --> N[Poll until publishing succeeds]
  N --> O[Lyrics are live in the catalog]
```

**1. Get your credentials**

Contact [apisupport@musixmatch.com](mailto:apisupport@musixmatch.com) for the API key.

Send Musixmatch your `redirect_uri`. Musixmatch issues a `client_id`, then a `client_secret`.

**2. Authenticate the artist and activate the subscription**

The artist signs in with their own Musixmatch account through the [Authorization Code flow](https://docs.musixmatch.com/enterprises/authentication.md#authorization-code-flow). Exchange the authorization code for tokens. Those calls use `https://connect.musixmatch.com`, as described on that page.

Call [`POST /oauth/token-metadata`](https://docs.musixmatch.com/enterprises/authentication#retrieving-the-musixmatch-user-id) and use the returned `sub` as `user_id` on every Distribution API call. Always store the latest `refresh_token`.

Call [`distribution.subscription.post`](https://docs.musixmatch.com/enterprises/distribution/api/subscriptions/distribution-subscription-post) with `plan_id`, `partner_user_id`, and `artists`. Uploads are refused without an active subscription.

**3. Deliver the release**

Deliver the release even when the ISRC already exists on Musixmatch. The delivery provides the audio.

Call [`distribution.files.post`](https://docs.musixmatch.com/enterprises/distribution/api/deliveries/distribution-files-post). It returns `upload_url` and `file_id`. HTTP PUT the release ZIP (ERN and audio) to `upload_url` with the header `Content-Type: application/zip`. That header is required.

Call [`distribution.delivery.post`](https://docs.musixmatch.com/enterprises/distribution/api/deliveries/distribution-delivery-post) with `file_id`. Poll [`distribution.delivery.get`](https://docs.musixmatch.com/enterprises/distribution/api/deliveries/distribution-delivery-get) until `status` is `success`.

**4. Prepare the lyrics**

Pick one option.

**No lyrics.** Call [`distribution.transcription.post`](https://docs.musixmatch.com/enterprises/distribution/api/transcriptions/distribution-transcription-post) with `isrc`. Sending `language` is recommended. Poll [`distribution.transcription.get`](https://docs.musixmatch.com/enterprises/distribution/api/transcriptions/distribution-transcription-get) until `status` is `success`. On success the response includes `lyrics` and `subtitle`.

**Lyrics and sync.** Call [`distribution.sync.post`](https://docs.musixmatch.com/enterprises/distribution/api/sync/distribution-sync-post) with `isrc`, `lyrics`, and `language`. Poll [`distribution.sync.get`](https://docs.musixmatch.com/enterprises/distribution/api/sync/distribution-sync-get) until `status` is `success`. On success the response includes `subtitle`.

**Lyrics, no sync.** Continue to the next step.

**5. Publish the lyrics**

&#x20;This call is mandatory. A transcription or sync request does not publish anything by itself. After it completes, send the result with [`distribution.lyrics.post`](https://docs.musixmatch.com/enterprises/distribution/api/lyrics/distribution-lyrics-post): `isrc`, `lyrics`, and `subtitle` when you have one. Pass `subtitle` as-is, in LRC. `lyrics` is required. If you already have lyrics and skipped transcription and sync, send those lyrics with the same call. Poll [`distribution.lyrics.get`](https://docs.musixmatch.com/enterprises/distribution/api/lyrics/distribution-lyrics-get) until `status` is `success`. The lyrics are then live in the catalog.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.