Artist IDs Dsp Availabilities

Manage artist identifications on streaming platforms (Spotify, Apple Music, Facebook)

Resource Overview

Artist DSP Availabilities link artists to their profiles on Digital Service Providers (DSPs) like Spotify, Apple Music, and Facebook. This enables proper artist identification and content matching across platforms.

Base Endpoint
/artist-dsp-availabilities
Resource Type
artist-dsp-availabilities
User Scope
Owner-restricted

Allowed DSPs

Artist identification is only allowed for the following platforms:

DSP ID external-artist-id Format external-artist-url Format
Spotify 1 spotify:artist:{id} https://open.spotify.com/artist/{id}
Apple Music 4 Numeric ID https://music.apple.com/artist/{id}
Facebook 12 Numeric ID https://www.facebook.com/{id}

Automatic Facebook Library Replication

When you create, update, or delete a Facebook (DSP 12) identification, the system automatically replicates the action to Facebook Library (DSP 16). You only need to manage the Facebook entry.

Schema

Required Attributes

Field Type Validation Description
external-artist-id string Required · up to 500 characters · DSP-specific format Artist identifier on the DSP platform
external-artist-url string Required · valid URL · DSP-specific format · ignored and stored as null with Spotify NEW Artist profile URL on the DSP platform

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last update timestamp

Relationships

Relationship Related Resource Description Required
artist artists The artist this identification belongs to Yes
dsp dsps The DSP platform (Spotify, Apple, Facebook) Yes

Validation Rules by DSP

S

Spotify (DSP 1)

external-artist-id
spotify:artist:{alphanumeric, max 30 chars}
external-artist-url
https://open.spotify.com/artist/{id}
Example: spotify:artist:4q3ewBCX7sLwd24euuV69X
Brand-new artist: NEW

For an artist with no Spotify profile yet, send external-artist-id as exactly NEW (uppercase). The URL is not required: it is stored as null, even when one is sent. NEW is replaced with the real Spotify ID once it is available.

An artist can be marked as NEW only when:

  • it has no Spotify profile linked, and
  • it does not appear, in any role, on a release that was already sent.

Updating a row that already holds NEW to NEW again is always accepted. Reads may return "external-artist-id": "NEW" with "external-artist-url": null.

A

Apple Music (DSP 4)

external-artist-id
Numeric only
external-artist-url
https://music.apple.com/artist/{id}
Example: 1126808565
F

Facebook (DSP 12)

external-artist-id
Numeric only
external-artist-url
https://www.facebook.com/{id}
Example: 112233445566778899

List Artist DSP Availabilities

GET /artist-dsp-availabilities 
GET /artist-dsp-availabilities
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • filter[id] - Filter by ID(s)
  • filter[artist-id] - Filter by artist
  • filter[dsp-id] - Filter by DSP

Other Parameters

  • include=artist - Include artist data
  • include=dsp - Include DSP data
  • include=artist,dsp - Include both
  • sort - Sort by field

Success Response

200 OK 
{
  "data": [
    {
      "type": "artist-dsp-availabilities",
      "id": "1",
      "attributes": {
        "external-artist-id": "spotify:artist:4q3ewBCX7sLwd24euuV69X",
        "external-artist-url": "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
        "created-at": "2024-01-01T10:00:00Z",
        "updated-at": "2024-01-01T10:00:00Z"
      },
      "relationships": {
        "artist": {
          "links": { "related": "/artist-dsp-availabilities/1/artist" }
        },
        "dsp": {
          "links": { "related": "/artist-dsp-availabilities/1/dsp" }
        }
      }
    }
  ]
}

Create Artist DSP Availability

POST /artist-dsp-availabilities

Spotify Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "spotify:artist:4q3ewBCX7sLwd24euuV69X",
      "external-artist-url": "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "1" }
      }
    }
  }
}

Spotify Example: brand-new artist

POST /artist-dsp-availabilities
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "NEW"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "1" }
      }
    }
  }
}

The created resource answers "external-artist-id": "NEW" and "external-artist-url": null.

Apple Music Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "1126808565",
      "external-artist-url": "https://music.apple.com/artist/1126808565"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "4" }
      }
    }
  }
}

Facebook Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "112233445566778899",
      "external-artist-url": "https://www.facebook.com/112233445566778899"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "12" }
      }
    }
  }
}

Success Response

201 Created

Update Artist DSP Availability

PATCH /artist-dsp-availabilities/{id} 
{
  "data": {
    "type": "artist-dsp-availabilities",
    "id": "1",
    "attributes": {
      "external-artist-id": "spotify:artist:6vWDO969PvNqNYHIOW5v0m",
      "external-artist-url": "https://open.spotify.com/artist/6vWDO969PvNqNYHIOW5v0m"
    }
  }
}

Success Response

200 OK

Delete Artist DSP Availability

DELETE /artist-dsp-availabilities/{id} 
DELETE /artist-dsp-availabilities/1
Authorization: Bearer {token}

Success Response

204 No Content

Error Responses

DSP Not Allowed

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Artist identification is only allowed for Spotify, Apple, and Facebook.",
    "status": "422"
  }]
}

Invalid Spotify ID Format

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Spotify artist ID must be in format: spotify:artist:{id} where id is alphanumeric (max 30 characters).",
    "status": "422"
  }]
}

Spotify NEW: Profile Already Linked

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "This artist already has a Spotify profile linked, so they are not new on Spotify. Keep their Spotify profile link instead of marking them as new.",
    "source": { "pointer": "/data/attributes/external-artist-id" },
    "status": "422"
  }]
}

Spotify NEW: Already on a Sent Release

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "This artist already appears on a release sent to distribution, so they are not new on Spotify. Paste their Spotify profile link instead of marking them as new.",
    "source": { "pointer": "/data/attributes/external-artist-id" },
    "status": "422"
  }]
}

Invalid Apple/Facebook ID Format

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Apple artist ID must be numeric.",
    "status": "422"
  }]
}

URL Does Not Match ID

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Spotify artist URL must be: https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
    "status": "422"
  }]
}

Duplicate Entry

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "This artist already has an identification for this DSP. Use PATCH to update it.",
    "status": "422"
  }]
}

Unauthorized Access

403 Forbidden 
{
  "errors": [{
    "detail": "You are not authorized to perform this action.",
    "status": "403"
  }]
}