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, max:500, DSP-specific format Artist identifier on the DSP platform
external-artist-url string required, url, DSP-specific format 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 Type Related Resource Description Required
artist BelongsTo artists The artist this identification belongs to Yes
dsp BelongsTo 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
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" }
      }
    }
  }
}

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"
  }]
}

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"
  }]
}