NAV
code sample

Introduction

Welcome! You can use Feature.fm’s API to access our inventory of promoted songs.

Our API will power your mobile app and website with high quality music while simultaneously providing you with the opportunity to monetize your air-play in a smarter, modern way.

About the API

The Feature.fm API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and use JSON response to indicate if the call was successful or not.

We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients. We also support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application.

JSON will be returned in all responses from the API, including errors.

We hope you enjoy using our API the same way we enjoyed building it for you!

Key Concepts

Feature.fm Partners

Do you have a music app, music blog or music related website? Do you share our passion in helping artists promote their music? Are you tired of clogging your service with ads and want to use high quality content in conjunction with a monetization solution instead?

If you answered yes, Feature.fm is for you.

Why should I join the Feature.fm Partners program

Feature.fm is an excellent solution for music services that are looking to monetize their music website/applications without using traditional ads that intrude on their content, increase churn, and disrupt the user experience.

Feature.fm is a music promotional platform that powers music services, websites and apps with great music content while allowing them to effectively monetize.

Additionally, our partners also get a dashboard! Our music services have access to detailed reports on their revenues and are able to cash out the money anytime with the touch of a button.

Feature.fm Customers

Feature.fm’s main customers are the artists, music labels and music promoters. They are the reason we built Feature.fm and our goal is to help them effectively promote music in the digital streaming age.

Feature.fm was build with the customer in mind, and we put an extensive effort in building a platform that would make it seamless for our customers to enjoy increased exposure in the music apps where their fans are listening.

So how does it work

Artists who want to promote their music on Feature.fm’s network may create a campaign using Feature.fm’s Advertiser Dashboard. This is done by simply uploading a song to Feature.fm, specifying the target audience, and sending the campaign for approval.

Once the campaign has been approved, it will be served to our partners apps and websites.

What targeting does Feature.fm support

Feature.fm supports many targeting options, including playing a song to consumers who:

  1. Listen to specific music genres
  2. Like specific artists
  3. Are located in a specific city or country
  4. Are distinguished by gender & age

How does the budget work?

As part of the campaign creation process, the artist sets a budget for the campaign. The artist has complete control on his/her spending by specifying a daily budget, maximum budget, and maximum bid.

The campaign that will eventually get played is the campaign that is relevant to a specific consumer and has the highest bid attached to it.

How does the artist monitor campaign performance?

The artist receives access to a powerful dashboard with information about the performance of each campaign and the subsequent user interaction (plays, skips, vote up, share, tweet, and more).

Music services that are part of the Feature.fm network sends events that inform us on what happened when the song was played as part of a campaign.

These events, in real-time, are displayed to the customer in an impressive dashboard, helping the customer better understand the performance of the campaign so he/she may optimize it.

Best Practices To Consider

There are many unique ways to integrate Feature.fm. Every app has specific needs and distinct standards for user experience. We have outlined some of our best practices for integrating that will work very well for both artists and music streaming services.

All of the examples listed in this section are targeted towards mobile platforms. However, they are applicable to web, tablet, tv, or any other streaming platform.

In-Stream Song Promotion

In-Stream Integration Example In-Stream integration involves automatically playing a featured song after every X number of songs. This should be used to help an artist gain exposure to new listeners the same way the “old” radio does but in a smarter,modern way.

What are the benefits?

  1. It is a great discovery feature for the end user
  2. It is a great way for music streaming services to monetize their airplay without disrupting the user experience with traditional advertisements.
  3. It does not require a user action such as a click, swipe, etc. to enjoy this revenue stream.

In this example we see a promoted song being played in an example music app. The song is marked as promoted content and the user may add it to a playlist, like it, share it, etc. It is the best practice to use a promoted song as if it were any other song in the hosting music service.

In-Search Song Promotion

In-Search Integration Example In-Search integration involves displaying a featured song as part of the search results and can be compared to Google’s sponsored search results.

In one scenario, this can be used to help artists gain exposure during the user’s creation of a playlist by allowing him/her to participate in more and more playlists. It is also an excellent way for music streaming services to monetize their search results with high quality music content.

In this example we see three promoted songs being displayed as part of the search results in an example music app. The songs are marked as a promoted content and the user can add the song to playlist, like it, share it, etc. It is the best practice to use a promoted song as if it were any other song in the hosting music service.

In-Discovery Song Promotion

In-Discovery Integration Example In-Discovery Song Promotion is to display a featured song in discovery sections in the music streaming services, blog and websites.

Discovery sections may include

  1. Music News Feed
  2. Popular Songs
  3. Music Charts
  4. Music News
  5. Any Browsable Section

This should be used to help artists gain exposure in front of users who want to discover new music. It is also great way for music streaming services to monetize their discovery screens without disturbing the user experience.

In this example we see a promoted song being displayed in an example music app. The song is being displayed with a mark indicating it is a promoted song. The user may add the song to a playlist, like it, share it, etc. It is the best practice to use a promoted song as if it were any other song in the hosting music service.

Publisher API

Consumers

Who is a Consumer

We define consumers as our partners' end users who are using their platforms to listen to and discover music.

Identify Consumer

This endpoint should be used to identify the end consumer. This request would normaly be called from the client side. When calling it from server side ipaddr parameter should be added to request payload.

In order to operate efficiently, Feature.fm requires a unique identifier for each user who receives a promoted song. This allows Feature.fm to avoid playing the same song to the same user multiple times and also to make better song recommendations based on the user's activity.

HTTP Request

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key": "valid_api_key", "cuid":user_unique_id_in_music_service, "gender": "male","1990": null}' APIDOMAIN/consumer/identify

The above command returns JSON structured like this:

{
    "status":0,
    "message":"Consumer was identified successfully",
    "consumer_token":"e978264b-ecea-4692-a4cd-2f725ee37d09"
}

POST /consumer/identify

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
cuid false Unique id of the user inside the application/website. This will allow feature.fm to choose campaigns more wisely for the user.
gender false Valid values: "male" or "female"
year_of_birth false Valid year (YYYY)
ipaddr false the user's ip address (mandatory for server side integration)

The endpoint will return a campaign to be played according to consumer and targeting parameters. Each request will generate a thread with a unique ID that should be used when conducting additional operations such as playing the song, sending events, etc.

HTTP Request

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token" ,"num_campaigns":1, "placement":"in_stream", "genres":[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22], "tags":["happy", "running"], "latest_songs": ["USAT21602948", "USQX91700384"]}' APIDOMAIN/featured/song

The above command returns JSON structured like this:

{
    "status": 0,
    "data": {
        "campaign_id": 1,
        "song": {
            "genres": [{
                            "name": "alternative/indie"
                        }],
            "title": "song name",
            "duration": "song duration in seconds",
            "albumart_url": "albumart valid image url",
            "sample_url": "song sample url",
            "soundcloud_url": "soundcloud url if exist",
            "buy_song_url": "buy_song_url if exist",
            "id": 0,
            "artist": {
                "name": "artist name",
                "image": "artist image url",
                "id": 0,
                "facebook_page_url": "artist page facebook url if exists",
                "twitter_page_url": "artist twitter handle url if exists",
                "bio": "artist short bio",
            },
            "publisher_catalog_id": "916339",
            "publisher_album_id": "103242",
            "stream_url": "FEATUREFMDOMAIN/play/{{song_play_id}}",
            "event_url": "APIDOMAIN/event/{{song_play_id}}",
            "youtube_url": "youtube url if exist",
            "share_on_twitter_url": "url to tweet this song on Twitter",
            "share_on_facebook_url": "url to share this song on Facebook",
            "spotlight_page_url": "artist Spotlight page on feature.fm",
            "share_url": "FEATUREFMDOMAIN/share/{{song_play_id}}"
        },
        "song_play_id": "should be used to send events",
        "social_optimization_type": "playlist",
        "custom_action_name": "Visit my page",
        "custom_action_url": "FEATUREFMDOMAIN/playlist/1353278355",
        "custom_action_event_url": "APIDOMAIN/event/58f6862c3300005dbff11af9.58f6866f33000032c0f11afd.5901ece82300004a002119ba/visit_playlist_page?api_key=7684aa0a76552139436d12ebbbd3da6e&consumer_token=cc4437d6-a260-4564-9193-c30eafb9ddb6&seconds_played="
    }
}

POST /featured/song

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
num_campaigns false Number of campaigns to return. Valid values are 1,2, or 3.
placement false Placement parameter may be used to get more detailed reports about the performance of a specific widget in specific location.
consumer_token true Valid consumer token.
genres true Array of genre codes. Allows the service to provide some information about the user’s context. For example: if he’s listening to Rock radio or likes Folk music, etc. Feature.fm will make sure that the user will get featured songs in the same context.
tags false Array of free-text tags. Allows the service to provide some information about the user’s context. For example: if he’s listening to songs attached to specific tags like: activities, moods, etc. Feature.fm will make sure that the user will get featured songs relevant to the specified tags.
artists true Array of free-text artist names. Allows the service to provide some information about the user’s context. For example: if he’s listening session with different artists Feature.fm will make sure that the user will get featured songs from similar artists.
latest_songs false Array of song's ISRC. Latest songs that the user listened to. Allows the service to provide some information about the user’s context. Helps our system to fine-tune the recommended songs.

Supported Genres

Code Name
0 rock
1 soul/r&b
2 alternative/indie
3 pop
4 electronica/dance
5 rap/hip hop
6 comedy/spoken word
7 world
8 classical/opera
9 reggae/ska
10 christian/gospel
11 soundtracks
12 new age
13 folk
14 latin
15 cast recordings/cabaret
16 country
17 instrumental
18 children's
19 jazz
20 vocals
21 seasonal
22 blues

Campaign Events

Feature.fm is a music promotion network, as such, we are obligated to providing our customers data and statistics regarding their campaigns.

Feature.fm Supported Events

Partners should send Feature.fm an event upon the occurrence of:

  1. Song Skip
  2. Song Vote-Up
  3. Song Vote-Down
  4. Song Like
  5. Favorite Song
  6. Song Added to Playlist
  7. Visit Artist Page
  8. Visit Album Page
  9. Follow
  10. Download
  11. Repost
  12. Share
  13. Comment

To be able to do that in efficient way and in real-time we kindly ask our partners to send us the relevant events specified in the Campaign Events section.

Please Note: The Skip event is mandatory and required to be sent when a featured song is being skipped.

Play Progress Update

This method should be used to notify Feature.fm about the song progress. Feature.fm uses this data to monitor the campaigns and to enhance the artist's dashboard. This endpoint must be called every 10 seconds as long as the song is playing.

POST /thread/{song_play_id}/progress

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "progress":147}' APIDOMAIN/thread/{{song_play_id}}/progress

POST Parameters

Parameter Required Description
progress true the current song position
song_play_id true the song play id that was retrieved from getFeaturedSong method

Skip

This endpoint should be used to report a skip event of a featured song. It is mandatory to report back if the user has skipped the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/skip

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/skip

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the user skipped the song.
consumer_token true Valid consumer token.

Vote Up

This endpoint should be used to report a vote up event of a featured song. It is mandatory to report back if the user has voted up the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/voteup

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/voteup

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Vote Down

This endpoint should be used to report a vote down event of a featured song. It is mandatory to report back if the user has voted down the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/votedown

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/votedown

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Like

This endpoint should be used to report a like event of a featured song. It is mandatory to report back if the user has liked the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/like

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/like

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Favorite

This endpoint should be used to report a favorite event of a featured song. It is mandatory to report back if the user has favorited the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/favorite

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/favorite

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Added To Playlist

This endpoint should be used to report an add to playlist event as a result of playing a featured song. It is mandatory to report back if the user has added the song to a playlist and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147, "playlist_name":"eclectisch"}' APIDOMAIN/event/{{song_play_id}}/added_to_playlist

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/added_to_playlist

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
playlist_id true The id of the playlist the song was added to.
consumer_token true Valid consumer token.

Visit Artist Page

This endpoint should be used to report click on the artist/user profile page event of a featured song. It is mandatory to report back if the user has clicked the link and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/visit_artist_page

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/visit_artist_page

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Visit Album Page

This endpoint should be used to report click on the album page event of a featured song. It is mandatory to report back if the user has clicked the link and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/visit_album_page

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/visit_album_page

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Follow

This endpoint should be used to report a follow event of a featured song. It is mandatory to report back if the user has followed the artist/user and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/follow

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/follow

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Download

This endpoint should be used to report a download event of a featured song. It is mandatory to report back if the user has downloaded the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/download

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/download

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Repost

This endpoint should be used to report a repost event of a featured song. It is mandatory to report back if the user has reposted the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/repost

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/repost

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Share

This endpoint should be used to report a shared event of a featured song. It is mandatory to report back if the user has shared the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147}' APIDOMAIN/event/{{song_play_id}}/share

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/share

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.

Comment

This endpoint should be used to report a comment event of a featured song. It is mandatory to report back if the user has commented on the song and at which position during the song, as this data is very valuable to the artists and will be displayed on their campaign dashboard.

curl -v -X POST -H "Content-Type: application/json" -d '{"api_key":"valid_api_key", "consumer_token":"valid_consumer_token", "seconds_played":147, "comment_text": "Great song"}' APIDOMAIN/event/{{song_play_id}}/comment

The above command returns JSON structured like this:

{
    "status": 0,
    "message": "success"
}

On error the status will be <> 0 and message will provide more details about the error:

{
    "status": 1,
    "message": "invalid parameter: seconds_played"
}

POST /event/{song_play_id}/comment

POST Parameters

Parameter Required Description
api_key true In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
seconds_played true The number of seconds the song was played before the event occurred. Specify (-1) if seconds_played is unknown.
consumer_token true Valid consumer token.
comment_text false The commant that the user entered

Marketing API

Artists

The Artist Object

The below JSON is an example of a artist object:

{
    "id": "5ad4a2b11e0000f94a1cf85b",
    "artistName": "Feature.fm",
    "artistImage": "http://www.feature.fm/blog/assets/images/feature_fm_no_text_logo.png?v=7d8241cd74",
    "type": "artist",
    "countryCode": "US",
    "shortBio": "My Biography",
    "websiteUrl": "http://feature.fm",
    "facebookPage": "https://www.facebook.com/Featurefm-497931363607317/",
    "twitterUrl": "https://twitter.com/featurefm?lang=en",
    "youtubeChannel": "https://www.youtube.com/channel/UCY1B_SZrt8sWNScujMCoNWw",
    "spotifyArtistUrl": "",
    "tags": ["tag1", "tag2"],
    "linkSettings": {
        "defaultStores": [
            "spotify",
            "amazon",
            "soundcloud",
            "apple",
            "deezer",
            "youtube"
        ],
        "customDomains": [
            {
                "domain": "custom.ffm.to",
                "isDefault": true
            }
        ],
        "notifications": {
            "toggle": true,
            "showArtistImage": true,
            "message": "Thank you for pre-saving my release",
            "subject": "My new release is out and available in your library"
        },
        "localization": [
            {
                "locale": "default",
                "callToActionText": "Choose your preferred music service",
                "enabledStores": [
                    {
                        "storeId": "youtube",
                        "actionName": "Watch Now"
                    },
                    {
                        "storeId": "spotify",
                        "actionName": "Play Now"
                    },
                    {
                        "storeId": "amazon",
                        "actionName": "Download Now"
                    }
                ],
                "disabledStores": [
                    {
                        "storeId": "deezer",
                        "actionName": "Play Now"
                    },
                    {
                        "storeId": "soundcloud",
                        "actionName": "Stream Now"
                    }
                ]
            },
            {
                "locale": "fr",
                "callToActionText": "Choisissez votre service de musique préféré",
                "enabledStores": [
                    {
                        "storeId": "amazon",
                        "actionName": "Jouer"
                    },
                    {
                        "storeId": "spotify",
                        "actionName": "Jouerify"
                    }
                ],
                "disabledStores": [
                    {
                        "storeId": "tidal",
                        "actionName": "Touer"
                    },
                    {
                        "storeId": "apple",
                        "actionName": "Fichsse"
                    }
                ]
            }
        ],
        "pixels": {
            "facebook": "123456789",
            "google": "123456789",
            "googleTagManager": "123456789"
        },
        "affiliates": {
            "apple": "apple_affiliate_code",
            "amazon": [
                {
                    "tag": "big",
                    "countryCode": "us"
                },
                {
                    "tag": "small",
                    "countryCode": "il"
                }
            ]
        },
        "analytics": {
            "google": "UA-9876-1"
        },
        "legal": {
            "termsOfServiceUrl": "https://en.wikipedia.org/wiki/Angelina_Jolie",
            "privacyPolicyUrl": "https://www.facebook.com/angelinajoliegoddess/"
        }
    }
}
Attribute Type Description
id string The unique identifier of the artist
artistName string The artist name
artistImage string Link to artist image
type string Can be either artist or band
countryCode string ISO 3166-1 alpha-2 code (ex. US)
shortBio string Short bio of the artist/band
websiteUrl string Url to the artist website
facebookPage string Facebook page url
twitterUrl string Twitter full url or twitter handle for the artist/band profile
youtubeChannel string youtube url for the artist channel
tikTokArtistUrl string tiktok url for the artist page
spotifyArtistUrl string Url to the artist profile on Spotify
tags array An array of strings representing tags associated with the artist. These tags can be used for categorization, searching, and filtering (Optional)
linkSettings object Default SmartLink/Action Pages settings

The Artist's List Object

{
    "id": "5ad4a2b11e0000f94a1cf85b",
    "name": "My Artist",
}
Attribute Type Description
id string The unique identifier of the artist
name string The artist name

The below JSON is an example of a artist's list object:

Attribute Type Description
customDomains array List of custom domains that can be used for the artist's SmartLink/Action Pages. Note: The custom domain must be approved for your api_key before using it. Once the domain is approved, you can choose to attach it to any of your artists
localization array <object> Localization settings
pixels object Re-targeting pixels
affiliates object Affiliate programs that are connected to your SmartLink/Action Page (such as Apple or Amazon)
analytics object Analytics programs that are connected to your SmartLink/Action Page (such as Google analytics)
legal object Legal object, defines the link privacy policy and terms of service URLs
notifications object Artist default fan notification settings (Optional). This feature automatically notifies fans that pre-save when your release is available. For this feature to work - it should be activated by contacting clientservices@feature.fm

Attribute Type Description
locale string ISO 3166-1 alpha-2 code (ex. US). use 'default' for all other locales
callToActionText string The default call to action to use for the link page locale
enabledStores array <object> Ordered list of music stores to show on display for the current link page locale
disabledStores array <object> Ordered list of music stores to hide from display for the current link page locale

Attribute Type Description
toggle boolean Indicate the default status of the Fan Notification feature at the artist level. If the value is ‘true’, the Fan Notification feature will be active by default for newly created links moving forward
showArtistImage boolean Indicate to display the ArtistImage in the header of the email. If the value is ‘true’, the image will show by default
message string The default text shown in the body of the Fan Notification email (maximum 150 characters)
subject string The default text of the subject line of the Fan Notification email (maximum 64 characters)

List Artists

Returns a list of artists associated to a specific api_key

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/artists

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
page number Page number (Optional). If page specified, number of results per page are 10. if not specified, all artists are included.

Returns

The above command returns JSON structured like this:

[
    {
        "id": "5b0d0f4f1a0000bdd53824e2",
        "name": "My Artist"
    }
]
Attribute Required Description
data array <object> array of artist's list summary object

Search Artists (New)

Returns a list of artists associated to a specific api_key for a given search term

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/artists/search?term=artist&page=1&limit=1

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
term string Search term (Optional). If not specified, all artists are included.
page number Page number (Optional, Default 1)
limit number Number of result per page (Optional, Default 10. Max 100)
exact boolean Indicate either to run exact search or phrase search (Optional, default false)

Returns

The above command returns JSON structured like this:

{
    "page": 1,
    "pages": 10,
    "data": [
        {
            "id": "5b0d0f4f1a0000bdd53824e2",
            "name": "My Artist"
        }
    ]
}
Attribute Required Description
page number The page number being returned
pages number number of pages available
data array <object> array of artist's list summary object filtered by the given search term

Get Artist

Retrieves the details of an existing artist. You need only supply the unique artist identifier that was returned upon artist creation.

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/artist/{id}

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
id string The id of the artist to retrieve

Returns

Returns an artist object if a valid identifier was provided.

Create Artist

Creates artist object

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/artist

{
    "artistName": "Feature.fm",
    "artistImage": "http://www.feature.fm/blog/assets/images/feature_fm_no_text_logo.png?v=7d8241cd74",
    "type": "artist",
    "countryCode": "IL",
    "shortBio": "My Biography",
    "websiteUrl": "http://feature.fm",
    "facebookPage": "https://www.facebook.com/Featurefm-497931363607317/",
    "twitterUrl": "https://twitter.com/featurefm?lang=en",
    "youtubeChannel": "https://www.youtube.com/channel/UCY1B_SZrt8sWNScujMCoNWw",
    "spotifyArtistUrl": "",
    "tags": ["tag1", "tag2"],
    "linkSettings": {
        "defaultStores": [
            "spotify",
            "amazon",
            "soundcloud",
            "apple",
            "deezer",
            "youtube"
        ],
        "customDomains": [
            {
                "domain": "custom.ffm.to",
                "isDefault": true
            }
        ],
        "notifications": {
            "toggle": true,
            "showArtistImage": true,
            "message": "Thank you for pre-saving my release",
            "subject": "My new release is out and available in your library"
        },
        "localization": [
            {
                "locale": "default",
                "callToActionText": "Choose your preferred music service",
                "enabledStores": [
                    {
                        "storeId": "youtube",
                        "actionName": "Watch Now"
                    },
                    {
                        "storeId": "spotify",
                        "actionName": "Play Now"
                    },
                    {
                        "storeId": "amazon",
                        "actionName": "Download Now"
                    }
                ],
                "disabledStores": [
                    {
                        "storeId": "deezer",
                        "actionName": "Play Now"
                    },
                    {
                        "storeId": "soundcloud",
                        "actionName": "Stream Now"
                    }
                ]
            },
            {
                "locale": "fr",
                "callToActionText": "Choisissez votre service de musique préféré",
                "enabledStores": [
                    {
                        "storeId": "amazon",
                        "actionName": "Jouer"
                    },
                    {
                        "storeId": "spotify",
                        "actionName": "Jouerify"
                    }
                ],
                "disabledStores": [
                    {
                        "storeId": "tidal",
                        "actionName": "Touer"
                    },
                    {
                        "storeId": "apple",
                        "actionName": "Fichsse"
                    }
                ]
            }
        ],
        "pixels": {
            "facebook": "123456789",
            "google": "123456789",
            "googleTagManager": "123456789"
        },
        "affiliates": {
            "apple": "apple_affiliate_code",
            "amazon": [
                {
                    "tag": "big",
                    "countryCode": "us"
                },
                {
                    "tag": "small",
                    "countryCode": "il"
                }
            ]
        },
        "analytics": {
            "google": "UA-9876-1"
        },
        "legal": {
            "termsOfServiceUrl": "https://en.wikipedia.org/wiki/Angelina_Jolie",
            "privacyPolicyUrl": "https://www.facebook.com/angelinajoliegoddess/"
        }
    }
}

POST Parameters

Attribute Type Description
artistName string The artist name (Required)
artistImage string A valid url to artist image (Optional)
type string valid options: artist/band (Required)
countryCode string ISO 3166-1 alpha-2 code (ex. US) (Required)
shortBio string Short bio of the artist/band (Optional)
websiteUrl string Url to the artist website (Optional)
facebookPage string Facebook page url (Optional)
twitterUrl string Twitter full url or twitter handle for the artist/band profile (Optional)
youtubeChannel string Youtube url for the artist channel (Optional)
spotifyArtistUrl string Url to the artist profile on Spotify (Optional)
tags array An array of strings representing tags associated with the artist. These tags can be used for categorization, searching, and filtering (Optional)
linkSettings object Default SmartLink/Action Pages settings (Optional). If not provided will derived from the account defaults

Returns

Returns an artist object if a valid identifier was provided.

Update Artist

Update artist object

curl -v -X PUT -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/artist/{id}

{
    "artistName": "Feature.fm",
    "artistImage": "http://www.feature.fm/blog/assets/images/feature_fm_no_text_logo.png?v=7d8241cd74",
    "type": "artist",
    "countryCode": "IL",
    "shortBio": "My Biography",
    "websiteUrl": "http://feature.fm",
    "facebookPage": "https://www.facebook.com/Featurefm-497931363607317/",
    "twitterUrl": "https://twitter.com/featurefm?lang=en",
    "youtubeChannel": "https://www.youtube.com/channel/UCY1B_SZrt8sWNScujMCoNWw",
    "spotifyArtistUrl": "",
    "tags", ["tag1", "tag2", "tag3"],
    "linkSettings": {
        "defaultStores": [
            "spotify",
            "amazon",
            "soundcloud",
            "apple",
            "deezer",
            "youtube"
        ],
        "customDomains": [
            {
                "domain": "custom.ffm.to",
                "isDefault": true
            }
        ],
        "localization": [
            {
                "locale": "default",
                "callToActionText": "Choose your preferred music service",
                "enabledStores": [
                    {
                        "storeId": "youtube",
                        "actionName": "Watch Now"
                    },
                    {
                        "storeId": "spotify",
                        "actionName": "Play Now"
                    },
                    {
                        "storeId": "amazon",
                        "actionName": "Download Now"
                    }
                ],
                "disabledStores": [
                    {
                        "storeId": "deezer",
                        "actionName": "Play Now"
                    },
                    {
                        "storeId": "soundcloud",
                        "actionName": "Stream Now"
                    }
                ]
            },
            {
                "locale": "fr",
                "callToActionText": "Choisissez votre service de musique préféré",
                "enabledStores": [
                    {
                        "storeId": "amazon",
                        "actionName": "Jouer"
                    },
                    {
                        "storeId": "spotify",
                        "actionName": "Jouerify"
                    }
                ],
                "disabledStores": [
                    {
                        "storeId": "tidal",
                        "actionName": "Touer"
                    },
                    {
                        "storeId": "apple",
                        "actionName": "Fichsse"
                    }
                ]
            }
        ],
        "pixels": {
            "facebook": "123456789",
            "google": "123456789",
            "googleTagManager": "123456789"
        },
        "affiliates": {
            "apple": "apple_affiliate_code",
            "amazon": [
                {
                    "tag": "big",
                    "countryCode": "us"
                },
                {
                    "tag": "small",
                    "countryCode": "il"
                }
            ]
        },
        "analytics": {
            "google": "UA-9876-1"
        },
        "legal": {
            "termsOfServiceUrl": "https://en.wikipedia.org/wiki/Angelina_Jolie",
            "privacyPolicyUrl": "https://www.facebook.com/angelinajoliegoddess/"
        }
    }
}

PUT Parameters

Attribute Type Description
artistName string The artist name (Required)
artistImage string A valid url to artist image (Optional)
type string valid options: artist/band (Required)
countryCode string ISO 3166-1 alpha-2 code (ex. US) (Required)
shortBio string Short bio of the artist/band (Optional)
websiteUrl string Url to the artist website (Optional)
facebookPage string Facebook page url (Optional)
twitterUrl string Twitter full url or twitter handle for the artist/band profile (Optional)
youtubeChannel string Youtube url for the artist channel (Optional)
spotifyArtistUrl string Url to the artist profile on Spotify (Optional)
tags array An array of strings representing tags associated with the artist. These tags can be used for categorization, searching, and filtering (Optional)
linkSettings object Default SmartLink/Action Pages settings (Optional)

Returns

If success, Returns the artist object, otherwise, returns error code.

As the update is a PUT request, the entire Artist object should be sent with your request. Empty fields will be treated as missing (Required params) or empty values (Optional params)

SmartLink object allow you to define a behaviour for SmartLink pages, pre-save pages and future release pages. You can create Track, Album, Playlist or content link, update or fetch the link data including real-time analytics. You can retrieve individual SmartLink as well as a list of all your SmartLinks.

The below JSON is an example of a SmartLink object:

{
    "id": "5ad4a2b11e0000f94a1cf85b",
    "artistId": "5ad4a2b11e0000f94a1cf85c",
    "shortId": "greatest_hits",
    "createdAt": 1526373512,
    "status": "ACTIVE",
    "scanLink": "https://itunes.apple.com/il/album/sweet-child-o-mine/68192941?i=68192994",
    "domain": "https://ffm.to",
    "pageLayout": "base_layout",
    "title": "Greatest Hits",
    "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
    "description": "Listen to my Album",
    "preReleaseDescription": "Save Now!",
    "background": {
        "type": "blur",
        "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg"
    },
    "stores": [
        {
            "storeId": "apple",
            "url": "https://geo.itunes.apple.com/us/album/fields-of-joy/712308582?i=712308671&app=music"
        },
        {
            "storeId": "spotify",
            "url": "https://open.spotify.com/track/0XcR8kUxhai3H7wqB0R2eE"
        },
        {
            "storeId": "deezer",
            "url": "https://www.deezer.com/en/playlist/1354282275"
        }
    ],
    "preview": {
        "storeId": "apple",
        "url": "https://audio-ssl.itunes.apple.com/apple-assets-us-std-000001/Music1/v4/fa/8e/ab/fa8eab5b-cd77-3b4d-8931-1943e61d47de/mzaf_6427571633371052040.plus.aac.p.m4a"
    },
    "enabledStores": [
        {
            "storeId": "spotify",
            "actionName": "Play Now"
        }
    ],    
    "localization" : [
        {
            "locale": "fr",
            "title": "French Title",
            "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
            "description": "French description",
            "preview" : {
                "storeId": "deezer",
                "url": "https://www.amazon.com/Sweet-Child-Mine-Lost-Roses/dp/1945322071"
            },
            "enabledStores": [
                {
                    "storeId": "deezer",
                    "actionName": "Play"
                }
            ],
            "conditionalRouting": [
                {
                    "condition": "ios",
                    "storeId": "deezer"
                }
            ],
            "routingRules": {
                "idleTimeoutRouting": {
                    "timeout": 2,
                    "storeId": "spotify"
                },
                "usePreferredService": true
            }
        },
        {
            "locale": "gb",
            "title": "Great Title"
        }
    ],
    "conditionalRouting": [{
        "condition": "ios",
        "storeId": "spotify"
    }],
    "routingRules": {
        "idleTimeoutRouting": {
            "timeout": 2,
            "storeId": "spotify"
        },
        "usePreferredService": true
    },
    "songName": "Greatest Hits",
    "albumName": "Greatest Hits",
    "pixels": {
        "facebook": "123456999",
        "google": "123456998",
        "googleTagManager": "123456997"
    },
    "affiliates": {
        "apple": "app",
        "amazon": [{
            "tag": "sweet-fr",
            "countryCode": "fr"
        },{
            "tag": "sweet-uk",
            "countryCode": "gb"
        }]
    },
    "analytics": {
        "google": "UA-4444-5"
    },
    "legal": {
        "termsOfServiceUrl": "https://en.wikipedia.org/wiki/Slash_(musician)",
        "privacyPolicyUrl": "https://en.wikipedia.org/wiki/Axl_Rose"
    },
    "targeting": {
        "artists": [
            "Guns&Roses"
        ],
        "tags": [
            "rock",
            "alternative"
        ]
    },
    "emailCollection": {
        "enabled": true,
        "title": "Stay Tuned",
        "actionButton": "Subscribe"
    },
    "socialIcons": {
        "enabled": true,
        "useArtistDefaults": false,
        "socialLinks": {
            "facebook": "https://facebook.com/pluf",
            "instagram": "https://instagram.com/plupi",
            "twitter": "https://twitter.com/twit",
            "youtube": "https://youtube.com/yoyo",
            "spotify": "https://open.spotify.com/artist/slus",
            "soundcloud": "https://soundcloud.com/cluc",
            "other": "https://www.other.com",
        },
    },
    "socialEmbeds": {
        "title": "soctit",
        "description": "social media desc",
        "preReleaseDescription": "Save Now!",
        "image": "https://image.shutterstock.com/image-vector/cute-funny-hippo-450w-351867221.jpg",
    }    
}
Attribute Type Description
id string The SmartLink id
artistId string The artist id associated with the SmartLink object
shortId string SmartLink short code
createdAt date Timestamp of the SmartLink creation
status string The status of the SmartLink. Valid options are: "ACTIVE", "ARCHIVED"
scanLink string the target link that is used to auto generate the SmartLink page
domain string The domain specified for this SmartLink
pageLayout string Page layout for the SmartLink. Valid options are: 'base_layout' or 'action_page'
title string SmartLink page title
image string SmartLink image url
type string Type of link. Valid options are: "post_release", "future_release", "pre_release"
description string SmartLink page description
background object The styling of the background of the Smart Link page. Available options are the default blur of the hero image, a solid color, or an image
preReleaseDescription string SmartLink Pre Release Description. After Release the description will be used
stores array <object> List of music stores object associated with this SmartLink
preview object SmartLink preview object
enabledStores array <object> Ordered list of music stores to show on display for the current link page
disabledStores array <object> list of music stores to hide from display for the current link page
localization array <object> List of customized locale display options
conditionalRouting object Allow customized routing rules per browser/channel
routingRules object Setting fans idle timeout behavior and allow direct linking to user preferred service (Optional)
songName string The song name associated with the SmartLink (in case of track link)
albumName string The album name associated with the SmartLink (in case of album or track link)
pixels object Re-targeting pixels object for ad re-targeting
affiliates object Affiliates object representing your affiliate programs that are connected to your SmartLink (such as Apple or Amazon)
analytics object Analytics object representing your analytics programs that are connected to your SmartLink (such as Google analytics)
saveSuccessfulMessage string Message to show after successful save
legal object Legal object, defines the SmartLink privacy policy and terms of service URLs
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs
preSaveFollow object Pre Save Follow object, currently, only spotify supported (Optional)
emailCollection object Enable Widget to collect fans emails
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Background Object Details

Attribute Type Description
type string This is the kind of background declared for the Smart Link. Allowed values are: blue, color, image
color string Required when type is color and must be ‘hex’ format (example: #000000)
image string Required when type is image. Value must be the URL to a hosted image

Attribute Type Description
storeId string Store id (See stores list to find allowed values)
url string url to the media file to play. Valid options are: MP3, MP4a, YouTube URL (only in case the store is YouTube), SoundCloud URL (only in case the store is SoundCloud)

Enabled Stores Object Details

Attribute Type Description
storeId string Store id (See stores list to find allowed values)
actionName string Action name to display when displaying the store on a SmartLink page
preSaveActionName string Store's action name to display when displaying a Pre-Save/Pre-Order SmartLink page.

Attribute Type Description
enabled boolean Show/Hide email collection
title string Email collection title text
actionButton string Email collection button text

Attribute Type Description
enabled boolean Show/Hide social icons
useArtistDefaults boolean Inherit social links from the artist object
socialLinks Map Social links Map. override artist default. Supported: facebook, instagram, twitter, youtube, spotify, tiktok, soundcloud, other

Attribute Type Description
title string Social title
description string Social description
preReleaseDescription string SmartLink Pre Release Description. After Release the description will be used
image string Social embeded image link

Disabled Stores Object Details

Attribute Type Description
storeId string Store id (See stores list to find allowed values)
actionName string Action name to display when displaying the store on a SmartLink page

Conditional Routing Object Details

Attribute Type Description
condition string Device (ios, android, desktop) or channel code
storeId string redirect to store id when condition match

Routing Rules Object Details

Attribute Type Description
idleTimeoutRouting object Send fans to a destination of your choice if they don't click on any service buttons on your landing page
usePreferredService boolean Automatically send fans to their preferred service if they've visited a Feature.fm link before

Idle Timeout Object Details

Attribute Type Description
timeout integer The number of seconds a user can remain inactive on the page before being automatically redirected to a service of your choise
storeId string Store id (See stores list to find allowed values)

Attribute Type Description
locale string Locale code (ISO 3166-1 alpha-2 code)
title string Locale page title
image string Locale image url
description string Locale page description
preReleaseDescription string SmartLink Pre Release Description. After Release the description will be used
preview object Locale preview object
conditionalRouting array <object> Locale customized routing rules per browser/channel
routingRules object Locale customized setting for fans idle timeout behavior and sirect linking settings (Optional)
enabledStores array <object> Locale ordered list of music stores to display for the current link page
disabledStores array <object> Locale list of music stores to hide from display for the current link page

Retargeting Pixels Object Details

Attribute Type Description
google string Google adwords remarketing id
facebook string Facebook re-targeting pixel id
tiktok string TikTok re-targeting pixel id
googleTagManager string Google tag manager id

Affiliates Object Details

Attribute Type Description
amazon array List of amazon affiliate objects
apple string Apple affiliate id
spotify string Spotify affiliate id

Amazon Affilaite Object

Attribute Type Description
tag string Amazon affiliate tag
countryCode string The country code that the amazon tag applied to (ISO 3166-1 alpha-2 code)

Analytics Object Details

Attribute Type Description
google string Google analytics id

Attribute Type Description
privacyPolicyUrl string Url for the privacy policy of the SmartLink page
termsOfServiceUrl string Url for the privacy policy of the SmartLink page

Targeting Object Details

Attribute Type Description
tags array Free text list of tags that will be sent with the retargeting pixels (ie. rock, pop, happy)
artists array Free text list of artists relevant for this link, it will be sent with the re-targeting pixels

Pre Save Follow Entity Object Details

Attribute Type Description
url string Spotify URL. allowed User, Playlist, Artist

Pre Save Follow Object Details

Attribute Type Description
storeId string Music store id. currently, only spotify is suppotred
entities array <object> Entities to follow, max allowed 3 entities

Fan Notification Object Details

Attribute Type Description
toggle boolean Indicate the status of the Fan Notification feature on the SmartLink
showArtistImage boolean Indicate to display the Artist Image in the header of the email. If the value is ‘true’, the image will show
message string The text shown in the body of the Fan Notification email (maximum 150 characters)
subject string The text of the subject line of the Fan Notification email (maximum 64 characters)
artistName string The text of the artist name (maximum 64 characters)
releaseName string The text of the release name (maximum 64 characters)
artistImage string Artist image URL
releaseImage string Release image URL

Music Store Object Details

Attribute Type Description
id string Music store id
url string The content url for this music store
fallbackUrl string The destination a fan is directed to after a successful pre-save. The value must be a valid URL
autoScan boolean Should this store be auto scanned for a URL
title string Title of the url content
streamType string Valid options are: "track", "album", "playlist"
showAfterRelease boolean show store only after the release date (Optional, default false)
tracks array In case of album or playlist, list of tracks preview (Up to 30 secs)
territories array <object> List of MusicStoreTerritory objects that define custom music store urls for specific territories

Music Store Territory Object Details

Attribute Type Description
countryCode string Valid country code (ISO 3166-1 alpha-2 code)
webUrl string The content url for this country
mobileUrl string The mobile url for this country

In some API endpoints, where we do not need all the SmartLink object data, a summary object can be returned with a subset of the SmartLink object information (useful listing SmartLinks)

The below JSON is an example of a SmartLink object:

{
    "id": "5ad4a2b11e0000f94a1cf85b",
    "createdAt": 1523884721506,
    "artist": "599450031b0000a208fcbc85",
    "status": "ACTIVE",
    "type": "post_release",
    "domain": "https://ffm.to",
    "scanLink": "https://open.spotify.com/album/3OW1dbZnmZpAMtTUVgQ1pu",
    "shortId": "0b0rnrn",
    "title": "Lenny Kravitz - Fly Away",
    "image": "https://is1-ssl.mzstatic.com/image/thumb/Music6/v4/b2/e2/1b/b2e21bd2-e67e-ce9d-20dc-3f5faa5b8cb2/source/500x0w.jpg",
}
Attribute Type Description
id string The SmartLink id
createdAt date Timestamp of the SmartLink creation
artist string The artist id associated with the SmartLink object
status string The status of the SmartLink. Valid options are: "ACTIVE", "ARCHIVED"
type string Type of link. Valid options are: "post_release", "future_release", "pre_release"
domain string domain to be used for this SmartLink
shortId string SmartLink short code
title string SmartLink page title
image string SmartLink image url

Retrieves the details of an existing SmartLink. You need only supply the unique SmartLink identifier that was returned upon SmartLink creation.

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/smartlink/{id}

GET Parameters

Parameter Required Description
id true The id of the SmartLink to retrieve

Returns

Returns a SmartLink object if a valid identifier was provided.

Attribute Type Description
status string "success" if was successful
data object SmartLink object details

Retrieves the details of an existing SmartLink by short id and domain. The domain parameter should not include the HTTP protocol.

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/smartlink/shortid/{shortId}?domain={domainName}

GET Parameters

Parameter Required Description
shortid true The short id of the SmartLink to retrieve
domainName true The domain of the smartlink (e.g.: ffm.to)

Returns

Returns a SmartLink object if a valid identifier/s were provided.

Creates a new post release SmartLink object. If your music has already been released and is now available to stream or buy.

If you already know the end destinations for some of your stores, you can skip part of the scanning process. See the following example:

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/smartlink

{
    "artistId": "5ad4a2b11e0000f94a1cf85c",
    "scanLink": "https://itunes.apple.com/il/album/sweet-child-o-mine/68192941?i=68192994",
    "domain": "https://ffm.to",
    "pageLayout": "base_layout",
    "title": "Greatest Hits",
    "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
    "description": "Listen to my Album",
    "background": {
        "type": "image",
        "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg"
    },
    "stores": [
        {
            "storeId": "apple",
            "url": "https://geo.itunes.apple.com/us/album/fields-of-joy/712308582?i=712308671&app=music"
        },
        {
            "storeId": "spotify",
            "url": "https://open.spotify.com/track/0XcR8kUxhai3H7wqB0R2eE"
        },
        {
            "storeId": "deezer",
            "url": "https://www.deezer.com/en/playlist/1354282275"
        }
    ],
    "preview": {
        "storeId": "apple",
        "url": "https://audio-ssl.itunes.apple.com/apple-assets-us-std-000001/Music1/v4/fa/8e/ab/fa8eab5b-cd77-3b4d-8931-1943e61d47de/mzaf_6427571633371052040.plus.aac.p.m4a"
    },
    "enabledStores": [
        {
            "storeId": "spotify",
            "actionName": "Play Now"
        }
    ],    
    "localization" : [
        {
            "locale": "fr",
            "title": "French Title",
            "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
            "description": "French description",
            "preview" : {
                "storeId": "deezer",
                "url": "https://www.amazon.com/Sweet-Child-Mine-Lost-Roses/dp/1945322071"
            },
            "enabledStores": [
                {
                    "storeId": "deezer",
                    "actionName": "Play"
                }
            ],
            "conditionalRouting": [
                {
                    "condition": "ios",
                    "storeId": "deezer"
                }
            ],
            "routingRules": {
                "idleTimeoutRouting": {
                    "timeout": 10,
                    "storeId": "spotify"
                },
                "usePreferredService": true
            }
        },
        {
            "locale": "gb",
            "title": "Great Title"
        }
    ],
    "conditionalRouting": [{
        "condition": "ios",
        "storeId": "spotify"
    }],
    "routingRules": {
        "idleTimeoutRouting": {
            "timeout": 2,
            "storeId": "deezer"
        },
        "usePreferredService": true
    },
    "songName": "Greatest Hits",
    "albumName": "Greatest Hits",
    "pixels": {
        "facebook": "123456999",
        "google": "123456998",
        "googleTagManager": "123456997"
    },
    "affiliates": {
        "apple": "app",
        "amazon": [{
            "tag": "sweet-fr",
            "countryCode": "fr"
        },{
            "tag": "sweet-uk",
            "countryCode": "gb"
        }]
    },
    "analytics": {
        "google": "UA-4444-5"
    },
    "legal": {
        "termsOfServiceUrl": "https://en.wikipedia.org/wiki/Slash_(musician)",
        "privacyPolicyUrl": "https://en.wikipedia.org/wiki/Axl_Rose"
    },
    "targeting": {
        "artists": [
            "Guns&Roses"
        ],
        "tags": [
            "rock",
            "alternative"
        ]
    }
}

To create a SmartLink that all stores is automatically being generated from a scan link you can use this example:

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/smartlink

{
    "artistId": "5dd4a2b11e0000f94a1cf85c",
    "shortId": "greatest_hits",
    "domain": "https://ffm.to",
    "scanLink": "https://www.youtube.com/watch?v=aNFvM5XqF8g",
}

POST Parameters

Parameter Type Description
artistId string The artist id associated with the SmartLink object (Required)
shortId string SmartLink short code (Required)
transactionId uuid provide a valid GUID identifying this specific transaction. If connection lost you can use the same body with the transactionId and retrieve the original response (Optional)
scanLink string the target link that is used to auto generate the SmartLink page (Optional if stored provided)
domain string The domain specified for this SmartLink (Optional, default: ffm.to). to use custom domain, please add it first to the link associated artist
pageLayout string Page layout for the SmartLink. Valid options are: 'base_layout' or 'action_page' (Optional, default: base_layout)
title string SmartLink page title (Optional, if scanLink exists, it will try to automatically fill)
image string SmartLink image url (Optional, if scanLink exists, it will try to automatically fill)
description string SmartLink page description (Optional)
stores array <object> List of music stores object associated with this SmartLink (Optional if scanLink provided).
preview object SmartLink preview object (Optional)
enabledStores array <object> List of music stores to display (Optional. All stores are visible)
localization array <object> List of customized locale display options (Optional. if empty, all locale will use defaults)
conditionalRouting object Allow customized routing rules per browser/channel (Optional)
routingRules object Setting fans idle timeout behavior and allow direct linking to user preferred service (Optional)
songName string The song name associated with the SmartLink (in case of track link) (Optional)
albumName string The album name associated with the SmartLink (in case of album or track link) (Optional)
pixels object Re-targeting pixels object for ad re-targeting (Optional)
affiliates object Affiliates object representing your affiliate programs that are connected to your SmartLink (such as Apple or Amazon) (Optional)
analytics object Analytics object representing your analytics programs that are connected to your SmartLink (such as Google analytics) (Optional)
legal object Legal object, defines the SmartLink privacy policy and terms of service URLs (Optional)
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs (Optional)
emailCollection object Enable Widget to collect fans emails
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Returns

If success, Returns the SmartLink object, otherwise, returns error code.

Creates a new future release SmartLink object. Your music is not released yet, but you want to create your link ahead of time so it's ready on release date. On release date, the link converts to post release link and all marked stores are scanned.

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/smartlink/future-release

{
    "artistId": "5dd4a2b11e0000f94a1cf85c",
    "releaseDate": "2028-05-18",
    "timezone": "America/New_York",
    "domain": "https://ffm.to",
    "scanLink": "https://itunes.apple.com/il/album/sweet-child-o-mine/68192941?i=68192994",
    "stores": [
        {
            "storeId": "apple"
        },
        {
            "storeId": "spotify"
        },
        {
            "storeId": "youtube"
        },
        {
            "storeId": "deezer",
            "url": "https://www.deezer.com/en/playlist/1354282275"
        }
    ],
    "title": "Greatest Hits",
    "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg"
}

POST Parameters

Parameter Required Description
releaseDate Date The release date of the song / album (Required)
releaseTime string The release time (HH:MM 24-hour) of the song / album, default 00:00
timezone string The release date's full timezone name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List)
artistId string The artist id associated with the SmartLink object (Required)
transactionId uuid provide a valid GUID identifying this specific transaction. If connection lost you can use the same body with the transactionId and retrieve the original response (Optioanl)
shortId string SmartLink short code (Required)
scanLink string the target link that is used to auto generate the SmartLink page (Required)
domain string The domain specified for this SmartLink (Optional, default: ffm.to). to use custom domain, please add it first to the link associated artist
background object The styling of the background of the Smart Link page. Available options are the default blur of the hero image, a solid color, or an image
pageLayout string Page layout for the SmartLink. Valid options are: 'base_layout' or 'action_page' (Optional, default: base_layout)
title string SmartLink page title (Optional, if scanLink exists, it will try to automatically fill)
image string SmartLink image url (Optional, if scanLink exists, it will try to automatically fill)
description string SmartLink page description (Optional)
preReleaseDescription string SmartLink Pre Release Description. After Release the description will be used (Optional)
stores array <object> List of music stores object associated with this SmartLink (Required).
preview object SmartLink preview object (Optional)
enabledStores array <object> List of music stores to display (Optional. All stores are visible)
localization array <object> List of customized locale display options (Optional. if empty, all locale will use defaults)
conditionalRouting object Allow customized routing rules per browser/channel (Optional)
routingRules object Setting fans idle timeout behavior and allow direct linking to user preferred service (Optional)
songName string The song name associated with the SmartLink (in case of track link) (Optional)
albumName string The album name associated with the SmartLink (in case of album or track link) (Optional)
pixels object Re-targeting pixels object for ad re-targeting (Optional)
affiliates object Affiliates object representing your affiliate programs that are connected to your SmartLink (such as Apple or Amazon) (Optional)
analytics object Analytics object representing your analytics programs that are connected to your SmartLink (such as Google analytics) (Optional)
legal object Legal object, defines the SmartLink privacy policy and terms of service URLs (Optional)
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs (Optional)
emailCollection object Enable Widget to collect fans emails
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Returns

If success, Returns the SmartLink object, otherwise, returns error code.

Creates a new pre-save release SmartLink object. Your music is not released, but you want to share it as a Pre-Order or Pre-Save (Spotify / Deezer) until release day

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/smartlink/pre-save

{
    "artistId": "5dd4a2b11e0000f94a1cf85c",
    "releaseDate": "2028-05-18",
    "timezone": "America/New_York",
    "domain": "https://ffm.to",
    "background": {
        "type": "blur"
    },
    "notifications": {
        "toggle": true,
        "showArtistImage": true,
        "message": "Thank you for pre-saving my release",
        "subject": "My new release is out and available in your library",
        "artistName": "Guns N' Roses",
        "releaseName": "100% Guns N' Roses",
        "artistImage": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
        "releaseImage": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg"
    },
    "stores": [
        {
            "storeId": "apple",
            "url": "https://geo.itunes.apple.com/us/album/fields-of-joy/712308582?i=712308671&app=music"
        },
        {
            "storeId": "spotify",
            "url": "",
            "fallbackUrl": "https://open.spotify.com/track/0XcR8kUxhai3H7wqB0R2eE"
        },
        {
            "storeId": "deezer",
            "url": "https://www.deezer.com/en/playlist/1354282275"
        }
    ],
    "preSaveFollow": [
        {
            "storeId": "spotify",
            "entities": [
                {
                    "url": "https://open.spotify.com/artist/6tbjWDEIzxoDsBA1FuhfPW"
                },
                {
                    "url": "https://open.spotify.com/playlist/3JiPfA9qVRzQcOEixkQB5Z"
                }
            ]
        }
    ],
    "title": "Greatest Hits",
    "emailCollection": {
        "enabled": true,
        "title": "Stay Tuned",
        "actionButton": "Subscribe"
    },    
    "preReleaseDescription": "Save Now!",
    "description": "Listen To",
    "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
    "enableFutureSave": true
}

POST Parameters

Parameter Required Description
releaseDate Date The release date of the song / album (Required)
releaseTime string The release time (HH:MM 24-hour) of the song / album, default 00:00
isLocalRelease boolean Allow to set a local release for each territory (Optional, default false)
scanLink string the target link/upc/isrc that is used to auto generate the SmartLink page on release date
timezone string The release date's full timezone name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (Optional if local release)
background object The styling of the background of the Smart Link page. Available options are the default blur of the hero image, a solid color, or an image
artistId string The artist id associated with the SmartLink object (Required)
transactionId uuid provide a valid GUID identifying this specific transaction. If connection lost you can use the same body with the transactionId and retrieve the original response (Optional)
shortId string SmartLink short code (Required)
domain string The domain specified for this SmartLink (Optional, default: ffm.to). to use custom domain, please add it first to the link associated artist
pageLayout string Page layout for the SmartLink. Valid options are: 'base_layout' or 'action_page' (Optional, default: base_layout)
title string SmartLink page title (Required)
image string SmartLink image url (Required)
description string SmartLink page description (Optional)
preReleaseDescription string SmartLink Pre Release Description. After Release the description will be used (Optional)
enableFutureSave boolean When the value is true, the Smart Link both collects new Future Save opt-ins after a successful pre-save as well as delivers the content to Future Save fans at time of conversion (Optional)
notifications object Fan notification settings for this specific link (Optional). This feature automatically notifies fans that pre-save when your release is available. For this feature to work - it should be activated by contacting clientservices@feature.fm
stores array <object> List of music stores object associated with this SmartLink (Required). Spotify/Deezer url is optional as pre-save is allowed before the link is available. For other stores, in case they provided, url parameter is mandatory and should contains the pre-order page url.
preview object SmartLink preview object (Optional)
enabledStores array <object> List of music stores to display (Optional. All stores are visible)
localization array <object> List of customized locale display options (Optional. if empty, all locale will use defaults)
conditionalRouting object Allow customized routing rules per browser/channel (Optional)
routingRules object Setting fans idle timeout behavior and allow direct linking to user preferred service (Optional)
songName string The song name associated with the SmartLink (in case of track link) (Optional)
albumName string The album name associated with the SmartLink (in case of album or track link) (Optional)
pixels object Re-targeting pixels object for ad re-targeting (Optional)
affiliates object Affiliates object representing your affiliate programs that are connected to your SmartLink (such as Apple or Amazon) (Optional)
analytics object Analytics object representing your analytics programs that are connected to your SmartLink (such as Google analytics) (Optional)
legal object Legal object, defines the SmartLink privacy policy and terms of service URLs (Optional)
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs (Optional)
preSaveFollow object Pre Save Follow object, currently, only spotify supported (Optional)
emailCollection object Enable Widget to collect fans emails
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Rescans an existing SmartLink. Existing stores may be overridden by the scan result, however, stores which couldn't be resolved are not overridden

curl -v -X PUT -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/smartlink/{id}/rescan

{
    "scanLink": "ISRC:USSM10505527"
}
Parameter Required Description
scanLink boolean Link to rescan (Optional), If not specified - the current smartlink's scanLink will be rescanned.

Returns

If success, returns the SmartLink object, otherwise, returns error code.

curl -v -X PUT -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/smartlink/{id}

{
    "scanLink": "https://itunes.apple.com/il/album/sweet-child-o-mine/68192941?i=68192994",
    "domain": "https://ffm.to",
    "pageLayout": "base_layout",
    "title": "Greatest Hits",
    "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
    "description": "Listen to my Album",
    "background": {
        "type": "color",
        "image": "#000000"
    },
    "stores": [
        {
            "storeId": "apple",
            "url": "https://geo.itunes.apple.com/us/album/fields-of-joy/712308582?i=712308671&app=music"
        },
        {
            "storeId": "spotify",
            "url": "https://open.spotify.com/track/0XcR8kUxhai3H7wqB0R2eE"
        },
        {
            "storeId": "deezer",
            "url": "https://www.deezer.com/en/playlist/1354282275"
        }
    ],
    "preview": {
        "storeId": "apple",
        "url": "https://audio-ssl.itunes.apple.com/apple-assets-us-std-000001/Music1/v4/fa/8e/ab/fa8eab5b-cd77-3b4d-8931-1943e61d47de/mzaf_6427571633371052040.plus.aac.p.m4a"
    },
    "enabledStores": [
        {
            "storeId": "spotify",
            "actionName": "Play Now"
        }
    ],    
    "localization" : [
        {
            "locale": "fr",
            "title": "French Title",
            "image": "https://i.ytimg.com/vi/O1fHxPY3TJo/hqdefault.jpg",
            "description": "French description",
            "preview" : {
                "storeId": "deezer",
                "url": "https://www.amazon.com/Sweet-Child-Mine-Lost-Roses/dp/1945322071"
            },
            "enabledStores": [
                {
                    "storeId": "deezer",
                    "actionName": "Play"
                }
            ],
            "conditionalRouting": [
                {
                    "condition": "ios",
                    "storeId": "deezer"
                }
            ],
            "routingRules": {
                "idleTimeoutRouting": {
                    "timeout": 5,
                    "storeId": "spotify"
                },
                "usePreferredService": true
            }
        },
        {
            "locale": "gb",
            "title": "Great Title"
        }
    ],
    "conditionalRouting": [{
        "condition": "ios",
        "storeId": "spotify"
    }],
    "routingRules": {
        "idleTimeoutRouting": {
            "timeout": 4,
            "storeId": "spotify"
        },
        "usePreferredService": true
    },
    "songName": "Greatest Hits",
    "albumName": "Greatest Hits",
    "pixels": {
        "facebook": "123456999",
        "google": "123456998",
        "googleTagManager": "123456997"
    },
    "affiliates": {
        "apple": "app",
        "amazon": [{
            "tag": "sweet-fr",
            "countryCode": "fr"
        },{
            "tag": "sweet-uk",
            "countryCode": "gb"
        }]
    },
    "analytics": {
        "google": "UA-4444-5"
    },
    "legal": {
        "termsOfServiceUrl": "https://en.wikipedia.org/wiki/Slash_(musician)",
        "privacyPolicyUrl": "https://en.wikipedia.org/wiki/Axl_Rose"
    },
    "targeting": {
        "artists": [
            "Guns&Roses"
        ],
        "tags": [
            "rock",
            "alternative"
        ]
    }
}

PUT Parameters

Parameter Required Description
shortId string SmartLink short code
releaseDate Date The release date of the song / album
releaseTime string The release time (HH:MM 24-hour) of the song / album, default 00:00
timezone string The release date's full timezone name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List)
scanLink string the target link that is used to auto generate the SmartLink page (Optional if stored provided)
domain string The domain specified for this SmartLink (Optional, default: ffm.to). to use custom domain, please add it first to the link associated artist
background object The styling of the background of the Smart Link page. Available options are the default blur of the hero image, a solid color, or an image
pageLayout string Page layout for the SmartLink. Valid options are: 'base_layout' or 'action_page' (Optional, default: base_layout)
title string SmartLink page title (Optional, if scanLink exists, it will try to automatically fill)
image string SmartLink image url (Optional, if scanLink exists, it will try to automatically fill)
description string SmartLink page description (Optional)
preReleaseDescription string SmartLink Pre Release Description. After Release the description will be used (Optional)
stores array <object> List of music stores object associated with this SmartLink (Optional if scanLink provided)
preview object SmartLink preview object (Optional)
enabledStores array <object> List of music stores to display (Optional. All stores are visible)
localization array <object> List of customized locale display options (Optional. if empty, all locale will use defaults)
conditionalRouting object Allow customized routing rules per browser/channel (Optional)
routingRules object Setting fans idle timeout behavior and allow direct linking to user preferred service (Optional)
songName string The song name associated with the SmartLink (in case of track link) (Optional)
albumName string The album name associated with the SmartLink (in case of album or track link) (Optional)
pixels object Re-targeting pixels object for ad re-targeting (Optional)
affiliates object Affiliates object representing your affiliate programs that are connected to your SmartLink (such as Apple or Amazon) (Optional)
analytics object Analytics object representing your analytics programs that are connected to your SmartLink (such as Google analytics) (Optional)
legal object Legal object, defines the SmartLink privacy policy and terms of service URLs (Optional)
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs (Optional)
updateToPostRelease Boolean Used to convert pre-release link to post-release effective immediately
emailCollection object Enable Widget to collect fans emails
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Returns

If success, Returns the SmartLink object, otherwise, returns error code.

curl -v -X DELETE -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/smartlink/{id}

Parameters

Parameter Required Description
id true The id of the SmartLink to archive

Returns

If success, Returns an empty JSON, otherwise, returns error code.

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/smartlink/{id}/restore
Parameter Required Description
id true The id of the SmartLink to restore

Returns

If success, Returns the SmartLink object, otherwise, returns error code.

Returns a list of SmartLinks associated to a specific artist

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/artist/{artist}/smartlinks?search=faded&page=1&limit=1&pagingInfo=true

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
search string Search term (Optional). If not specified, all smartlinks are included.
page number Page number (Optional, Default 1)
limit number Number of result per page (Optional, Default 10. Max 100)
pagingInfo boolean Show pagination information (Optional)

Returns

The above command returns JSON structured like this:

[
    {
        "id": "5adf52c71b0000e303332e17",
        "title": "Faded Love",
        "type": "post_release",
        "status": "ACTIVE",
        "domain": "https://ffm.to",
        "shortId": "nk2bx8y",
        "artist": "599450031b0000a208fcbc85",
        "scanLink": "https://open.spotify.com/album/4bX8UQWtlQQPrJunO3K345",
        "artistName": "My Artist",
        "createdAt": 1524585159263,
        "image": "https://i.scdn.co/image/9e48265689d8896cb562fc49bcdd506bb2e1f018",
    }
]
Attribute Required Description
data array array of SmartLink summary object

Returns a list of smartlinks associated to a specific api_key for a given search term

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/smartlink?search=faded&page=1&limit=1&pagingInfo=true

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
search string Search term (Optional). If not specified, all smartlinks are included.
page number Page number (Optional, Default 1)
limit number Number of result per page (Optional, Default 10. Max 100)
pagingInfo boolean Show pagination information (Optional)

Returns

The above command returns JSON structured like this:

[
    {
        "id": "5adf52c71b0000e303332e17",
        "title": "Faded Love",
        "type": "post_release",
        "status": "ACTIVE",
        "domain": "https://ffm.to",
        "shortId": "nk2bx8y",
        "artist": "599450031b0000a208fcbc85",
        "scanLink": "https://open.spotify.com/album/4bX8UQWtlQQPrJunO3K345",
        "artistName": "My Artist",
        "createdAt": 1524585159263,
        "image": "https://i.scdn.co/image/9e48265689d8896cb562fc49bcdd506bb2e1f018",
    }
]

Returns

With pageInfo set to true:

{
    "page": 1,
    "pages": 12,
    "data": [
        {
            "id": "5adf52c71b0000e303332e17",
            "title": "Faded Love",
            "type": "post_release",
            "status": "ACTIVE",
            "domain": "https://ffm.to",
            "shortId": "nk2bx8y",
            "artist": "599450031b0000a208fcbc85",
            "scanLink": "https://open.spotify.com/album/4bX8UQWtlQQPrJunO3K345",
            "artistName": "My Artist",
            "createdAt": 1524585159263,
            "image": "https://i.scdn.co/image/9e48265689d8896cb562fc49bcdd506bb2e1f018",
        }
    ]
}
Attribute Required Description
page integer The number of the current page
pages integer Total number of pages in the search result
data array array of SmartLink summary object

Query Analytics & Audience

Returns SmartLink Analytics

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' "APIDOMAIN/manage/v1/smartlink/{smartlink}/analytics?start=2018-04-21&end=2018-04-29&timeZoneOffset=180"

The above command returns JSON structured like this:

{
    "totals": {
        "clicks": 40,
        "uniqueUsers": 6,
        "songPreviews": 0,
        "clicksToService": 48
    },
    "timeline": [{
        "date": "2017-12-05",
        "clicks": 2,
        "songPreviews": 0,
        "clicksToService": 1
    },{
        "date": "2017-12-06",
        "clicks": 1,
        "songPreviews": 0,
        "clicksToService": 0
    },{
        "date": "2017-12-07",
        "clicks": 1,
        "songPreviews": 0,
        "clicksToService": 1
    },{
        "date": "2017-12-08",
        "clicks": 32,
        "songPreviews": 0,
        "clicksToService": 0
    },{
        "date": "2017-12-09",
        "clicks": 1,
        "songPreviews": 0,
        "clicksToService": 26
    },{
        "date": "2017-12-10",
        "clicks": 1,
        "songPreviews": 0,
        "clicksToService": 16
    },{
        "date": "2018-02-06",
        "clicks": 2,
        "songPreviews": 0,
        "clicksToService": 4
    }],
    "channels": [{
        "name": "Direct Link (DL)",
        "clicks": 1,
        "songPreviews": 0,
        "clicksToService": 1
    },{
        "name": "Original",
        "clicks": 39,
        "songPreviews": 0,
        "clicksToService": 47
    }],
    "channelTypes": [
    {
        "name": "Organic",
        "clicks": 40,
        "songPreviews": 0,
        "clicksToService": 48
    }],
    "referrals": [{
        "name": "direct",
        "clicks": 40,
        "songPreviews": 0,
        "clicksToService": 48
    }],
    "streams": [{
        "name": "spotify",
        "clicks": 0,
        "songPreviews": 0,
        "clicksToService": 48
    }],
    "locations": [{
        "code": "FR",
        "clicks": 23,
        "songPreviews": 0,
        "clicksToService": 0
    },{
        "code": "US",
        "clicks": 17,
        "songPreviews": 0,
        "clicksToService": 48
    }],
    "follow": [
        {
            "follow": 1,
            "targetId": "3658521",
            "service": "tidal",
            "targetType": "artist",
            "name": "Bruno Mars",
        },
        {
            "follow": 1,
            "targetId": "10926",
            "service": "tidal",
            "targetType": "artist",
            "name": "Lenny Kravitz",
        }
    ],
    "audience": [{
        "service": "spotify",
        "service_user_id": "john.doe",
        "userData": {
            "displayName": "john.doe",
            "webUrl": "https://open.spotify.com/user/john.doe",
            "email": "john.doe@gmail.com",
            "image": "https://profile-images.scdn.co/images/userprofile/default/0319a3cde14b70dc6bc1c923634eff77326d3e02",
            "profileFollowers": 3,
            "country": "US",
            "birthdate": "1994-05-01",
            "playlistsFollowers": null,
            "subscriptionType": "free"
        }
    }]
}

Returns

Attribute Required Description
totals object Total analytics summary
timeline object Total analytics groups by timeline
channels object Total analytics grouped by channels
channelTypes object Total analytics grouped by channel types (Organic/Paid)
referrals object Total analytics grouped by referrals source
referralsSourceTypes object Total analytics grouped by referrals source type
activities object Total analytics grouped by activities
streams object Total analytics grouped by streams
locations object Total analytics grouped by locations
follow object Multiple follow statistics
audience object Only for pre release links. Shows data for users who Pre-Saved the link and agreed to share their contact.

Action Pages

The Action Page Object

The below JSON is an example of a Action Page object:

{
    "id": "5b02c896260000b596db4837",
    "artistId": "599450031b0000a208fcbc85",
    "shortId": "qby54qo",
    "domain": "https://ffm.to",
    "title": "Like I Do",
    "image": "https://i.scdn.co/image/2e55b9c247cc6b0b713fbbce9db0527a932f8748",
    "previewUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
    "description": "Choose your preferred music service",
    "localization": [{
        "locale": "US",
        "title": "Like I Do",
        "image": "https://i.scdn.co/image/2e55b9c247cc6b0b713fbbce9db0527a932f8748",
        "previewUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
        "description": "Choose your preferred music service",
        "actionButtons": [{
            "id": "9de244ec-5d62-48b9-9c09-e863ae882b14",
            "platformCode": "spotify",
            "actionCode": "pre_save",
            "actionText": "Pre-Save on Spotify",
            "releaseDate": "2020-05-21",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Your music library will update automatically on release day!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        }]
    }],
    "actionButtons": [
        {
            "id": "9de244ec-5d62-48b9-9c09-e863ae882b13",
            "platformCode": "spotify",
            "actionCode": "pre_save",
            "actionText": "Pre-Save on Spotify",
            "releaseDate": "2020-05-21",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Your music library will update automatically on release day!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        },
        {
            "id": "ddd4bcf9-de70-496b-9114-61d431125678",
            "platformCode": "spotify",
            "actionCode": "save",
            "actionText": "Save on Spotify",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Thanks for saving! Your music library has been updated",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        },
        {
            "id": "f61a0610-9f5d-4d70-b20d-1bec31447b7a",
            "platformCode": "spotify",
            "actionCode": "follow",
            "actionText": "Follow on Spotify",
            "linkUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "saveSuccessfulMessage": "Thanks for following!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        }
    ],
    "targeting": {
        "tags": [
            "bosanova"
        ],
        "artists": [
            "David Guetta"
        ]
    },
    "legal": {
        "privacyPolicyUrl": "https://www.sonymusic.com/privacy-policy/",
        "termsOfServiceUrl": "https://www.sonymusic.com/terms-and-conditions/"
    },
    "pixels": {
        "google": "2394872331",
        "googleTagManager": "GTM-1234",
        "facebook": "2342342331"
    },
    "affiliates": {
        "apple": "q234ru22",
        "amazon": [{
                "tag": "big",
                "countryCode": "us"
            },{
                "tag": "small",
                "countryCode": "il"
            }
        ]
    },
    "analytics": {
        "google": "UA-238572-353"
    },
    "songName": "Name",
    "albumName": "Name",
    "socialIcons": {
        "enabled": true,
        "useArtistDefaults": false,
        "socialLinks": {
            "facebook": "https://facebook.com/pluf",
            "instagram": "https://instagram.com/plupi",
            "twitter": "https://twitter.com/twit",
            "youtube": "https://youtube.com/yoyo",
            "spotify": "https://open.spotify.com/artist/slus",
            "soundcloud": "https://soundcloud.com/cluc",
            "other": "https://www.other.com",
        },
    },
    "socialEmbeds": {
        "title": "soctit",
        "description": "social media desc",
        "image": "https://image.shutterstock.com/image-vector/cute-funny-hippo-450w-351867221.jpg",
    }    
}
Attribute Type Description
id string The Action Page id
artistId string The artist id associated with the Action Page object
createdAt date Timestamp of the Action Page creation
status string The status of the Action Page. Valid options are: "ACTIVE", "ARCHIVED"
shortId string Action Page short code
domain string The domain specified for this Action Page.
title string Action Page title
image string Action Page image url
previewUrl string Action Page preview link. Supported URLs: Spotify, Apple, Amazon, Deezer, YouTube, SoundCloud, .MP3
description string Action Page description
localization array <object> List of customized locale display options
actionButtons string <object>
songName string The song name associated with the Action Page (in case of track link)
albumName string The album name associated with the Action Page (in case of album or track link)
pixels object Re-targeting pixels object for ad re-targeting
affiliates object Affiliates object representing your affiliate programs that are connected to your Action Page (such as Apple or Amazon)
analytics object Analytics object representing your analytics programs that are connected to your Action Page (such as Google analytics)
legal object Legal object, defines the Action Page privacy policy and terms of service URLs
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

ActionPage Localization Object Details

Attribute Type Description
locale string Locale code (ISO 3166-1 alpha-2 code)
title string Locale page title
image string Locale image url
description string Locale page description
previewUrl string Locale preview link. Supported URLs: Spotify, Apple, Amazon, Deezer, YouTube, SoundCloud, .MP3
actionButtons string <object>

ActionPage Localization Object Details

Attribute Type Description
id string Button ID
platformCode string Button platform code (currently only Spotify supported)
actionCode string Button action code. Suppotred: pre_save, save, follow
actionText string Button action text
releaseDate Date Track release date
releaseTime string The release time (HH:MM 24-hour) of the song / album, default 00:00
timezone string The release date's full timezone name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List)
linkUrl string action button link (track/album/playlist) to save/follow
saveSuccessfulMessage string Message to show after successful save/follow
artistProfileUrl string Artist to follow after successful save/follow
addEmail Boolean Indicates to collect user emails.

The Action Page Summary Object

In some API endpoints, where we do not need all the Action Page object data, a summary object can be returned with a subset of the Action Page object information (useful listing ActionPages)

Action Page Summary Object Details

The below JSON is an example of a Action Page object:

{
    "id": "5ad4a2b11e0000f94a1cf85b",
    "createdAt": 1523884721506,
    "artist": "599450031b0000a208fcbc85",
    "status": "ACTIVE",
    "domain": "https://ffm.to",
    "shortId": "0b0rnrn",
    "title": "Lenny Kravitz - Fly Away",
    "image": "https://is1-ssl.mzstatic.com/image/thumb/Music6/v4/b2/e2/1b/b2e21bd2-e67e-ce9d-20dc-3f5faa5b8cb2/source/500x0w.jpg"
}
Attribute Type Description
id string The Action Page id
createdAt date Timestamp of the Action Page creation
artist string The artist id associated with the Action Page object
status string The status of the Action Page. Valid options are: "ACTIVE", "ARCHIVED"
domain string domain to be used for this Action Page
shortId string Action Page short code
title string Action Page page title
image string Action Page image url

Get Action Page

Retrieves the details of an existing Action Page. You need only supply the unique Action Page identifier that was returned upon Action Page creation.

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/actionpage/{id}

GET Parameters

Parameter Required Description
id true The id of the Action Page to retrieve

Get Action Page By ShortId and Domain

Retrieves the details of an existing Action Page by short id and domain. The domain parameter should not include the HTTP protocol.

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/actionpage/shortid/{shortId}?domain={domainName}

GET Parameters

Parameter Required Description
shortid true The short id of the Action Page to retrieve
domainName true The domain of the Action Page (e.g.: ffm.to)

Returns

Returns a Action Page object if a valid identifier/s were provided.

Create Action Page

Creates a new Action Page ActionPage object.

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/actionpage

{
    "artistId": "599450031b0000a208fcbc85",
    "shortId": "qby54qo",
    "domain": "https://ffm.to",
    "title": "Like I Do",
    "image": "https://i.scdn.co/image/2e55b9c247cc6b0b713fbbce9db0527a932f8748",
    "previewUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
    "description": "Choose your preferred music service",
    "localization": [{
        "locale": "US",
        "title": "Like I Do",
        "image": "https://i.scdn.co/image/2e55b9c247cc6b0b713fbbce9db0527a932f8748",
        "previewUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
        "description": "Choose your preferred music service",
        "actionButtons": [{
            "platformCode": "spotify",
            "actionCode": "pre_save",
            "actionText": "Pre-Save on Spotify",
            "releaseDate": "2020-05-21",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Your music library will update automatically on release day!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        }]
    }],
    "actionButtons": [
        {
            "platformCode": "spotify",
            "actionCode": "pre_save",
            "actionText": "Pre-Save on Spotify",
            "releaseDate": "2020-05-21",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Your music library will update automatically on release day!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        },
        {
            "platformCode": "spotify",
            "actionCode": "save",
            "actionText": "Save on Spotify",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Thanks for saving! Your music library has been updated",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        },
        {
            "platformCode": "spotify",
            "actionCode": "follow",
            "actionText": "Follow on Spotify",
            "linkUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "saveSuccessfulMessage": "Thanks for following!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        }
    ],
    "targeting": {
        "tags": [
            "bosanova"
        ],
        "artists": [
            "David Guetta"
        ]
    },
    "legal": {
        "privacyPolicyUrl": "https://www.sonymusic.com/privacy-policy/",
        "termsOfServiceUrl": "https://www.sonymusic.com/terms-and-conditions/"
    },
    "pixels": {
        "google": "2394872331",
        "googleTagManager": "GTM-1234",
        "facebook": "2342342331"
    },
    "affiliates": {
        "apple": "q234ru22",
        "amazon": [{
                "tag": "big",
                "countryCode": "us"
            },{
                "tag": "small",
                "countryCode": "il"
            }
        ]
    },
    "analytics": {
        "google": "UA-238572-353"
    },
    "songName": "Name",
    "albumName": "Name"
}

POST Parameters

Attribute Type Description
id string The Action Page id (Required)
artistId string The artist id associated with the Action Page object (Required)
transactionId uuid provide a valid GUID identifying this specific transaction. If connection lost you can use the same body with the transactionId and retrieve the original response (Optioanl)
shortId string Action Page short code (Required)
domain string The domain specified for this Action Page (Required)
title string Action Page title (Requited)
image string Action Page image url (Required)
previewUrl string Action Page preview link. Supported URLs: Spotify, Apple, Amazon, Deezer, YouTube, SoundCloud, .MP3 (Optional)
description string Action Page description (Optional)
localization array <object> List of customized locale display options (Optional)
actionButtons string <object>
songName string The song name associated with the Action Page (Optioanl)
albumName string The album name associated with the Action Page (Optioanl)
pixels object Re-targeting pixels object for ad re-targeting (Optioanl)
affiliates object Affiliates object representing your affiliate programs that are connected to your Action Page (such as Apple or Amazon) (Optioanl)
analytics object Analytics object representing your analytics programs that are connected to your Action Page (such as Google analytics) (Optional)
legal object Legal object, defines the Action Page privacy policy and terms of service URLs (Optional)
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs (Optional)
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Returns

If success, Returns the ActionPage object, otherwise, returns error code.

Update ActionPage

curl -v -X PUT -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' -d '{body}' APIDOMAIN/manage/v1/actionpage/{id}

{
    "id": "5b02c896260000b596db4837",
    "shortId": "qby54qo",
    "domain": "https://ffm.to",
    "title": "Like I Do",
    "image": "https://i.scdn.co/image/2e55b9c247cc6b0b713fbbce9db0527a932f8748",
    "previewUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
    "description": "Choose your preferred music service",
    "localization": [],
    "actionButtons": [
        {
            "id": "9de244ec-5d62-48b9-9c09-e863ae882b13",
            "platformCode": "spotify",
            "actionCode": "pre_save",
            "actionText": "Pre-Save on Spotify",
            "releaseDate": "2020-05-21",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Your music library will update automatically on release day!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        },
        {
            "id": "ddd4bcf9-de70-496b-9114-61d431125678",
            "platformCode": "spotify",
            "actionCode": "save",
            "actionText": "Save on Spotify",
            "linkUrl": "https://open.spotify.com/track/6RnkFd8Fqqgk1Uni8RgqCQ",
            "saveSuccessfulMessage": "Thanks for saving! Your music library has been updated",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        },
        {
            "id": "f61a0610-9f5d-4d70-b20d-1bec31447b7a",
            "platformCode": "spotify",
            "actionCode": "follow",
            "actionText": "Follow on Spotify",
            "linkUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "saveSuccessfulMessage": "Thanks for following!",
            "artistProfileUrl": "https://open.spotify.com/artist/1Cs0zKBU1kc0i8ypK3B9ai",
            "addEmail": true
        }
    ],
    "targeting": {
        "tags": [
            "bosanova"
        ],
        "artists": [
            "David Guetta"
        ]
    },
    "legal": {
        "privacyPolicyUrl": "https://www.sonymusic.com/privacy-policy/",
        "termsOfServiceUrl": "https://www.sonymusic.com/terms-and-conditions/"
    },
    "pixels": {
        "google": "2394872331",
        "googleTagManager": "GTM-1234",
        "facebook": "2342342331"
    },
    "affiliates": {
        "apple": "q234ru22",
        "amazon": [{
                "tag": "big",
                "countryCode": "us"
            },{
                "tag": "small",
                "countryCode": "il"
            }
        ]
    },
    "analytics": {
        "google": "UA-238572-353"
    },
    "songName": "Name",
    "albumName": "Name"
}

PUT Parameters

Attribute Type Description
id string The Action Page id (Required)
shortId string Action Page short code (Required)
domain string The domain specified for this Action Page (Required)
title string Action Page title (Requited)
image string Action Page image url (Required)
previewUrl string Action Page preview link. Supported URLs: Spotify, Apple, Amazon, Deezer, YouTube, SoundCloud, .MP3 (Optional)
description string Action Page description (Optional)
localization array <object> List of customized locale display options (Optional)
actionButtons string <object>
songName string The song name associated with the Action Page (Optioanl)
albumName string The album name associated with the Action Page (Optioanl)
pixels object Re-targeting pixels object for ad re-targeting (Optioanl)
affiliates object Affiliates object representing your affiliate programs that are connected to your Action Page (such as Apple or Amazon) (Optioanl)
analytics object Analytics object representing your analytics programs that are connected to your Action Page (such as Google analytics) (Optional)
legal object Legal object, defines the Action Page privacy policy and terms of service URLs (Optional)
targeting object Targeting object, tags and artists that will be sent to your re-targeting programs (Optional)
socialIcons object Social links info
socialEmbeds object Social Embeds info for social sharing

Returns

If success, Returns the ActionPage object, otherwise, returns error code.

Archive Action Page

curl -v -X DELETE -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/actionpage/{id}

Parameters

Parameter Required Description
id true The id of the Action Page to archive

Returns

If success, Returns an empty JSON, otherwise, returns error code.

Restore Action Page

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/actionpage/{id}/restore
Parameter Required Description
id true The id of the ActionPage to restore

Returns

If success, Returns the ActionPage object, otherwise, returns error code.

List ActionPages

Returns a list of ActionPages associated to a specific artist

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/artist/{artist}/actionpages?page=1&search=faded&limit=1

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
search string Search term (Optional). If not specified, all actionpages are included.
page number Page number (Optional, Default 1)
limit number Number of result per page (Optional, Default 10. Max 100)

The above command returns JSON structured like this:

[
    {
        "id": "5adf52c71b0000e303332e17",
        "title": "Faded Love",
        "domain": "https://ffm.to",
        "shortId": "nk2bx8y",
        "artist": "599450031b0000a208fcbc85",
        "artistName": "My Artist",
        "createdAt": 1524585159263,
        "image": "https://i.scdn.co/image/9e48265689d8896cb562fc49bcdd506bb2e1f018",
    }
]

Returns

Attribute Required Description
data array array of ActionPage summary object

Search ActionPage (New)

Returns a list of actionpages associated to a specific api_key for a given search term

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/actionpage?search=faded&page=1&limit=1

GET Parameters

Parameter Required Description
api_key string In order to work with our API you must create an application in our music service’s dashboard. Every app has a unique API key that must be sent with all calls to the API.
search string Search term (Optional). If not specified, all actionpages are included.
page number Page number (Optional, Default 1)
limit number Number of result per page (Optional, Default 10. Max 100)

Returns

The above command returns JSON structured like this:

[
    {
        "id": "5adf52c71b0000e303332e17",
        "title": "Faded Love",
        "domain": "https://ffm.to",
        "shortId": "nk2bx8y",
        "artist": "599450031b0000a208fcbc85",
        "artistName": "My Artist",
        "createdAt": 1524585159263,
        "image": "https://i.scdn.co/image/9e48265689d8896cb562fc49bcdd506bb2e1f018",
    }
]
Attribute Required Description
data array array of Actionpage summary object

Query Analytics & Audience

Returns Action Page Analytics

curl -v -X GET -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' "APIDOMAIN/manage/v1/actionpage/{actionpage}/analytics?start=2018-04-21&end=2018-04-29&timeZoneOffset=180"

The above command returns JSON structured like this:

{
    "totals": {
        "clicks": 17,
        "uniqueUsers": 4,
        "clicksToService": 3
    },
    "timeline": [{
        "date": "2018-03-18",
        "clicks": 16,
        "clicksToService": 3
    },{
        "date": "2018-03-19",
        "clicks": 1,
        "clicksToService": 0
    }],
    "channels": [{
        "name": "Original",
        "clicks": 17,
        "clicksToService": 3
    }],
    "channelTypes": [{
        "name": "Organic",
        "clicks": 17,
        "clicksToService": 3
    }],
    "referrals": [{
        "name": "direct",
        "clicks": 17,
        "clicksToService": 3
    }],
    "actions": [{
        "name": "follow",
        "clicksToService": 2
    },{
        "name": "stream",
        "clicksToService": 1
    }],
    "locations": [{
        "code": "US",
        "clicks": 17,
        "clicksToService": 3
    }],
    "audience": [{
        "service": "spotify",
        "service_user_id": "zohar.aharoni",
        "userData": {
            "displayName": "zohar.aharoni",
            "webUrl": "https://open.spotify.com/user/zohar.aharoni",
            "email": "zohar.aharoni@gmail.com",
            "image": "https://profile-images.scdn.co/images/userprofile/default/0319a3cde14b70dc6bc0c953636eff77326d3e02",
            "profileFollowers": 3,
            "country": "US",
            "birthdate": "1980-10-01",
            "playlistsFollowers": null,
            "subscriptionType": "free"
        }
    }]
}

Returns

Attribute Required Description
totals object Total analytics summary
timeline object Total analytics grouped by timeline
channels object Total analytics grouped by channels
channelTypes object Total analytics grouped by channel types (Organic/Paid)
referrals object Total analytics grouped by referrals source
actions object Total analytics grouped by actions
locations object Total analytics grouped by locations
audience object Shows data for users who Pre-Saved/Saved/Followed the link and agreed to share their contact.

General

Validate Available Id

Test if the given ID is available for use with a smartlink or an action page 

curl -v -X Get -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/system/shortid-available/{id}?domain={domain}

The above command returns JSON structured like this:

{
    "available": true
}
Parameter Required Description
id string ID to test
domain string Domain to test against

Returns

If success, returns available is true, otherwise, returns available is false.

Upload Artwork

Upload an image directly to Feature.fm, get a public link and use it for your links artworks. Image size can be up to 10MB. Image can be uploaded from URL or base64. Sending both values or none will respond with 404 error.

Prior to upload the image goes through format and size verification

curl -v -X POST -H "Content-Type: application/json" -H 'x-api-key: 5ae5e3ce150000ea23650f95' APIDOMAIN/manage/v1/system/upload-image{?url="http://"}

{
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

The above command returns JSON structured like this:

{
    "imageUrl": "https://advertiser-api-uploads.s3.us-west-2.amazonaws.com/test/img-a4215c20-e1b5-11e8-bc3d-e786aa8d82de.jpg"
}
Parameter Required Description
url string url to the image to upload (Optional if base64 is given)
base64 string base64 encoded data of the image (Optional if url is given)

Returns

If success, returns the image public url, otherwise, returns error.

Conversion API

A conversion is an action that a person takes on your website/app such as checking out, registering, downloading, or viewing a particular page.

Feature.fm allows you to report these actions, so we can store it internally and report back to the campaign's marketer.

Feature.fm conversion SDK/API will report data back if and only if the user has been referred by a SmartLink campaign.

When a fan is redirected to your page from a SmartLink campaign, a token is passed along as a URL parameter (ffm=). This token should be used to report back the conversion data. If you choose to use our web SDK (recommended), the token is automatically stored as a session cookie to be used when the user completes a transaction. This cookie expires when the session expires and lives up to three days.

When the fan completes an action, API/SDK track function/endpoint must be invoked with some data about the product (more below). If the transaction contains more than one product, the function can be called multiple times

To start using conversion data, the implementation should follow these two steps

If one or both of these criteria are not met, the conversion script will not work.

In order to start using the conversion SDK/API, please contact us so we will enable it for you. Usually done in 24 hours.

Initialize session

SDK

Add the SDK script (see below) to the following pages

<script type="text/javascript" src="https://assets.ffm.to/js/ffmTrack.js"></script>

Its recommented to add the script right before your closing body tag.

API

If you choose to use direct calls to our API, it is in your responsibilty to parse the unique_id token from the page query string and store it on the user session/workflow.

Execute transaction

SDK

When the user completes a transaction (sale/download/listen/etc...), reporting back to Feature.fm is done by calling window._ffmTrack which receives the following parameters:

ffmTrack function sends automatically the token which was stored when the fan was redirected to the service

<script type="text/javascript">
window._ffmTrack('B01BDKNLZG', 'track', 'Rihanna - Anti (Standard Edition)', 'sale', 12.99, 'GBP');
</script>

API

If you choose to use direct calls to our API, when the user completes a transaction (sale/download/listen/etc...), reporting back to feature.fm is done by calling "POST" to https//api.ffm.to/conversion/operation

curl -X "POST" https://api.ffm.to/conversion/operation
{  
  reference: 'B01BDKNLZG',
  type: 'track',
  name: 'Rihanna - Anti (Standard Edition)',
  operation: 'sale',
  value: 12.99,
  currency: 'GBP',
  ffmHash: ....
}

ffmHash is mandatory and must be filled with the user Feature.fm token

Periodic Report

If you would like to upload a daily/hourly aggregated conversion data in CSV/JSON rather than using the API for every transaction, we do support it as well!

For further information please do not hesitate to contact us.

Errors

The Feature.fm API uses the following error codes:

Error Code Meaning
400 Bad Request -- Something is wrong with your request
401 Unauthorized -- Your API key is wrong
403 Forbidden -- The object requested is hidden for administrators only
404 Not Found -- The specified object could not be found
405 Method Not Allowed -- You tried to access a object with an invalid method
406 Not Acceptable -- You requested a format that isn't json
410 Gone -- The object requested has been removed from our servers
429 Too Many Requests -- You're requesting too many objects! Slown down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.
code sample