Introduction

Welcome to the Base for Music Partner documentation!



API_URL='https://partners.api.baseformusic.com';

SWAGGER_DOCUMENTATION='https://partners.api.baseformusic.com/#api';



const API_URL = 'https://partners.api.baseformusic.com';

const SWAGGER_DOCUMENTATION = 'https://partners.api.baseformusic.com/#api';

The Base for Music Partner API offers a powerful set of tools for creating and tracking marketing campaigns from your website or application. Through this API, all generated campaigns are optimised and tracked by Base for Music's administrator solution, allowing you to obtain maximum results. By integrating our tools, you'll make it easy for your users to launch effective marketing campaigns to promote their music.

Key Features

Ads campaign: Create and customise marketing campaigns tailored to your user's objectives. You can create campaigns with different ad formats on following ad networks: Spotify Ad Studio, Google Ads, Meta, TikTok for Business. You can then select or import promotional content, define the target audience to be reached and select a budget to launch a music promotion campaign.
Smartlinks: Create and manage smartlinks to promote music on various platforms. Smartlinks are a powerful tool for promoting music on social networks, streaming platforms, and other online channels. They allow you to track the performance of your campaigns and optimise them for better results.
Shared reporting: Benefit from a reporting function that lets you share campaign statistics with yours users. Each report is adapted to the advertising format used, and offers the user a simplified interface for understanding the impact of their campaign according to their objective. You can create a unique URL for each campaign and share it with your user. Shared reports can be customised with your brand colours and logo.
Real-Time Analytics: Allow yours users to track campaign performance through real-time statistics. The API provides valuable information on all general campaign data (impression, reach, etc.) as well as data on the audiences generating results (center of interest, location, etc.). This feature also enables tracking of all the advertising optimization work done by our administrator solution.
External content API: Benefit from our various connectors to easily obtain the elements needed to launch a campaign (Drive API, Youtube video ID, Youtube Search, Spotify page ID, Spotify Search, etc..).
Widget integration: Integrate Base for Music's marketing features into your website or application simply by using our widgets to give your users the opportunity to promote their music.

Authentication

Get started

To get started with the Base for Music Partner API, please sign up for an API key by contacting us at team@baseformusic.fr


# Contact team@baseformusic.fr to get your clientId and clientSecret

PARTNER_TOKEN=$(echo -n "$client_id:$client_secret" | base64)


// Contact team@baseformusic.fr to get your clientId and clientSecret


const PARTNER_TOKEN = new Buffer.from(client_id + ':' + client_secret).toString('base64')

This key will serve as your authentication token, granting access to the API's functionalities securely.

Authorization

The Base for Music Partner API supports OAuth 2.0 for secure authentication. When making requests to the API, you will need to include your API key in the Authorization header. This API key serves as your access token, granting permission to interact with the API on behalf of your account.

REQUEST SAMPLE


#!/bin/bash

client_id="VotreClientID"
client_secret="VotreClientSecret"
API_URL="https://partners.api.baseformusic.com/partners-api/token"

PARTNER_TOKEN=$(echo -n "$client_id:$client_secret" | base64)

curl -X GET "$API_URL/token" \
  -H "Authorization: Basic $PARTNER_TOKEN" \
  --data-urlencode "grant_type=client_credentials"


// Contact team@baseformusic.fr to get your partnerToken
const PARTNER_TOKEN = new Buffer.from(client_id + ':' + client_secret).toString('base64')

fetch(API_URL + `/token`, {
  method: "GET",
  headers: {
    Authorization: 'Basic' + PARTNER_TOKEN,
  },
    form: {
    grant_type: 'client_credentials'
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

HTTP Request

GET https://partners.api.baseformusic.com/partners-api/token

Parameter	Default	Description
token	`partnerToken`	client_id:client_secret in base64

RESPONSE SAMPLE


{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XXXXXX.6KuKQS--bngGOmseavD7CdSOlp5GawUD5hEVKBGrkX4"
}

partnerToken The field must have the format: Authorization: Basic base64 encoded client_id:client_secret

Security

To ensure the security of your account and data, it is crucial to keep your API key confidential and avoid sharing it publicly. Treat your API key as sensitive information and only share it with authorized personnel who need access to the API for development or integration purposes.

Please refer to the API documentation for detailed instructions on how to obtain and use your API key for authentication. If you have any questions or concerns about the authentication process, feel free to contact our support team at team@baseformusic.fr. We are here to assist you with a smooth and secure integration experience.

Campaigns

Create a campaign

REQUEST SAMPLE


curl -X 'POST' \
  'https://partners.api.baseformusic.com/partners-api/campaigns' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  externalUserId: '2b9e689a-d57a-4c54-b0a9-772c77993f7e',
  budget: 50,
  startDate: '2023-07-24T15:37:12.362Z',
  playbookContent: '[Object PlaybookContent]',
  playbookName: 'instagramFollowersMeta',
}'



const API_URL = 'https://partners.api.baseformusic.com/partners-api/campaigns';
const accessToken = 'ACCESS_TOKEN';

const requestData = {
  externalUserId: '2b9e689a-d57a-4c54-b0a9-772c77993f7e',
  budget: 50,
  startDate: '2023-07-24T15:37:12.362Z',
  playbookContent: '[Object PlaybookContent]',
  playbookName: 'instagramFollowersMeta',
};

fetch(API_URL, {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestData),
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

RESPONSE SAMPLE:


{
  "id": "6f89d7b4-0682-4b73-be80-cbfb810e7b80",
  "config": {
    "profile": {
      "artist": {
        "id": "6eukzxakkcvih0ku9w2n3v"
      }
    },
    "content": {
      "auto": {
        "track": {
          "id": "3n3ppam7vgava1iaruc9lp"
        }
      }
    },
    "redirection": {
      "id": "3n3ppam7vgava1iaruc9lp",
      "resourceType": "track"
    },
    "targeting": {
      "auto": {
        "musicalGenre": "hiphop",
        "language": "all"
      }
    }
  },
  "budget": 2000,
  "startDate": "2023-09-13T14:48:14.518Z",
  "endDate": "2023-10-28T14:48:14.518Z",
  "reportingURL": "https://baseformusic.com/apps/reporting/kKBLj4cp1W",
  "externalUserId": "string",
  "playbook": "spotifyEngagementAdStudio",
  "createdAt": "2023-09-13T14:48:14.514Z",
  "btobName": null,
}

HTTP Request

POST https://partners.api.baseformusic.com/partners-api/campaigns

Body Parameters

Parameter	Description
externalUserId	User ID in your system
budget	Campaign budget between 50€ and 2000€
startDate	Start date of campaign
playbookName	Campaign playbookName (specific to each playbook) see Playbook section.
playbookContent	Campaign content (specific to each playbook) see Playbook Content section.

Get a Specific Campaign

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/partners-api/campaigns/614fe44b-e3d8-4f61-b646-0a59ad190ee7' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN'


const ID_CAMPAIGN = '614fe44b-e3d8-4f61-b646-0a59ad190ee7';
const API_URL = 'https://partners.api.baseformusic.com/partners-api/campaigns/' + ID_CAMPAIGN;  


fetch(API_URL, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

RESPONSE SAMPLE


{
  "id": "6f89d7b4-0682-4b73-be80-cbfb810e7b80",
  "config": {
    "profile": {
      "artist": {
        "id": "6eukzxakkcvih0ku9w2n3v"
      }
    },
    "content": {
      "auto": {
        "track": {
          "id": "3n3ppam7vgava1iaruc9lp"
        }
      }
    },
    "redirection": {
      "id": "3n3ppam7vgava1iaruc9lp",
      "resourceType": "track"
    },
    "targeting": {
      "auto": {
        "musicalGenre": "hiphop",
        "language": "all"
      }
    }
  },
  "budget": 2000,
  "startDate": "2023-09-13T14:48:14.518Z",
  "endDate": "2023-10-28T14:48:14.518Z",
  "reportingURL": "https://baseformusic.com/apps/reporting/kKBLj4cp1W",
  "externalUserId": "string",
  "playbook": "spotifyEngagementAdStudio",
  "createdAt": "2023-09-13T14:48:14.514Z",
  "btobName": null,
}

This endpoint retrieves a specific campaign.

HTTP Request

GET https://partners.api.baseformusic.com/partners-api/campaign/<ID_CAMPAIGN>

Query Parameters

Parameter	Description
ID	The ID of the campaign to retrieve

Response

Parameter	Description
id	Campaign ID
config	Campaign config ( see playbookContent reporting )
externalUserId	User ID in your system
playbookName	Campaign playbook name
budget	Campaign budget
startDate	Campaign start date
endDate	Campaign end date
createdAt	Campaign created at date
progress	Campaign progress
reportingURL	Campaign reporting URL reporting

Response sample

{ "id": "614fe44b-e3d8-4f61-b646-0a59ad190ee7", "nameOrder": "#4510", "budget": 210, "playbookName": "spotifyEngagementAdStudio", "playbookContent": "[]", "startDate": "2023-07-24T00:00:00.000Z", "endDate": "2023-08-09T00:00:00.000Z", "progress": 100, }

Get All Campaigns

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/partners-api/campaigns/614fe44b-e3d8-4f61-b646-0a59ad190ee7' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN'


const ID_CAMPAIGN = '614fe44b-e3d8-4f61-b646-0a59ad190ee7';
const API_URL = 'https://partners.api.baseformusic.com/partners-api/campaigns/';  


fetch(API_URL, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

RESPONSE SAMPLE:


[
  {
    [Object campaign]
  }
  {
    [Object campaign]
  }
]

This endpoint retrieves all campaigns.

HTTP Request

GET https://partners.api.baseformusic.com/partners-api/campaigns

Query Parameters

Parameter	Description
externalUserId	The ID of the user in your system

Response

The response is an array of campaign objects. Each campaign object has the following properties:

Parameter	Description
id	Campaign ID
nameOrder	Campaign name ( generate by baseformusic )
budget	Campaign budget
startDate	Campaign start date
endDate	Campaign end date
progress	Campaign progress
reportingURL	Reporting id
playbookName	Campaign playbook name
content	Campaign playbook content

Smartlinks

Create a smartlink

REQUEST SAMPLE


curl -X 'POST' \
  'https://partners.api.baseformusic.com/partners-api/smartlinks' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "externalUserId": "1bfd4ae9",
  "defaultCoverUrl": "https://placehold.co/200x200",
  "name": "Smart Link 12",
  "title": "Sauvage",
  "description": "Dorian",
  "snapchatPixelId": "12314241432",
  "metaPixelId": "12314241432",
  "googleAnalyticsId": "12314241432",
  "releaseDate": "2026-06-05T13:50:37.622Z",
  "type": "PRESAVE"
}'



const API_URL = 'https://partners.api.baseformusic.com/partners-api/smartlinks';
const accessToken = 'ACCESS_TOKEN';

const requestData = {
  externalUserId: '1bfd4ae9',
  defaultCoverUrl: 'https://placehold.co/200x200',
  name: 'Smart Link 12',
  title: 'Sauvage',
  description: 'Dorian',
  snapchatPixelId: '12314241432',
  metaPixelId: '12314241432',
  googleAnalyticsId: '12314241432',
  releaseDate: '2026-06-05T13:50:37.622Z',
  type: 'PRESAVE',
};

fetch(API_URL, {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestData),
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

RESPONSE SAMPLE:


{
  "id": "ae7096ae-f50a-4a6b-be11-0d59d927e2c5",
  "name": "Smart Link 12",
  "title": "Sauvage",
  "description": "Dorian",
  "snapchatPixelId": "12314241432",
  "metaPixelId": "12314241432",
  "googleAnalyticsId": "12314241432",
  "shortId": "h74JusEW",
  "defaultCoverUrl": "https://placehold.co/200x200",
  "releaseDate": "2026-06-05T13:50:37.622Z",
  "externalUserId": "1bfd4ae9",
  "type": "PRESAVE",
  "customCanvasUrl": null,
  "defaultCanvasUrl": null,
  "coverUrl": null,
  "spotifyUri": null,
  "bioLinkData": null,
  "userId": null,
  "selectedCover": "default",
  "createdAt": "2024-07-24T15:39:45.009Z",
  "links": [
    {
      "id": "4891f4c7-ee35-4edc-9fb6-91002bff1161",
      "linkType": "SPOTIFY",
      "url": "",
      "position": 0,
      "presave": true,
      "widgetType": "PRESAVE"
    },
    {
      "id": "6a539e0b-51eb-4818-86e2-7a9295bb05c7",
      "linkType": "DEEZER",
      "url": "",
      "position": 1,
      "presave": true,
      "widgetType": "PRESAVE"
    },
    {
      "id": "ee7fa8b1-6bda-4714-9a26-a173cd6164ff",
      "linkType": "APPLE_MUSIC",
      "url": "",
      "position": 2,
      "presave": true,
      "widgetType": "PRESAVE"
    },
    {
      "id": "5ccff403-b63a-4b74-9ba9-2c687546ccbd",
      "linkType": "CUSTOM",
      "url": "",
      "position": 3,
      "presave": true,
      "widgetType": "PRESAVE"
    }
  ]
}

HTTP Request

POST https://partners.api.baseformusic.com/partners-api/smartlinks

Body Parameters

Parameter	Type	Description	Optional	Validation
defaultCoverUrl	string	The default cover URL for the smart link	No	Must be a valid URL
name	string	The name of the smart link	Yes
title	string	The title of the smart link	No
description	string	The description of the smart link	No
snapchatPixelId	string	The Snapchat Pixel ID	Yes
metaPixelId	string	The Meta (Facebook) Pixel ID	Yes
googleAnalyticsId	string	The Google Analytics ID	Yes
externalUserId	string	The external user ID	No
releaseDate	string (ISO 8601)	The release date for presave links	Yes	Format: YYYY-MM-DDTHH:MM:SS.sssZ; required for PRESAVE type
type	enum (PRESAVE, MUSIC, FAN, BIO)	The type of smart link	No	Must be one of the defined enum values
spotifyUri	string	The Spotify URI for music links	Yes	Format: spotify:resource:id; required for MUSIC type

Response

Parameter	Type	Description
id	string (UUID)	The unique identifier for the smart link
name	string	The name of the smart link
title	string	The title of the smart link
description	string	The description of the smart link
snapchatPixelId	string	The Snapchat Pixel ID
metaPixelId	string	The Meta (Facebook) Pixel ID
googleAnalyticsId	string	The Google Analytics ID
shortId	string	The shortened identifier for the smart link
defaultCoverUrl	string	The default cover URL for the smart link
releaseDate	string (ISO 8601)	The release date for presave links
externalUserId	string	The external user ID
type	enum (PRESAVE, MUSIC, FAN, BIO)	The type of smart link
customCanvasUrl	string	The custom canvas URL
defaultCanvasUrl	string	The default canvas URL
coverUrl	string	The cover URL
spotifyUri	string	The Spotify URI for music links
bioLinkData	object	The bio link data
userId	string (UUID)	The user ID
selectedCover	string	The selected cover (e.g., 'default')
createdAt	string (ISO 8601)	The creation timestamp
links	array of link objects	The list of associated links

Links Object Detailed Information:

Parameter	Type	Description
id	string (UUID)	The unique identifier for the link
linkType	enum (CUSTOM, SPOTIFY, YOUTUBE, YOUTUBE_MUSIC, SOUNDCLOUD, DEEZER, APPLE_MUSIC, PRIME_MUSIC, FNAC, TIDAL, BEATPORT, MIXCLOUD, QUOBUZZ, BANDCAMP, NAPSTER)	The type of the link (e.g., 'SPOTIFY')
url	string	The URL of the link
position	number	The position of the link
presave	boolean	Indicates if the link is a presave link
widgetType	string	The widget type of the link (e.g., 'PRESAVE')

Get a Specific smartlink

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/partners-api/smartlinks/ae7096ae-f50a-4a6b-be11-0d59d927e2c5' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer TOKEN'


const ID_SMARTLINK = 'ae7096ae-f50a-4a6b-be11-0d59d927e2c5';
const API_URL = 'https://partners.api.baseformusic.com/partners-api/smartlinks/' + ID_SMARTLINK;  


fetch(API_URL, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

RESPONSE SAMPLE


{
  "id": "ae7096ae-f50a-4a6b-be11-0d59d927e2c5",
  "name": "Smart Link 12",
  "title": "Sauvage",
  "description": "Dorian",
  "snapchatPixelId": "12314241432",
  "metaPixelId": "12314241432",
  "googleAnalyticsId": "12314241432",
  "shortId": "h74JusEW",
  "defaultCoverUrl": "https://placehold.co/200x200",
  "customCanvasUrl": null,
  "defaultCanvasUrl": null,
  "coverUrl": null,
  "selectedCover": "default",
  "spotifyUri": null,
  "type": "PRESAVE",
  "bioLinkData": null,
  "userId": null,
  "externalUserId": "1bfd4ae9",
  "releaseDate": "2026-06-05T13:50:37.622Z",
  "createdAt": "2024-07-24T15:39:45.009Z",
  "links": [
    {
      "id": "4891f4c7-ee35-4edc-9fb6-91002bff1161",
      "linkType": "SPOTIFY",
      "widgetType": "PRESAVE",
      "presave": true,
      "url": "",
      "position": 0
    },
    {
      "id": "6a539e0b-51eb-4818-86e2-7a9295bb05c7",
      "linkType": "DEEZER",
      "widgetType": "PRESAVE",
      "presave": true,
      "url": "",
      "position": 1
    },
    {
      "id": "ee7fa8b1-6bda-4714-9a26-a173cd6164ff",
      "linkType": "APPLE_MUSIC",
      "widgetType": "PRESAVE",
      "presave": true,
      "url": "",
      "position": 2
    },
    {
      "id": "5ccff403-b63a-4b74-9ba9-2c687546ccbd",
      "linkType": "CUSTOM",
      "widgetType": "PRESAVE",
      "presave": true,
      "url": "",
      "position": 3
    }
  ]
}

This endpoint retrieves a specific smartlink.

HTTP Request

GET https://partners.api.baseformusic.com/partners-api/smartlinks/<ID_SMARTLINK>

Query Parameters

Parameter	Description
ID	The ID of the smartlink to retrieve

Response

Parameter	Type	Description
id	string (UUID)	The unique identifier for the smart link
name	string	The name of the smart link
title	string	The title of the smart link
description	string	The description of the smart link
snapchatPixelId	string	The Snapchat Pixel ID
metaPixelId	string	The Meta (Facebook) Pixel ID
googleAnalyticsId	string	The Google Analytics ID
shortId	string	The shortened identifier for the smart link
defaultCoverUrl	string	The default cover URL for the smart link
releaseDate	string (ISO 8601)	The release date for presave links
externalUserId	string	The external user ID
type	enum (PRESAVE, MUSIC, FAN, BIO)	The type of smart link
customCanvasUrl	string	The custom canvas URL
defaultCanvasUrl	string	The default canvas URL
coverUrl	string	The cover URL
spotifyUri	string	The Spotify URI for music links
bioLinkData	object	The bio link data
userId	string (UUID)	The user ID
selectedCover	string	The selected cover (e.g., 'default')
createdAt	string (ISO 8601)	The creation timestamp
links	array of link objects	The list of associated links

Links Object Detailed Information:

Parameter	Type	Description
id	string (UUID)	The unique identifier for the link
linkType	enum (CUSTOM, SPOTIFY, YOUTUBE, YOUTUBE_MUSIC, SOUNDCLOUD, DEEZER, APPLE_MUSIC, PRIME_MUSIC, FNAC, TIDAL, BEATPORT, MIXCLOUD, QUOBUZZ, BANDCAMP, NAPSTER)	The type of the link (e.g., 'SPOTIFY')
url	string	The URL of the link
position	number	The position of the link
presave	boolean	Indicates if the link is a presave link
widgetType	string	The widget type of the link (e.g., 'PRESAVE')

Get All smartlinks

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/partners-api/smartlinks?externalUserId=1bfd4ae9' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer TOKEN'


const API_URL = 'https://partners.api.baseformusic.com/partners-api/smartlinks/';  
const EXTERNAL_USER_ID = '1bfd4ae';
const url = new URL(API_URL);
url.searchParams.append('externalUserId', EXTERNAL_USER_ID);

fetch(API_URL, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

RESPONSE SAMPLE:


[
  {
    "id": "ae7096ae-f50a-4a6b-be11-0d59d927e2c5",
    "name": "Smart Link 12",
    "title": "Sauvage",
    "description": "Dorian",
    "snapchatPixelId": "12314241432",
    "metaPixelId": "12314241432",
    "googleAnalyticsId": "12314241432",
    "shortId": "h74JusEW",
    "defaultCoverUrl": "https://placehold.co/200x200",
    "customCanvasUrl": null,
    "defaultCanvasUrl": null,
    "coverUrl": null,
    "selectedCover": "default",
    "spotifyUri": null,
    "type": "PRESAVE",
    "bioLinkData": null,
    "userId": null,
    "externalUserId": "1bfd4ae9",
    "releaseDate": "2026-06-05T13:50:37.622Z",
    "createdAt": "2024-07-24T15:39:45.009Z",
    "linkViews": 0
  }
]

This endpoint retrieves all smartlinks.

HTTP Request

GET https://partners.api.baseformusic.com/partners-api/smartlinks

Query Parameters

Parameter	Description
externalUserId	The ID of the user in your system

Response

The response is an array of smartlink objects. Each smartlink object has the following properties:

Parameter	Type	Description
id	string (UUID)	The unique identifier for the smart link
name	string	The name of the smart link
title	string	The title of the smart link
description	string	The description of the smart link
snapchatPixelId	string	The Snapchat Pixel ID
metaPixelId	string	The Meta (Facebook) Pixel ID
googleAnalyticsId	string	The Google Analytics ID
shortId	string	The shortened identifier for the smart link
defaultCoverUrl	string	The default cover URL for the smart link
customCanvasUrl	string	The custom canvas URL
defaultCanvasUrl	string	The default canvas URL
coverUrl	string	The cover URL
selectedCover	string	The selected cover (e.g., 'default')
spotifyUri	string	The Spotify URI for music links
type	enum (PRESAVE, MUSIC, FAN, BIO)	The type of smart link
bioLinkData	object	The bio link data
userId	string (UUID)	The user ID
externalUserId	string	The external user ID
releaseDate	string (ISO 8601)	The release date for presave links
createdAt	string (ISO 8601)	The creation timestamp
linkViews	number	The number of views for the link

Update a smartlink

REQUEST SAMPLE


curl -X 'PATCH' \
  'https://partners.api.baseformusic.com/partners-api/smartlinks/ae7096ae-f50a-4a6b-be11-0d59d927e2c5' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Updated Smart Link Name",
  "description": "Updated Description",
  "title": "Updated Title",
  "coverUrl": "https://placehold.co/300x300",
  "snapchatPixelId": "98765432100",
  "metaPixelId": "98765432100",
  "googleAnalyticsId": "98765432100",
  "spotifyUri": "spotify:track:4iV5W9uYEdYUVa79Axb6Wv",
  "selectedCover": "custom",
  "bioLinkData": {},
  "links": [
    {
      "linkType": "SPOTIFY",
      "url": "https://spotify.com/track/12345",
      "position": 0,
      "presave": true
    },
    {
      "linkType": "DEEZER",
      "url": "https://deezer.com/track/12345",
      "position": 1,
      "presave": true
    }
  ]
}'


const API_URL = 'https://partners.api.baseformusic.com/partners-api/smartlinks/ae7096ae-f50a-4a6b-be11-0d59d927e2c5';
const accessToken = 'ACCESS_TOKEN';

const requestData = {
  name: 'Updated Smart Link Name',
  description: 'Updated Description',
  title: 'Updated Title',
  coverUrl: 'https://placehold.co/300x300',
  snapchatPixelId: '98765432100',
  metaPixelId: '98765432100',
  googleAnalyticsId: '98765432100',
  spotifyUri: 'spotify:track:4iV5W9uYEdYUVa79Axb6Wv',
  selectedCover: 'custom',
  bioLinkData: {},
  links: [
    {
      linkType: 'SPOTIFY',
      url: 'https://spotify.com/track/12345',
      position: 0,
      presave: true
    },
    {
      linkType: 'DEEZER',
      url: 'https://deezer.com/track/12345',
      position: 1,
      presave: true
    }
  ]
};

fetch(API_URL, {
  method: 'PATCH',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestData),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error:', error));

HTTP Request

PATCH https://partners.api.baseformusic.com/partners-api/smartlinks/<ID_SMARTLINK>

Body Parameters

Parameter	Type	Description	Optional	Validation
name	string	The name of the smart link	Yes
coverUrl	string	The cover URL for the smart link	Yes	Must be a valid URL
customCanvasUrl	string	The custom canvas URL	Yes	Must be a valid URL
selectedCover	enum (default, custom)	The selected cover type	Yes	Must be one of the defined enum values
spotifyUri	string	The Spotify URI for music links	Yes	Format: spotify:resource:id; required for MUSIC type
title	string	The title of the smart link	Yes
description	string	The description of the smart link	Yes
snapchatPixelId	string	The Snapchat Pixel ID	Yes
metaPixelId	string	The Meta (Facebook) Pixel ID	Yes
googleAnalyticsId	string	The Google Analytics ID	Yes
bioLinkData	object	The bio link data	Yes	Must be a valid object
links	array of link objects	The list of associated links	Yes	Must be an array of valid link objects

Links Object Detailed Information

Parameter	Type	Description
id	string (UUID)	The unique identifier for the link
linkType	enum (CUSTOM, SPOTIFY, YOUTUBE, YOUTUBE_MUSIC, SOUNDCLOUD, DEEZER, APPLE_MUSIC, PRIME_MUSIC, FNAC, TIDAL, BEATPORT, MIXCLOUD, QUOBUZZ, BANDCAMP, NAPSTER)	The type of the link (e.g., 'SPOTIFY')
url	string	The URL of the link
position	number	The position of the link
presave	boolean	Indicates if the link is a presave link
widgetType	string	The widget type of the link (e.g., 'PRESAVE')

Playbook

A playbook is a type of a campaign that you can create in Base for Music.

This is a marketing campaign linked to an advertising format, set up and optimized to achieve a specific objective. It allows your user to simply select the right advertising format according to the content they want to promote and their promotional objective.

Please reach out to our support team to request the addition of a custom playbook.

Playbook name list

In this section, you will find the list of all the available playbooks and a summary of how they work.

playbookList



# Define the playbook filter
PLAYBOOK_FILTER=(
  "youtubeViewersEngagementsGoogleAds"
  "youtubeViewersGoogleAds"
  "spotifyEngagementAdStudio"
  "spotifyAudioMeta"
  "spotifyPlaylistMeta"
  "instagramFollowersMeta"
  "streamingListenersMeta"
  "tikTokFollowersTikTokBusiness"
  "bToB"
  "instagramTrafficMeta"
  "facebookTrafficMeta"
  "youtubeEngagementGoogleAds"
  "instagramViewsMeta"
  "instagramEngagementMeta"
  "tiktokViewsTikTokBusiness"
  "tiktokEngagementTikTokBusiness"
)


export const PLAYBOOK_BY_PROVIDER_FILTER = {
  youtube: ["youtubeViewersEngagementsGoogleAds", "youtubeViewersGoogleAds", "youtubeEngagementGoogleAds"],
  spotify: ["spotifyEngagementAdStudio"],
  meta: [
    "spotifyAudioMeta",
    "spotifyPlaylistMeta",
    "instagramFollowersMeta",
    "streamingListenersMeta",
    "instagramViewsMeta",
    "instagramTrafficMeta"
    "facebookTrafficMeta",
  ],
  tiktok: ["tikTokFollowersTikTokBusiness", "tiktokViewsTikTokBusiness", "tiktokEngagementTikTokBusiness"],
  other: ["bToB"],
};

export const PLAYBOOK_FILTER = [
  "youtubeViewersEngagementsGoogleAds",
  "youtubeViewersGoogleAds",
  "spotifyEngagementAdStudio",
  "spotifyListenersMeta",
  "spotifyPlaylistMeta",
  "instagramFollowersMeta",
  "streamingListenersMeta",
  "tikTokFollowersTikTokBusiness",
  "bToB",
  "instagramTrafficMeta",
  "facebookTrafficMeta",
  "youtubeEngagementGoogleAds",
  "instagramViewsMeta",
  "instagramEngagementMeta",
  "tiktokViewsTikTokBusiness",
  "tiktokEngagementTikTokBusiness"
];

Playbook name	Playbook Content	Objective	Description
youtubeViewersEngagementsGoogleAds	Google Ads	Youtube Viewers & Engagement	Get more views and engagement on your Youtube videos
youtubeViewersGoogleAds	Google Ads	Youtube Viewers	Get more views on your Youtube videos
youtubeEngagementGoogleAds	Google Ads	Youtube Engagement	Get more engagement on your Youtube videos
spotifyEngagementAdStudio	Spotify Ad Studio	Spotify Engagement	Get more engagement on your Spotify account
spotifyListenersMeta	Meta	Spotify Listeners	Get more listeners on your Spotify account
spotifyPlaylistMeta	Meta	Spotify Playlist Followers	Get more followers on your Spotify playlist
instagramFollowersMeta	Meta	Instagram Followers	Get more followers on your Instagram account
streamingListenersMeta	Meta	Streaming Listeners	Get more listeners on your streaming accounts
instagramTrafficMeta	Meta	Instagram Traffic	Get more traffic on your website / link
facebookTrafficMeta	Meta	Facebook Traffic	Get more traffic on your website / link
instagramViewsMeta	Meta	Instagram Views	Get more views on your Instagram account
instagramEngagementMeta	Meta	Instagram Engagement	Get more engagement on your Instagram account
tiktokViewsTikTokBusiness	TikTok for Business	TikTok Views	Get more views on your TikTok account
tiktokEngagementTikTokBusiness	TikTok for Business	TikTok Engagement	Get more engagement on your TikTok account
tikTokFollowersTikTokBusiness	TikTok for Business	TikTok Followers	Get more followers on your TikTok account
bToB	bTob	Custom playbook	Specific playbook for partners

Youtube viewers

Reach people likely to become new viewers on your video clip. It will be promoted as an ad at the beginning of video on Youtube via Google Ads. All audiences reached are optimized according to the number of new viewers they generate.

Youtube viewers engagements

Reach people likely to become new viewers and engage with actions on your video clip. It will be promoted as an ad at the beginning of video and as a recommendation on Youtube via Google Ads. All audiences reached are optimized according to the number of new viewers they generate and their rate of engagement (likes, playlists, shares, follows).

Spotify Engagement

Reach Spotify listeners likely to become highly engaged with your music to support your integration into Spotify's automatic playlists. It will be promoted as an audio ad on Spotify freemium via Spotify Ad Studio. All audiences reached are optimized according to the number of new listeners they generate and their engagement rate (average stream/listener, add to playlist, save, like.).

Instagram followers

Reach people likely to become new followers for your Instagram page. It will be promoted with a sponsored post or personalized ad content on Instagram via Meta and will redirect to your Instagram page. All audiences reached are optimized according to the number of new followers they generate.

Spotify listeners

Redirect maximum Spotify listeners to your music to support your inclusion in Spotify's automatic playlists. It will be promoted as a sponsored post or personalized ad content on Facebook & Instagram via Meta and redirect these people to Spotify. All audiences reached are optimized according to the number of new listeners identified who have been redirected from Meta to Spotify.

Spotify playlist followers

Redirect maximum Spotify listeners to your playlist to get new followers. It will be promoted as a sponsored post or personalized ad content on Facebook & Instagram via Meta and redirect those people to Spotify. All audiences reached are optimized according to the number of new listeners identified who have been redirected from Meta to Spotify.

Streaming listeners

Redirect maximum streaming listeners to your music to support your inclusion in automatic playlists. It will be promoted as a sponsored post or personalized ad content on Facebook & Instagram via Meta and redirect those people to the streaming platforms. All audiences reached are optimized according to the number of new listeners identified who have been redirected from Meta to streaming platforms.

Instagram traffic

Reach people likely to visit your website or link. It will be promoted with a sponsored post or personalized ad content on Instagram via Meta and will redirect to your website or link. All audiences reached are optimized according to the number of new visitors they generate.

Facebook traffic

Reach people likely to visit your website or link. It will be promoted with a sponsored post or personalized ad content on Facebook via Meta and will redirect to your website or link. All audiences reached are optimized according to the number of new visitors they generate.

Instagram views

Reach people likely to view your Instagram content. It will be promoted with a sponsored post or personalized ad content on Instagram via Meta and will redirect to your Instagram page. All audiences reached are optimized according to the number of new views they generate.

Instagram engagement

Reach people likely to engage with your Instagram content. It will be promoted with a sponsored post or personalized ad content on Instagram via Meta and will redirect to your Instagram page. All audiences reached are optimized according to the number of new engagements they generate.

TikTok views

Reach people likely to view your TikTok content. It will be promoted with a sponsored post on TikTok via TikTok for Business and will redirect to your page. All audiences reached are optimized according to the number of new views they generate.

TikTok engagement

Reach people likely to engage with your TikTok content. It will be promoted with a sponsored post on TikTok via TikTok for Business and will redirect to your page. All audiences reached are optimized according to the number of new engagements they generate.

TikTok followers

Reach people likely to become new followers for your TikTok page. It will be promoted with a sponsored post on TikTok via TikTok for Business and will redirect to your page. All audiences reached are optimized according to the number of new followers they generate.

Playbook custom

The BtoB playbook is a campaign that is optimized for a specific business objective.

You can contact the support team@baseformusic.fr to request the addition of a custom playbook.

Playbook content

This section provides detailed explanations of the playbookContent that should be followed when creating a campaign for each playbook. We recommend using auto targeting for your initial campaign and then transitioning to manual targeting for optimizing subsequent campaigns.

The playbookContent is a JSON object containing the information needed to create a campaign.

All content playbooks are categorized according to the partner advertising network :

Spotify Ad Studio
Meta
Tiktok for Business
GoogleAds
bTob

Example playbookContent:


{
   "profile":{
      "artist":{
         "id":"6eUKZXaKkcviH0Ku9w2n3V"
      }
   },
   "content":{
      // you have to choice between auto or custom
      "auto":{
         "track":{
            "id":"3n3Ppam7vgaVa1iaRUc9Lp"
         }
      },
      "custom":{
         "url":"https://drive.google.com/file/d/1RQ12X7Q9aWVaB6dpWSFI7FXPkG8FWe0/view",
         "description":"Spotify"
      }
   },
   "redirection":{
      "resourceType":"artist",
      "id":"6eUKZXaKkcviH0Ku9w2n3V"
   },
   "targeting":{
      // you have to choice between auto or custom
      "auto":{
         "musicalGenre":"reggae",
         "language":"all"
      },
      "custom": {
          "demographics": {
            "ageRanges": ["18-24", "25-34"],
            "countries": ["US"],
            "gender": "all",
          },
          "audiences": {
            "fanbase": [
              {
                "id": "6eUKZXaKkcviH0Ku9w2n3V",
              },
            ],
            "genres": ["classical"],
            "interests": ["chill"],
          },
        },
   }
}

In certain parts of the content, you will need to include the id of the content you want to promote. For instance, if you wish to promote a Spotify track, you should include the track's id in the trackId field.

Parameter	Type	Description
*profile*	object	Profile to promote
*content*	object	Content to promote
*redirection*	object	Redirection to artist or brand
*targeting*	object	Targeting details

Profile: In this section, you will provide information about the profile ChannelId / ArtistId you intend to promote.

Example:

Parameter	Type	Description
*artist*	object	Artist

You can promote a profile by providing the profile's id in the artistId field.

Content: In this section, you will provide information about the content you intend to promote.

Example:

Parameter	Type	Description
*auto*	object	Auto content
*custom*	object	Custom content

Targeting: In this section, you will specify the targeting details for your campaign.

Parameter	Type	Description
*auto*	object	Auto targeting
*custom*	object	Custom targeting

auto

LanguageEnum

LanguageEnum


['fr','en','es','de','pt','it','hi','all']

MusicalGenreEnum

MusicalGenreEnum


["hiphop","pop","traditional","classical","rock","jazz","electronica","traditional","reggae"",country","metal","traditional","latin","general"]

Parameter	Type	Description
musicalGenre	string	MusicalGenreEnum ( see MusicalGenreEnum )
language	string	LanguageEnum ( see LanguageEnum )

custom

AgeEnum

AgeEnum


["16-17","18-24","25-34","35-44","45-54","55-64","65+"]

GenderEnum

GenderEnum


["male","female","all"]

CountryCodeEnum

CountryCodeEnum


[
  "DZ", "AR", "AT","BH","BE","BO","BR","CA","CL","CO","CR","DO","EC","EG","SV","FI","FR","DE","GH","GT","HN","HK","IN","ID","IE","IT","JM","JP","KE","KW","LB","LI","LU","MY","MX","MA","NL","NZ","NI","NG","NO","OM","PS","PA","PY","PE","PH","PT","PR","QA","SA","SG","ZA","ES","SE","CH","TW","TZ","TN","TR","UG","AE","GB","US","UY",
]

Parameter	Type	Description
ageRanges	array	AgeEnum ( see AgeEnum )
countries	array	countryCodeEnum ( see CountryCodeEnum
gender	string	GenderEnum ( see GenderEnum )

Google Ads

Documentation for the following playbooks: youtubeViewersEngagementsGoogleAds, youtubeViewersGoogleAds

Example Youtube playbookContent



{
  "profile": {
    "channelReference": {
      "id": "6eUKZXaKkcviH0Ku9w2n3V"
    },
    "mail": "test@baseformusic.com"
  },
  "content": {
    "videoURL": {
      "id": "6eUKZXaKkcviH0Ku9w2n3V"
    }
  },
  "targeting": {
      // you have to choice between auto or custom
    "auto": {
      "auto": {
        "musicalGenre": "reggae",
        "language": "all"
      }
    },
    "custom": {
      "demographics": {
        "ageRanges": ["AGE_18_24"],
        "countries": ["US"],
        "gender": "ALL"
      },
      "audiences": {
        "fanbase": [
          {
            "id": "6eUKZXaKkcviH0Ku9w2n3V",
          }
        ],
        "topics": ["1001", "1286"],
        "interests": ["91900", "91902"],

      }
    }
  }
}

Parameter	Type	Description
profile	object	The profile of the artist you want to promote
profile.channelReference	object	The channel reference of the artist you want to promote
profile.channelReference.id	string	The channel id of the artist you want to promote
profile.mail	string	The mail of the artist you want to promote
content	object	The content you want to promote
content.videoURL	object	The video URL of the artist you want to promote
content.videoURL.id	string	The id of the video URL of the artist you want to promote
targeting	object	The targeting of the campaign
targeting.auto	object	The targeting of the campaign
targeting.auto.musicalGenre	string	The musical genre of the campaign ( see MusicalGenreEnum )
targeting.auto.language	string	The language of the campaign ( see LanguageEnum )
targeting.custom	object	The custom targeting of the campaign
targeting.custom.demographics	object	The demographics you want to target
targeting.custom.demographics.ageRanges	array	The age ranges you want to target ( see AgeRangeEnum )
targeting.custom.demographics.countries	array	The countries you want to target ( see CountryCodeEnum )
targeting.audiences	object	The audiences you want to target
targeting.audiences.fanbase	array	The fanbase you want to target
targeting.audiences.fanbase.id	string	The channeld id of the fanbase you want to target
targeting.audiences.topics	array	The topics you want to target ( see YoutubeTopicsEnum )
targeting.audiences.interests	array	The interests you want to target ( see YoutubeInterestsEnum )

YoutubeTopicsEnum ( see Enum in the code section )

YoutubeTopicsEnum


{
   "42":"Jazz",
   "217":"CD & Audio Shopping",
   "218":"Music Art & Memorabilia",
   "220":"Music Streams & Downloads",
   "585":"Christian & Gospel Music",
   "586":"Classical Music",
   "587":"Country Music",
   "588":"Dance & Electronic Music",
   "617":"Song Lyrics & Tabs",
   "618":"Vocals & Show Tunes",
   "809":"Podcasts",
   "892":"Sheet Music",
   "893":"Soundtracks",
   "1021":"Pop Music",
   "1022":"Experimental & Industrial Music",
   "1023":"Folk & Traditional Music",
   "1025":"DJ Resources & Equipment",
   "1026":"Music Recording Technology",
   "1028":"Music Composition & Theory",
   "1030":"Rap & Hip-Hop",
   "1031":"Reggae & Caribbean Music",
   "1032":"South Asian Music",
   "1034":"Middle Eastern & North African Music",
   "1035":"Hard Rock & Progressive",
   "1036":"Metal (Music)",
   "1037":"Classic Rock & Oldies",
   "1038":"Indie & Alternative Music",
   "1039":"Soul & R&B",
   "1040":"Blues",
   "1041":"Punk (Music)",
   "1087":"Music Education & Instruction",
   "1091":"Samples & Sound Libraries",
   "1186":"Talk Radio",
   "1208":"African Music",
   "1242":"Reggaeton",
   "1285":"Latin Pop",
   "1286":"Salsa & Tropical Music",
   "1287":"Brazilian Music",
   "1325":"Guitars",
   "1326":"Pianos & Keyboards",
   "1327":"Drums & Percussion",
   "1408":"Music Videos",
   "1806":"Southeast Asian Music",
   "1898":"Korean Pop"
}

YoutubeInterestsEnum ( see Enum in the code section )

YoutubeInterestsEnum



{
  "91900": "Music Lovers",
  "91901": "Pop Music Fans",
  "91902": "Rock Music Fans",
  "91903": "Classical Music Enthusiasts",
  "91904": "Country Music Fans",
  "91905": "Jazz Enthusiasts",
  "91906": "Blues Fans",
  "91907": "Electronic Dance Music Fans",
  "91908": "Folk & Traditional Music Enthusiasts",
  "91909": "Rap & Hip Hop Fans",
  "91910": "Metalheads",
  "91911": "Spanish-Language Music Fans",
  "91912": "Indie & Alternative Rock Fans"
};

Spotify Ad Studio

Documentation for the following playbook: spotifyEngagementAdStudio

Example spotifyEngagementAdStudio playbookContent


{
   "profile":{
      "artist":{
         "id":"6eUKZXaKkcviH0Ku9w2n3V"
      }
   },
   "content":{
      // you have to choice between auto or custom
      "auto":{
         "track":{
            "id":"3n3Ppam7vgaVa1iaRUc9Lp"
         }
      },
      "custom":{
         "url":"https://drive.google.com/file/d/1RQ12X7Q9aWVaB6dpWSFI7FXPkG8FWe0/view",
         "description":"Spotify"
      }
   },
   "redirection":{
      "resourceType":"artist",
      "id":"6eUKZXaKkcviH0Ku9w2n3V"
   },
   "targeting":{
      // you have to choice between auto or custom
      "auto":{
         "musicalGenre":"reggae",
         "language":"all"
      },
      "custom": {
          "demographics": {
            "ageRanges": ["18-24", "25-34"],
            "countries": ["US"],
            "gender": "all",
          },
          "audiences": {
            "fanbase": [
              {
                "id": "6eUKZXaKkcviH0Ku9w2n3V",
              },
            ],
            "genres": ["classical"],
            "interests": ["chill"],
          },
        },
   }
}

Parameter	Type	Description
profile	object	The profile of the artist you want to promote
profile.artist	object	The artist you want to promote
profile.artist.id	string	The Spotify id of the artist you want to promote
content	object	The content you want to promote
content.auto	object	The content you want to promote automatically
content.auto.track	object	The track you want to promote
content.auto.track.id	string	The Spotify id of the track you want to promote
content.custom	object	The content you want to promote manually
content.custom.url	string	The url of the content in you want to promote. ( see drive )
content.custom.description	string	The description of the content you want to promote
redirection	object	The redirection you want to use
redirection.resourceType	string	The type of resource you want to redirect to
redirection.id	string	The id of the resource you want to redirect to
targeting	object	The targeting you want to use
targeting.auto	object	The targeting you want to use automatically
targeting.custom	object	The targeting you want to use manually
targeting.auto.musicalGenre	string	The musical genre you want to target ( see MusicalGenreEnum )
targeting.auto.language	string	The language you want to target ( see LanguageEnum )
targeting.custom.demographics	object	The demographics you want to target
targeting.custom.audiences	object	The audiences you want to target
targeting.custom.demographics.ageRanges	array	The age ranges you want to target ( see AgeRangesEnum )
targeting.custom.demographics.countries	array	The countries you want to target ( see CountryCodeEnum )
targeting.custom.demographics.gender	array	The Gender of the artist you want to promote ( see GenderEnum )

TikTok for Business

Documentation for the following playbook: tikTokFollowersTikTokBusiness

Example TikTok playbookContent


{
   "profile":{
      "post":{
         "id":"21321EAZDSSQD"
      }
   },
   "targeting":{
     // you have to choice between auto or custom
      "auto":{
         "auto":{
            "musicalGenre":"reggae",
            "language":"all"
         }
      },
      "custom":{
         "demographics":{
            "ageRanges":[
               "18-24",
               "25-34"
            ],
            "countries":[
               "US"
            ],
            "gender":"all"
         },
         "audiences":{
            "fanbase":[
               {
                  "id":"6eUKZXaKkcviH0Ku9w2n3V"
               }
            ],
            "genres":[
               "classical"
            ],
            "interests":[
               "chill"
            ]
         }
      }
   }
}

Parameter	Type	Description
profile	object	The profile of the artist you want to promote
profile.post	object	The post of the artist you want to promote
profile.post.id	string	The id of the post of the artist you want to promote
targeting	object	The targeting of the artist you want to promote
targeting.auto	object	The auto targeting of the artist you want to promote
targeting.auto.musicalGenre	string	The musical genre of the artist you want to promote
targeting.auto.language	string	The language of the artist you want to promote
targeting.custom	object	The custom targeting of the artist you want to promote
targeting.custom.demographics	object	The demographics of the artist you want to promote
targeting.custom.demographics.ageRanges	array	The age ranges of the artist you want to promote ( see AgeRangesEnum )
targeting.custom.demographics.countries	array	The countries of the artist you want to promote ( see CountryCodeEnum )
targeting.custom.demographics.gender	array	The Gender of the artist you want to promote ( see GenderEnum )

Reporting

The API provides a shared reporting feature that allows you to share campaign reports with your users. You can create a unique URL for each campaign and share it. Users can then access the campaign reports by visiting the URL in their browser.

You can obtain a reporting URL. by either making a request to the get a Specific Campaign API endpoint or by retrieving it when listing all campaigns using the list campaign API endpoint.

Customize the reporting with your brand colors and logo by adding the following query parameters to the reporting URL:



- `SLUG_PARTNER_NAME` is the ID of the partner.

## Image example

> Reporting URL example [https://baseformusic.com/apps/reporting/Kt86Nrxncy](https://prod-base.netlify.app/apps/reporting/Kt16Nrxncy)

Each playbook have a unique reporting, see the example below with the Playbook "Spotify Engagement"

<div class="image-container">
    <img src="https://cdn.shopify.com/s/files/1/0262/6414/1875/files/Reporting_Share1.png?v=1693912509" class="image-item" />
    <img src="https://cdn.shopify.com/s/files/1/0262/6414/1875/files/Reporting_Share2.png?v=1693912539" class="image-item" />
</div>

External content

Benefit from our various connectors to easily obtain the elements needed to launch a campaign

Youtube Search

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/youtube/search?query=Mr%20Beasts&type=channel&limit=10' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'


const axios = require('axios');

const url = 'https://partners.api.baseformusic.com/external-content/youtube/search';
const queryParameters = {
  query: 'Mr Beasts',
  type: 'channel',
  limit: 10,
};

const headers = {
  accept: '*/*',
  Authorization: 'Bearer ACCESS_TOKEN',
};

axios
  .get(url, {
    params: queryParameters,
    headers: headers,
  })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

HTTP Request

GET https://partners.api.baseformusic.com/external-content/youtube/search

Query Parameters

Parameter	Type	Description
query	string	The query to search
type	YoutubeSearchEnum	channel or video ( see YoutubeSearchEnum )
limit	string	The number of results to return

YoutubeSearchEnum

YoutubeSearchEnum


[ "channel","video" ]

Enum	Description
channel	Search for channels
video	Search for videos

Youtube API video

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/youtube/video/aQJif5ic-lo' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN'



const ID_VIDEO = 'aQJif5ic-lo';
const API_URL = 'https://partners.api.baseformusic.com/external-content/youtube/video/';


fetch(API_URL, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

Get a video by id

HTTP Request

GET https://partners.api.baseformusic.com/external-content/youtube/video/{videoId}

Parameters

Parameter	Type	Description
videoId	string	The youtube Video id

Youtube API channel

Get a channel by id

REQUEST SAMPLE


curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/youtube/channel/UCjIWry0c3Z0fZEf4VdoJ3mA' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN'



const ID_CHANNEL = 'UCjIWry0c3Z0fZEf4VdoJ3mA';
const API_URL = 'https://partners.api.baseformusic.com/external-content/youtube/channel/';


fetch(API_URL, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

HTTP Request

GET https://partners.api.baseformusic.com/external-content/youtube/channel/{channelId}

Parameters

Parameter	Type	Description
channelId	string	The youtube Channel id

Spotify Search


curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/spotify/search?query=Dams&type=artist&limit=10' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'


const axios = require('axios');

const url = 'https://partners.api.baseformusic.com/external-content/spotify/search';
const queryParameters = {
  query: 'Dams',
  type: 'artist',
  limit: 10,
};

const headers = {
  accept: '*/*',
  Authorization: 'Bearer ACCESS_TOKEN',
};

axios
  .get(url, {
    params: queryParameters,
    headers: headers,
  })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

Spotify search for an artist, album, track or playlist

HTTP Request

GET https://partners.api.baseformusic.com/external-content/spotify/search

Query Parameters

Parameter	Type	Description
query	string	The query to search
type	SpotifySearchEnum	track,artist,album or playlist ( see SpotifySearchEnum )
limit	string	The number of results to return

SpotifySearchEnum

SpotifySearchEnum


[ "track","artist","album", "playlist" ]

Enum	Description
tracks	Search for tracks
artist	Search for artists
album	Search for albums
playlist	Search for playlists

Spotify API track



curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/spotify/track/4sjpqDVERhsIu8pIJJUjes?si=5abf2fea3d534edf \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'



const ID_TRACK = '4sjpqDVERhsIu8pIJJUjes?si=5abf2fea3d534edf';
const API_URL = 'https://partners.api.baseformusic.com/external-content/spotify/track/';


fetch(API_URL + ID_TRACK, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

HTTP Request

GET https://partners.api.baseformusic.com/external-content/spotify/track/{trackId}

Parameters

Parameter	Type	Description
trackId	string	The spotify track id

Spotify API artist



curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/spotify/artist/1k0U51DXyjFk4YnLZUIMP9 \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'



const ID_ARTIST = '1k0U51DXyjFk4YnLZUIMP9';
const API_URL = 'https://partners.api.baseformusic.com/external-content/spotify/artist/';


fetch(API_URL + ID_ARTIST, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

HTTP Request

GET https://partners.api.baseformusic.com/external-content/spotify/artist/{artistId}

Parameters

Parameter	Type	Description
artistId	string	The spotify artist id

Spotify API album



curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/spotify/album/6fBWeagrf7IOjz4unH1j9D \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'



const ID_ALBUM = '6fBWeagrf7IOjz4unH1j9D';
const API_URL = 'https://partners.api.baseformusic.com/external-content/spotify/album/';


fetch(API_URL + ID_ALBUM, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

HTTP Request

GET https://partners.api.baseformusic.com/external-content/spotify/album/{albumId}

Parameters

Parameter	Type	Description
albumId	string	The spotify album id

Spotify API playlist



curl -X 'GET' \
  'https://partners.api.baseformusic.com/external-content/spotify/playlist/19fEnBDlfxU6VL7fFtBWZg \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'



const ID_PLAYLIST = '19fEnBDlfxU6VL7fFtBWZg';
const API_URL = 'https://partners.api.baseformusic.com/external-content/spotify/playlist/';


fetch(API_URL + ID_PLAYLIST, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
})
  .then((response) => {
    return response.json(); // If the response contains JSON data
  })
  .then((data) => {
    // Handle the JSON data here
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the fetch
    console.error('Error:', error);
  });

HTTP Request

GET https://partners.api.baseformusic.com/external-content/spotify/playlist/{playlistId}

Parameters

Parameter	Type	Description
playlistId	string	The spotify playlist id

Drive API

To create the content.custom.url, you can use the endpoint below:

HTTP Request

POST https://partners.api.baseformusic.com/external-content/drive/upload

Body Parameters

Parameter	Type	Description
file	File	The file to upload
name	string	The name of the file



curl -X 'POST' \
  'http://localhost:3010/external-content/drive/upload' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'name=oigdkjsx.mp4' \
  -F 'video=@IOS - Fleets - 1.mp4;type=video/mp4'



const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const url = 'http://localhost:3010/external-content/drive/upload';
const headers = {
  accept: '*/*',
  Authorization: 'Bearer ACESS_TOKEN',
  'Content-Type': 'multipart/form-data',
};

const form = new FormData();
form.append('name', 'oigdkjsx.mp4');
form.append('video', fs.createReadStream('IOS - Fleets - 1.mp4'));

axios
  .post(url, form, { headers: { ...headers, ...form.getHeaders() } })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

Change log

Version	Release date	Description
1.O	2023-09-01	Initial release Partners API
1.1	2023-10-01	Add external content API
1.2	2024-01-01	Add new playbook
2.0	2024-06-01	Add smartlink endpoint

Status Codes

BaseForMusic uses the following error codes:

Status Code	Meaning
200	OK -- Everything worked as expected.
201	Created -- The object is gonna be created.
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The resource requested is hidden for administrators only.
404	Not Found -- The specified endpoint could not be found.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Support

Our team is here to support you throughout your integration journey. If you encounter any issues, have questions, or need assistance, please feel free to reach out to our support team at team@baseformusic.fr. We highly value your feedback, which helps us improve the API and documentation for all our partners.

Partners API

Introduction

Key Features

Authentication

Get started

Authorization

HTTP Request

Security

Campaigns

Create a campaign

HTTP Request

Body Parameters

Get a Specific Campaign

HTTP Request

Query Parameters

Response

Response sample

Get All Campaigns

HTTP Request

Query Parameters

Response

Smartlinks

Create a smartlink

HTTP Request

Body Parameters

Response

Links Object Detailed Information:

Get a Specific smartlink

HTTP Request

Query Parameters

Response

Links Object Detailed Information:

Get All smartlinks

HTTP Request

Query Parameters

Response

Update a smartlink

HTTP Request

Body Parameters

Links Object Detailed Information

Playbook

Playbook name list

Youtube viewers

Youtube viewers engagements

Spotify Engagement

Instagram followers

Spotify listeners

Spotify playlist followers

Streaming listeners

Instagram traffic

Facebook traffic

Instagram views

Instagram engagement

TikTok views

TikTok engagement

TikTok followers

Playbook custom

Playbook content

auto

LanguageEnum

MusicalGenreEnum

custom

AgeEnum

GenderEnum

CountryCodeEnum

Meta

Google Ads

YoutubeTopicsEnum ( see Enum in the code section )

YoutubeInterestsEnum ( see Enum in the code section )

Spotify Ad Studio

TikTok for Business

Reporting

External content

Youtube Search

HTTP Request

Query Parameters

YoutubeSearchEnum

Youtube API video

HTTP Request

Parameters