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

Authentication

All requests to the Marketing API require a valid x-api-key header to be included in the request. This header is used to authenticate your requests and ensure secure access to the API. Requests without a valid API key will be rejected.

To get your API access, click here.

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",
            "hideFFMBranding": true,
            "footer": "85 Broad Street Suite 17.089 New York, NY 10004",
            "sender": "noreply@myartist.com"
        },
        "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

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)
hideFFMBranding boolean Indicate to hide "Powered By Feature.fm" by default in the email notification
footer string A text that will be displayed in the email notification footer. For example: can be Physical Address. (maximum 264 characters)
sender string The email address that will be shown as the sender in Fan Pre-Save Email Notifications. Must be the one set for the account or the default feature.fm sender. If not set, will use the default feature.fm sender

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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/artists'

GET Parameters

Parameter Required Description
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

The Artist's List Object

Attribute Type Description
id string The unique identifier of the artist
name string The artist name

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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/artists/search?term=artist&page=1&limit=1'

GET Parameters

Parameter Required Description
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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/artist/:artistId'

Path Parameters

Parameter Required Description
artistId 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: {YOUR_API_KEY}' -d '
{
    "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",
            "hideFFMBranding": true,
            "footer": "85 Broad Street Suite 17.089 New York, NY 10004",
            "sender": "noreply@myartist.com"
        },
        "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/"
        }
    }
}' 'APIDOMAIN/manage/v1/artist'

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: {YOUR_API_KEY}' -d '
{
    "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/"
        }
    }
}' 'APIDOMAIN/manage/v1/artist/:artistId'

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', 'action_page', 'modern_layout'
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: blur, 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 supported
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
hideFFMBranding boolean Indicate to hide "Powered By Feature.fm" by default in the email notification
footer string A text that will be displayed in the email notification footer. For example: can be Physical Address. (maximum 264 characters)
sender string The email address that will be shown as the sender in Fan Pre-Save Email Notifications. Must be the one set for the account or the default feature.fm sender. If not set, will use the default feature.fm sender

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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/smartlink/:smartlinkId'

Path Parameters

Parameter Required Description
smartlinkId 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/smartlink/shortid/:shortId?domain={domain}'

Path Parameters

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

GET Parameters

Parameter Required Description
domain 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: {YOUR_API_KEY}' -d '
{
    "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"
        ]
    }
}' 'APIDOMAIN/manage/v1/smartlink'

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: {YOUR_API_KEY}' -d '
{
    "artistId": "5dd4a2b11e0000f94a1cf85c",
    "shortId": "greatest_hits",
    "domain": "https://ffm.to",
    "scanLink": "https://www.youtube.com/watch?v=aNFvM5XqF8g",
}' 'APIDOMAIN/manage/v1/smartlink'

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', 'action_page' or 'modern_layout' (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: {YOUR_API_KEY}' -d '
{
    "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"
}' 'APIDOMAIN/manage/v1/smartlink/future-release'

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', 'action_page' or 'modern_layout' (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: {YOUR_API_KEY}' -d '
{
    "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",
        "hideFFMBranding": true,
        "footer": "85 Broad Street Suite 17.089 New York, NY 10004",
        "sender": "noreply@gunsandroses.com"
    },
    "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
}' 'APIDOMAIN/manage/v1/smartlink/pre-save'

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', 'action_page' or 'modern_layout' (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
saveSuccessfulMessage string Message to show after successful pre-save

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: {YOUR_API_KEY}' -d '
    {
        "scanLink": "ISRC:USSM10505527"
    }' 'APIDOMAIN/manage/v1/smartlink/:smartlinkId/rescan'

Path Parameters

Parameter Required Description
smartlinkId true The id of the smartlink to rescan

Body Parameters

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: {YOUR_API_KEY}' -d '
{
    "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"
        ]
    }
}' 'APIDOMAIN/manage/v1/smartlink/:smartlinkId'

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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/smartlink/:smartlinkId'

Path Parameters

Parameter Required Description
smartlinkId 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/smartlink/:smartlinkId/restore'

Path Parameters

Parameter Required Description
smartlinkId 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/artist/:artistId/smartlinks?search=faded&page=1&limit=1&pagingInfo=true'

Path Parameters

Parameter Required Description
artistId true The id of the artist to search

Query Parameters

Parameter Required Description
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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/smartlink?search=faded&page=1&limit=1&pagingInfo=true'

GET Parameters

Parameter Required Description

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

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

Returns SmartLink Analytics

Path Parameters

Parameter Required Description
smartlinkId true The id of the smartlink

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.

The Shortlink Management API allows you to create, retrieve, update, delete, restore, and fetch analytics for shortlinks. Shortlinks provide a simplified way to create branded short URLs that redirect to your content.

The below JSON is an example of a Shortlink object:

{
    "id": "5cb5f69b160000f812eaf4a3",
    "artistId": "5cb5f69b160000f812eaf4a3",
    "title": "My New Single",
    "link": "https://open.spotify.com/track/your-track-id",
    "domain": "ffm.link",
    "shortId": "mynewsingle",
    "image": "https://i.scdn.co/image/your-image-id",
    "createdAt": 1526373512,
    "status": "ACTIVE",
    "localization": [
        {
            "locale": "us",
            "link": "https://open.spotify.com/track/us-track-id"
        },
        {
            "locale": "gb",
            "link": "https://open.spotify.com/track/uk-track-id"
        }
    ],
    "targeting": {
        "tags": ["pop", "summer"],
        "artists": ["Artist Name"]
    },
    "pixels": {
        "google": "G-XXXXXXXX",
        "facebook": "1234567890",
        "tiktok": "ABCDEF1234567890ABCD"
    },
    "affiliates": {
        "amazon": [
            {
                "tag": "myaffiliate-20",
                "countryCode": "us"
            }
        ],
        "apple": "1234567",
        "spotify": "partner123"
    },
    "analytics": {
        "google": "UA-XXXXXXXX-X"
    },
    "legal": {
        "privacyPolicyUrl": "https://example.com/privacy",
        "termsOfServiceUrl": "https://example.com/terms"
    },
    "socialEmbeds": {
        "enabled": true,
        "title": "Check out my new single!",
        "description": "Now available on all platforms",
        "preReleaseDescription": "Coming soon!",
        "image": "https://example.com/social-image.jpg"
    },
    "sharedAnalytics": {
        "enabled": true
    }
}
Field Type Required Description
link string Yes The primary destination URL for the shortlink. Must be a valid URL with http or https protocol.
artistId string Yes The ID of the artist this shortlink belongs to.
title string Yes A title for the shortlink, used for internal identification and in some social media embeds.
domain string Optional The domain to use for the shortlink (e.g., ffm.link). Must be a valid URI. If not provided, a default domain will be used.
shortId string Optional A custom short identifier (e.g., ffm.link/:shortId). Can contain letters, numbers, hyphens, and underscores. Max 50 characters.
image string Optional A URL for an image to be used in social media embeds. Must be a valid http or https URL.
transactionId string Optional 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.
localization array Optional An array of objects for localizing the link based on the user's country. See Localization Object.
targeting object Optional An object for audience targeting. See Targeting Object.
pixels object Optional An object for adding retargeting pixels. See Retargeting Pixels Object.
affiliates object Optional An object for configuring affiliate programs. See Affiliates Object.
analytics object Optional An object for configuring third-party analytics. See Analytics Object.
legal object Optional An object for providing links to legal documents. See Legal Object.
socialEmbeds object Optional An object for customizing how the link appears on social media. See Social Embeds Object.
sharedAnalytics object Optional An object to configure a publicly shareable analytics report. See Shared Analytics Object.

Localization Object

Used within the localization array to provide different destination links for different countries.

Field Type Required Description
locale string Yes The two-letter ISO country code (e.g., "us", "gb", "jp").
link string Yes The destination URL for this specific locale. Must be a valid http/https URL.

Targeting Object

Used to target specific audiences.

Field Type Required Description
tags array Optional An array of strings.
artists array Optional An array of artist names.

Retargeting Pixels Object

Used to add tracking pixels from various ad platforms.

Field Type Description
google string Your Google Ads pixel ID.
facebook string Your Facebook Pixel ID.
googleTagManager string Your Google Tag Manager container ID.
tiktok string Your TikTok Pixel ID (must be 20 alphanumeric characters).
snapchat string Your Snapchat Pixel ID.
appnexus string Your AppNexus pixel ID.

Affiliates Object

Used to configure affiliate marketing programs.

Field Type Required Description
amazon array Optional An array of Amazon affiliate objects with tag (string) and countryCode (2-letter country code).
apple string Optional Your Apple affiliate token.
spotify string Optional Your Spotify affiliate token.

Analytics Object

Used for integrating with third-party analytics services.

Field Type Required Description
google string Optional Your Google Analytics Tracking ID (e.g., "UA-XXXXXXXX-X").

Used to link to your terms of service and privacy policy.

Field Type Required Description
privacyPolicyUrl string Optional A URL to your privacy policy. Must be a valid http/https URL.
termsOfServiceUrl string Optional A URL to your terms of service. Must be a valid http/https URL.

Social Embeds Object

Used to customize the link's appearance on social media platforms.

Field Type Required Description
enabled boolean Optional Defaults to true. Set to false to disable custom social embeds.
title string Optional A custom title for the social media embed.
description string Optional A custom description. Max 48 characters.
preReleaseDescription string Optional A description to show before the release date. Max 48 characters.
image string Optional A URL for a custom image. Must be a valid http/https URL.

Shared Analytics Object

Used to enable a public-facing analytics report for this link.

Field Type Required Description
enabled boolean Optional Defaults to false. Set to true to enable the report.

Creates a new shortlink.

HTTP Request

POST APIDOMAIN/manage/v1/shortlink

curl -X POST \
  'APIDOMAIN/manage/v1/shortlink' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -d '{
    "artistId": "5cb5f69b160000f812eaf4a3",
    "title": "My New Single",
    "link": "https://open.spotify.com/track/your-track-id",
    "image": "https://i.scdn.co/image/your-image-id",
    "domain": "ffm.link"
  }'

The above command returns JSON structured like this:

{
    "status": 0,
    "data": {
        "id": "5cb5f69b160000f812eaf4a3",
        "artistId": "5cb5f69b160000f812eaf4a3",
        "title": "My New Single",
        "link": "https://open.spotify.com/track/your-track-id",
        "domain": "ffm.link",
        "shortId": "mynewsingle",
        "image": "https://i.scdn.co/image/your-image-id",
        "createdAt": 1526373512,
        "status": "ACTIVE"
    }
}

POST Parameters

See The Shortlink Object for all available fields.

Returns

If success, returns the created shortlink object, otherwise, returns error code.

Retrieves a list of all shortlinks for all artists associated with your key.

HTTP Request

GET APIDOMAIN/manage/v1/shortlink

curl -X GET \
  'APIDOMAIN/manage/v1/shortlink?limit=10&page=1' \
  -H 'x-api-key: {YOUR_API_KEY}'

The above command returns JSON structured like this:

{
    "status": 0,
    "data": [
        {
            "id": "5cb5f69b160000f812eaf4a3",
            "artistId": "5cb5f69b160000f812eaf4a3",
            "title": "My New Single",
            "link": "https://open.spotify.com/track/your-track-id",
            "domain": "ffm.link",
            "shortId": "mynewsingle",
            "status": "ACTIVE"
        }
    ],
    "paging": {
        "page": 1,
        "limit": 10,
        "total": 100
    }
}

Query Parameters

Parameter Required Description
limit Optional Number of results per page (Default 10, Max 100)
page Optional Page number (Default 1)

Returns

Returns a list of shortlink objects.

Retrieves a shortlink by its short ID and domain.

HTTP Request

GET APIDOMAIN/manage/v1/shortlink/shortid/:shortId?domain={domain}

curl -X GET \
  'APIDOMAIN/manage/v1/shortlink/shortid/aBc12D?domain=ffm.link' \
  -H 'x-api-key: {YOUR_API_KEY}'

Path Parameters

Parameter Required Description
shortId Yes The short ID of the shortlink to retrieve

GET Parameters

Parameter Required Description
domain Yes The domain of the shortlink (e.g., ffm.link)

Returns

If found, returns the shortlink object, otherwise, returns error code.

Retrieves a shortlink by its unique ID.

HTTP Request

GET APIDOMAIN/manage/v1/shortlink/:shortlinkId

curl -X GET \
  'APIDOMAIN/manage/v1/shortlink/:shortlinkId' \
  -H 'x-api-key: {YOUR_API_KEY}'

GET Parameters

Parameter Required Description
shortlinkId Yes The ID of the shortlink to retrieve

Returns

If found, returns the shortlink object, otherwise, returns error code.

Updates an existing shortlink.

HTTP Request

PUT APIDOMAIN/manage/v1/shortlink/:shortlinkId

curl -X PUT \
  'APIDOMAIN/manage/v1/shortlink/:shortlinkId' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -d '{
    "title": "My Awesome New Single",
    "link": "https://music.apple.com/us/album/your-album/your-id"
  }'

PUT Parameters

See The Shortlink Object for all available fields. Only include fields you want to update.

Returns

If success, returns the updated shortlink object, otherwise, returns error code.

Archives (soft-deletes) a shortlink.

HTTP Request

DELETE APIDOMAIN/manage/v1/shortlink/:shortlinkId

curl -X DELETE \
  'APIDOMAIN/manage/v1/shortlink/:shortlinkId' \
  -H 'x-api-key: {YOUR_API_KEY}'

Returns

Returns a success status if the shortlink was archived successfully.

Restores an archived shortlink.

HTTP Request

POST APIDOMAIN/manage/v1/shortlink/:shortlinkId/restore

curl -X POST \
  'APIDOMAIN/manage/v1/shortlink/:shortlinkId/restore' \
  -H 'x-api-key: {YOUR_API_KEY}'

Returns

Returns the restored shortlink object if successful.

Retrieves analytics for a specific shortlink.

HTTP Request

GET APIDOMAIN/manage/v1/shortlink/:shortlinkId/analytics

curl -X GET \
  'APIDOMAIN/manage/v1/shortlink/:shortlinkId/analytics?start=2024-01-01&end=2024-01-31' \
  -H 'x-api-key: {YOUR_API_KEY}'

The above command returns JSON structured like this:

{
    "status": 0,
    "data": {
        "totals": {
            "clicks": 1500,
            "uniqueClicks": 1200
        },
        "timeline": {
            "2024-01-01": {
                "clicks": 50,
                "uniqueClicks": 45
            }
        },
        "locations": {
            "US": {
                "clicks": 800,
                "uniqueClicks": 700
            },
            "GB": {
                "clicks": 300,
                "uniqueClicks": 250
            }
        },
        "referrals": {
            "twitter.com": {
                "clicks": 500,
                "uniqueClicks": 400
            }
        }
    }
}

Path Parameters

Parameter Required Description
shortlinkId true The id of the shortlink

GET Parameters

Parameter Required Description
start Optional Start date for analytics (YYYY-MM-DD format)
end Optional End date for analytics (YYYY-MM-DD format)

Returns

Returns analytics data including totals, timeline breakdown, locations, and referral sources.

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 array <object> List of Action Page buttons
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 array <object> Locale specific buttons display settings

ActionPage Object Details

Attribute Type Description
id string Button ID
platformCode string Button platform code (currently only Spotify supported)
actionCode string Button action code. Supported: 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/actionpage/:actionpageId'

Path Parameters

Parameter Required Description
actionpageId 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/actionpage/shortid/:shortId?domain={domain}'

Path Parameters

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

GET Parameters

Parameter Required Description
domain 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: {YOUR_API_KEY}' -d '
{
    "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"
}' 'APIDOMAIN/manage/v1/actionpage'

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 array <object> List of Action Page buttons (Required)
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: {YOUR_API_KEY}' -d '
{
    "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"
}' 'APIDOMAIN/manage/v1/actionpage/:actionpageId'

Path Parameters

Parameter Required Description
actionpageId true The id of the Action Page

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 array <object> List of Action Page buttons (Required)
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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/actionpage/:actionpageId'

Path Parameters

Parameter Required Description
actionpageId 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/actionpage/:actionpageId/restore'

Path Parameters

Parameter Required Description
actionpageId 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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/artist/:artistId/actionpages?page=1&search=faded&limit=1'

Path Parameters

Parameter Required Description
artistId true The id of the artist folder to search in

GET Parameters

Parameter Required Description
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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/actionpage?search=faded&page=1&limit=1'

GET Parameters

Parameter Required Description
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: {YOUR_API_KEY}' "APIDOMAIN/manage/v1/actionpage/:actionpageId/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.

Artist Future Save Configuration

The Future Save feature allows fans to subscribe to receive all future pre-saves from an artist by opting-in just once. This means that fans who join the Future Save will be automatically set to receive the artist's next Pre-Save on Feature.fm. Fans can opt-in after successfully completing a Pre-Save, where they will be prompted to receive all future releases from the artist. This feature works only with the supported services mentioned below. The user needs to be subscribed to the Future Save feature. Once subscribed, they can enable/disable this feature per artist they create. Also, the user will need to provide information for each music service, including the service name, the link to the artist page in that service, and if the feature is enabled for that specific service for that artist.

Supported Services

Set Future-Save Settings For Artist

curl --location --request PUT 'APIDOMAIN/manage/v1/artist/:artistId/future' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "enabled": true,
    "services": [
        {
            "service": "spotify",
            "link": "https://open.spotify.com/artist/1lhaaKpTyXOnjp79M3xYBl"
        }
    ]
}'

The above command returns JSON structured like this:

{
    "id": "674dc4141d00005800c4d659",
    "artistId": "6681425f1c00001234604031",
    "artist": {
        "id": "6681425f1c00001234604031",
        "alias": "lennykravitz",
        "name": "Lenny Kravitz",
        "accountId": "564b038e4321006330ee3676"
    },
    "shortId": "vp7qymr",
    "type": "future_save",
    "createdAt": 1733149716813,
    "enabled": true,
    "services": [
        {
            "id": "e3kohxpw0",
            "service": "spotify",
            "link": "https://open.spotify.com/track/0XcR8kUxhai3H7wqB0R2eE",
            "toggle": true
        }
    ]
}

Path Parameters

Parameter Required Description
artistId true The id of the artist

PUT Parameters

Attribute Type Required Description
enabled boolean true A boolean value that determines whether Future-Save is enabled for the artist
services array <object> true An array of objects, where each object represents a artist profile url in a service

Returns

If success, returns the Future-Save Settings for the artist, otherwise - returns error code.

Disable Future-Save Settings For Artist

curl --location --request DELETE 'APIDOMAIN/manage/v1/artist/:artistId/future' \
--header 'x-api-key: {YOUR_API_KEY}'

Path Parameters

Parameter Required Description
artistId true The id of the artist

Returns

Will return the future-save settings with "enabled" field set to false

Restore Future-Save Settings For Artist

curl --location --request POST 'APIDOMAIN/manage/v1/artist/:artistId/future/enable' \
--header 'x-api-key: {YOUR_API_KEY}'

Path Parameters

Parameter Required Description
artistId true The id of the artist

Returns

Will return the future-save settings with "enabled" field set to true

Get Future-Save Settings For Artist

curl --location --request GET 'APIDOMAIN/manage/v1/artist/:artistId/future' \
--header 'x-api-key: {YOUR_API_KEY}'

Path Parameters

Parameter Required Description
artistId true The id of the artist

Returns

Will return the future-save settings for the artist

The Future-Save Service Object

Attribute Type Required Description
service string true The name of the music service (e.g., "spotify")
link string true The URL to the artist's page on the respective music service

Best Practice for Adding Services to Artist Future-Save Settings via API

When adding new services to Future-Save settings, you have two options:

Option 1: Complete Update - Call the update API endpoint with the complete list of services, including both previously configured services and your new additions - This approach requires knowledge of all existing service configurations

Option 2: Fetch-Then-Update - If you don't have access to previously configured service URLs, first call GET to retrieve current settings - Add your new service information to the existing services list in the response - Use the combined data as the request body for your update call - Note: The GET response contains extended information fields that are ignored during update operations, so you can safely include them in your update request

Channels

channels refer to the different avenues or platforms where artists can share their Feature.fm smart links to track and understand where their audience is coming from. These channels can be either organic (e.g., social media posts, email newsletters) or paid (e.g., advertising campaigns).

Custom channels extend this functionality by allowing you to create personalized tracking parameters beyond the pre-set options.

List Channels

GET /v1/channel

Returns a list of all channels for the authenticated user.

Request

Response

Example cURL

curl -X GET "APIDOMAIN/manage/v1/channel" \
  -H "x-api-key: {YOUR_API_KEY}"

Create Custom Channel

POST /v1/channel

Creates a new custom channel.

Request Body

{
  "name": "My Channel",
  "isOrganic": true
}
Field Type Required Description
name string Yes Name of the channel
isOrganic boolean No Whether the channel is organic (default: true)

Response

Example cURL

curl -X POST "APIDOMAIN/manage/v1/channel" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Channel",
    "isOrganic": true
  }'

Delete Custom Channel

DELETE /v1/channel/:channelId

Deletes a custom channel by its ID.

Path Parameters

Parameter Type Description
channelId string The ID of the channel to delete

Response

Example cURL

curl -X DELETE "APIDOMAIN/manage/v1/channel/1234567890" \
  -H "x-api-key: {YOUR_API_KEY}"

Audience Segments

What are Segments?

A Segment is a saved audience filter—a set of rules that defines a group of fans based on their attributes or behaviors (e.g., country, platform, engagement, etc.). Segments allow you to target, analyze, or message specific subsets of your audience. Segments can be managed at the user level (for the whole account) or at the artist/folder level.

You can create, read, update, and delete segments, and then use them to query your audience or for other marketing actions.

Segment Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "US Spotify Fans",
  "filter": {
    "locations": { "condition": "includes", "value": ["us"] },
    "platforms": { "condition": "includes", "value": ["spotify"] }
  }
}
Attribute Type Description
id string Optional. Unique identifier for the segment. Can be a UUID v4 or a string containing only letters, numbers, underscores, or hyphens.
name string Required. Name of the segment. Max 40 characters.
filter object Required. Object defining the segment’s filter rules. See Filter Fields for details.

Filter Fields

{
  "locations": { "condition": "includes", "value": ["us", "gb"] },
  "platforms": { "condition": "includes", "value": ["spotify", "apple"] }
}

Each segment’s filter is an object where each key is a category (e.g., locations, platforms) and the value is an object with:

Category Condition(s) Value Type Description/Restrictions
platforms includes array of strings Must be valid platform IDs. At least one required. No duplicates.
subscriptions includes array of strings Allowed: "paid", "free", "na". At least one required.
smartlinks includes string Must be a valid smartlink id (24 hex chars).
email_marketing includes array of strings Only "subscribed" allowed. At least one required.
folders includes array of strings Must be a valid artist id (24 hex chars). Not allowed in artist segments.
locations includes array of strings Valid country codes (ISO 3166-1 alpha-2). At least one required.
last_seen between object { start: ISODate, end: ISODate }. Start must be <= end.
artist_tags includes array of strings At least one required.
engagements greater than number Must be a number.
followers greater than number Must be a number.
registration_types includes array of strings Allowed: "one-time", "forever". At least one required.

Filter Field Example

"filter": {
  "locations": { "condition": "includes", "value": ["us", "gb"] },
  "platforms": { "condition": "includes", "value": ["spotify", "apple"] },
  "last_seen": { "condition": "between", "value": { "start": "2023-01-01", "end": "2023-12-31" } }
}

Filter Conditions

Platforms

Subscriptions

Locations

Email Marketing

Folders (User Segments Only)

Last Seen

Artist Tags

Engagements

Followers

Registration Types

Validation Rules

  1. Segment name must not exceed 40 characters
  2. At least one filter condition is required
  3. Artist segments cannot include folder filters
  4. All dates must be in ISO format (YYYY-MM-DD)
  5. smartlink and artist/folder ids must be valid 24-character hexadecimal strings
  6. Country codes must be valid ISO-3166-1 alpha-2 and lowercase
  7. Platform values must be valid streaming platforms
  8. Subscription types must be valid: "paid", "free" or "na"
  9. Registration types must be either "one-time" or "forever"

Pre-defined Segments

The following audience segments are available out-of-the-box. Each segment is identified by an id, has a user-friendly name, and is defined by one or more filters.

Segment ID Name Filters Used
everyone Everyone None (includes all users)
spotify-fans Spotify Fans platforms: Spotify
youtube-subscribers YouTube Subscribers platforms: YouTube, YouTube Music
apple-fans Apple Music Fans platforms: Apple
influencers Influencers followers: 1000
recent-fans Recent Fans last_seen: Last 90 days
repeat-fans Repeat Fans engagements: users who have engaged more than once
top-fans Top Fans engagements: users who have engaged at least 5 times
slipping-away Slipping away last_seen: Not seen in the last 30 days
past-fans Past Fans last_seen: Not seen in the last 90 days
premium-streamers Premium Streamers subscriptions: Paid
engagements: engaged at least 3 times
forever-fans Future Save Fans registration_types: Forever

Example:

You can use these segment IDs when querying the API to quickly target common audience groups.

Create a User Segment

curl -X POST "APIDOMAIN/manage/v1/audience/segments" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Fans in US",
    "filter": {
        "platforms": {
            "condition": "includes",
            "value": ["spotify", "apple", "youtube"]
        },
        "subscriptions": {
            "condition": "includes",
            "value": ["paid", "free", "na"]
        },
        "locations": {
            "condition": "includes",
            "value": ["us", "gb", "jp"]
        },
        "smartlinks": {
            "condition": "includes",
            "value": "507f1f77bcf86cd799439011"
        },
        "email_marketing": {
            "condition": "includes",
            "value": ["subscribed"]
        },
        "folders": {
            "condition": "includes",
            "value": ["507f1f77bcf86cd799439011"]
        },
        "last_seen": {
            "condition": "between",
            "value": {
                "start": "2024-01-01",
                "end": "2024-12-31"
            }
        },
        "artist_tags": {
            "condition": "includes",
            "value": ["rock", "pop", "jazz"]
        },
        "engagements": {
            "condition": "greater than",
            "value": 1000
        },
        "followers": {
            "condition": "greater than",
            "value": 5000
        },
        "registration_types": {
            "condition": "includes",
            "value": ["one-time", "forever"]
        }
    }
  }'

POST /manage/v1/audience/segments

Creates a new audience segment for the user.

Input

Attribute Type Description
name string Name of the segment (required, max 40 characters)
filter object Filter object defining the segment (required). See Filter Fields below.

List User Segments

curl -X GET "APIDOMAIN/manage/v1/audience/segments" -H 'x-api-key: {YOUR_API_KEY}'

GET /manage/v1/audience/segments

Returns all segments for the current user.

Input

No input parameters.

Get a User Segment

curl -X GET "APIDOMAIN/manage/v1/audience/segments/SEGMENT_UUID" -H 'x-api-key: {YOUR_API_KEY}'

GET /manage/v1/audience/segments/:segmentId

Returns a specific segment by its ID.

Input

Attribute Type Description
segmentId string Segment UUID (required)

Update a User Segment

curl -X PUT "APIDOMAIN/manage/v1/audience/segments/SEGMENT_UUID" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Segment Name",
    "filter": {
      "platforms": { "condition": "includes", "value": ["spotify"] }
    }
  }'

PUT /manage/v1/audience/segments/:segmentId

Updates an existing segment.

Input

Attribute Type Description
segmentId string Segment UUID (required, in URL)
name string Name of the segment (required, max 40 characters)
filter object Filter object defining the segment (required). See Filter Fields below.

Delete a User Segment

curl -X DELETE "APIDOMAIN/manage/v1/audience/segments/SEGMENT_UUID" -H 'x-api-key: {YOUR_API_KEY}'

DELETE /manage/v1/audience/segments/:segmentId

Deletes a segment.

Input

Attribute Type Description
segmentId string Segment UUID (required)

Artist/Folder Segments

All the above operations are also available for artist/folder-level segments, using the following endpoints:

Example: Create Artist Segment

curl -X POST "APIDOMAIN/manage/v1/audience/artists/:artistId/segments" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Artist Fans",
    "filter": {
      "locations": { "condition": "includes", "value": ["us"] }
    }
  }'

Input

Path Parameters

Parameter Required Description
artistId string Artist ID (required, 24-char hex, in URL)

Body Parameters

Attribute Type Description
name string Name of the segment (required, max 40 characters)
filter object Filter object defining the segment (required). See Filter Fields below.

Advanced Audience Query

What is Audience Query?

Audience Query allows you to fetch a list of fans matching a segment. You can query by referencing a saved segment or by providing an inline filter (without saving it as a segment). Queries can be performed at the user level or for a specific artist/folder.

User Audience Query

POST /manage/v1/audience/query

Query your audience using either a saved segment or an inline filter.

cURL Example (using segmentId vs inline filter)

curl -X POST "APIDOMAIN/manage/v1/audience/query" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
        "segmentId": "SEGMENT_UUID"
    }'

curl -X POST "APIDOMAIN/manage/v1/audience/query" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "locations": { "condition": "includes", "value": ["us"] }
    }
  }'

Input

Query Parameters

Attribute Type Description
page number Page number (optional, default: 1)
pageSize number Page size (optional, default: 10)

Body Parameters

Attribute Type Description
segmentId string Segment UUID. Required if filter is not provided.
filter object Inline filter object. Required if segmentId is not provided. See Filter Fields.

Note: You must provide either segmentId or filter, not both.

Artist/Folder Audience Query

POST /manage/v1/audience/artists/:artistId/query

Query the audience for a specific artist/folder.

cURL Example

curl -X POST "APIDOMAIN/manage/v1/audience/artists/:artistId/query" \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "segmentId": "SEGMENT_UUID"
  }'

Input

Path Parameters

Attribute Type Description
artistId string Artist ID (required, 24-char hex, in URL)

Query Parameters

Attribute Type Description
page number Page number (optional, default: 1)
pageSize number Page size (optional, default: 10)

Body Parameters

Attribute Type Description
segmentId string Segment UUID. Required if filter is not provided.
filter object Inline filter object. Required if segmentId is not provided. See Filter Fields.

Note: You must provide either segmentId or filter, not both.

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: {YOUR_API_KEY}' 'APIDOMAIN/manage/v1/system/shortid-available/:shortId?domain={domain}'

Path Parameters

Parameter Required Description
shortId true The short id to check for availability

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: {YOUR_API_KEY}' '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