Introduction

 

Linkfire helps you create intelligent links that route fans to the music they love, in the apps they love. Best of all – we do it all automatic.

The linkfire API lets you:

  • Create Linkfire campaign links via music service URLs, UPC and -ISRC codes.
  • Generate campaign marketing assets.
  • Manage campaign link properties.
  • Automatically scan for products across music services and stores.

Want to sign up for a Linkfire Developer account or to integrate your application with the Linkfire API?

The Linkfire API is currently open to limited partners. To request access and register your application, e-mail help@linkfire.com and tell us about your desired use-case. We are looking forward to hearing from you!

Postman Collection

If you are a Postman user, today is your lucky day.

The Linkfire Postman collection contains example requests and code snippets for quickly getting started communicating with the Linkfire API endpoints. The collection also includes a set of handy environment variables for each request model.

We highly recommend getting familiarizing yourself with the Linkfire API using the Postman collection.

Download the latest version of the Linkfire Postman collection here.

== Linkfire API URI ==
https://api.linkfire.com 

== Authentication endpoint ==
https://auth.linkfire.com/identity/connect/token 

Authentication

 

Linkfire utilizes OAuth 2.0 for authentication and authorization. The reason we use OAuth 2.0 is so that your integration does not need to store or send any Linkfire user login credentials. If OAuth 2.0 is unfamiliar territory for you, we highly recommend reading this introduction article to OAuth 2.0 by Digital Ocean.

By default, Linkfire API supports the OAuth 2.0 client_credential flow.

Scope

In order to authenticate with the API you need to specify the public.api scope in the request body when requesting your Bearer token. You can do this by making a POST request to https://auth.linkfire.com/identity/connect/token with your assigned API credentials.

 

Errors

 

The Linkfire API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint.
Where possible, the API strives to use appropriate HTTP verbs for each action:

Verb
Description

GET

Used for retrieving resources.

POST

Used for creating resources.

PUT

Used for changing/replacing resources or collections.

DELETE

Used for deleting resources.

All responses come in standard JSON format. The linkfire API is served over HTTPS to ensure data privacy; HTTP is not supported.

Linkfire uses conventional HTTP response codes to indicate the success or failiure of an API request. Generally, codes in the 2xx range indicate success, codes in the 4xxrange indicate an error with the request on the client-side (e.g., a required parameter was omitted), and codes in the 5xxrange indicate an error with Linkfires's servers.

Status Codes
Description

2XX – Success

Everything worked as expected.

400 – Bad Request

Often caused by missing a required parameter or malformed JSON/CSV/XML data

401 – Unauthorized

No valid API credential provided or header is completely missing.

403 – Forbidden

Likely not authenticated against the correct scope.

404 – Not Found

The requested item doesn't exist.

415 – Unsupported Media Type

Request Payload is in an unsupported format.

5XX – Server Errors

Something went wrong on our end.

Linkfire System Status

You can always check the available of Linkfire's servers in real-time on our status page.

 

Generate bearer token

 
posthttps://auth.linkfire.com/identity/connect/token

Form Data

grant_type
string

Grant type defines which OAuth flow to use. At this time, the Linkfire API only supports "client_credentials"

scope
string

Defines which API scope is requested. The Linkfire API uses the "public.api" scope

client_id
string

API Client identifier

client_secret
string

API Client secret

 
curl --request POST \
 --url https://auth.linkfire.com/identity/connect/token \
 --header ‘cache-control: no-cache’ \
 --header ‘content-type: application/x-www-form-urlencoded’ \
 --data ‘grant_type=client_credentials&client_id=YOURID&client_secret=YOURSECRET&scope=public.api’
A binary file was returned

You couldn't be authenticated

{
  "access_token": "80085L09-2da0-37eb-0266-RickC1379f9b",
  "expires_in": 3600,
  "token_type": "Bearer"
}
 

Settings

 

Settings contain endpoints used to manage Board settings and other general preferences of your Linkfire Account.

 

Get boards

 
gethttps://api.linkfire.com/settings/boards

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/settings/boards
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/settings/boards' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/settings/boards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/settings/boards");

xhr.send(data);
import requests

url = "https://api.linkfire.com/settings/boards"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
 {
  "data": [
    {
      "id": "9d4db9f8-f558-49b1-b753-074cf77265ca",
      "parentId": null,
      "name": "my-linkfire-board",
      "domains": [
        "cb54d38b-ec35-4cb3-bdb9-5d6b404ef667",
        "c1515328-2a0b-4a4d-92d8-952b8e684476"
      ],
      "images": []
    }
  ],
  "transactionId": "33b1245f-4325-4b0b-96b2-4cc7403a45e3"
}

Get board domains

 
gethttps://api.linkfire.com/settings/boards/boardId/domains

Path Params

boardId
uuid
required

Board identifier

Headers

Api-Version
string

API version to use

If a domain has the value isFavorite = true, the domain is used by default when new links are created, unless another domain is specified in the request.

curl --request GET \
  --url https://api.linkfire.com/settings/boards/boardId/domains
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api.linkfire.com/settings/boards/boardId/domains' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/settings/boards/boardId/domains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/settings/boards/boardId/domains");

xhr.send(data);
import requests

url = "https://api.linkfire.com/settings/boards/boardId/domains"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{
  "data": [
    {
      "id": "cb54d38b-ec35-4cb3-bdb9-5d6b404ef667",
      "name": "mydomain.lnk.to",
      "isFavorite": true
    },
    {
      "id": "c1515328-2a0b-4a4d-92d8-952b8e684476",
      "name": "myotherdomain.lnk.to",
      "isFavorite": false
    }
  ],
  "transactionId": "5d35778a-00bd-43da-bffa-9dbc9ca09105"
}

Get available media services

 
gethttps://api.linkfire.com/settings/mediaservices

Query Params

description
string

Only get media services that contains this description

name
string

Only get media services that contains this name

page
int32

Page number to get. Default is 0 (first page)

pageSize
int32

Number of media services to get per page. Max 1000

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/settings/mediaservices
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/settings/mediaservices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/settings/mediaservices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/settings/mediaservices");

xhr.send(data);
import requests

url = "https://api.linkfire.com/settings/mediaservices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{
  "totalItemsCount": 1521,
  "data": [
    {
      "id": "0fd09037-1aef-4fcb-b661-c8da0636c3f1",
      "buttonType": "GoTo",
      "name": "Planet Music",
      "description": "Manual integration."
    }
  ],
  "transactionId": "fb2cd76a-55f2-4802-873d-9d3d10215e91"
}

Get board media services

 
gethttps://api.linkfire.com/settings/boards/boardId/mediaservices

Path Params

boardId
uuid
required

Board identifier

Query Params

page
int32

Page number to get. Default is 0 (first page)

pageSize
int32

Number of media services to get per page. Max 1000

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/settings/boards/boardId/mediaservices
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api.linkfire.com/settings/boards/boardId/mediaservices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/settings/boards/boardId/mediaservices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/settings/boards/boardId/mediaservices");

xhr.send(data);
import requests

url = "https://api.linkfire.com/settings/boards/boardId/mediaservices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{
  "totalItemsCount": 17,
  "data": [
    {
      "id": "4a478a1f-d289-4997-934b-6399b56417d2",
      "buttonType": "Download",
      "name": "beatport",
      "description": "Automated integration."
    }
  ],
  "transactionId": "1d950015-78c3-4491-a8ba-95424aef1c82"
}

Batch

 
 
 

Get batch identifiers

 
gethttps://api.linkfire.com/campaigns/boards/boardId/batches

Path Params

boardId
uuid
required

Board identifier

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/campaigns/boards/boardId/batches
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api.linkfire.com/campaigns/boards/boardId/batches' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/campaigns/boards/boardId/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/campaigns/boards/boardId/batches");

xhr.send(data);
import requests

url = "https://api.linkfire.com/campaigns/boards/boardId/batches"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{
  "data": [
    {
      "id": "a271fc85-4444-4ebf-b216-7da42f980599",
      "creatorId": "54dc8d36-f899-4e2c-b84b-db0eee888881",
      "created": "2017-03-16T15:23:56.323"
    },
    {
      "id": "9641201e-fbdb-4798-b718-1180d305d1b9",
      "creatorId": "54dc8d36-f899-4e2c-b84b-db0eee888881",
      "created": "2017-03-16T15:10:24.507"
    }
  ],
  "transactionId": "05b1da72-2633-4bf2-88e1-ba0653ad3c5e"
}

Get batch scanning status

 
gethttps://api.linkfire.com/campaigns/boards/boardId/batches/batchId/scan/status

Path Params

boardId
uuid
required

Board identifier

batchId
uuid
required

Batch identifier

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/campaigns/boards/boardId/batches/batchId/scan/status
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api.linkfire.com/campaigns/boards/boardId/batches/batchId/scan/status' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/campaigns/boards/boardId/batches/batchId/scan/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/campaigns/boards/boardId/batches/batchId/scan/status");

xhr.send(data);
import requests

url = "https://api.linkfire.com/campaigns/boards/boardId/batches/batchId/scan/status"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
 {
  "data": [
    {
      "id": "49e91316-9ebe-46c6-a066-0a892f921856",
      "linkStatus": "NoScanningResults",
      "totalNumbersOfSteps": 22,
      "currentStepNumber": 6,
      "currentAction": "Media service 'itunes' scanning started.",
      "isComplete": false
    },
    {
      "id": "7daec6fd-695f-40b9-8204-8305f93b6068",
      "linkStatus": "Published",
      "totalNumbersOfSteps": 22,
      "currentStepNumber": 22,
      "currentAction": "Scanning completed.",
      "isComplete": true
    }
  ],
  "transactionId": "2ad5fb68-dae4-4161-935b-a4077b3c8071"
}

Campaigns

 
 
 

Get scanning status

 
gethttps://api.linkfire.com/campaigns/boards/boardId/links/linkId/scan/status

Path Params

boardId
uuid
required

Board identifier

linkId
uuid
required

Campaign link identifier

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/campaigns/boards/boardId/links/linkId/scan/status
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api.linkfire.com/campaigns/boards/boardId/links/linkId/scan/status' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/campaigns/boards/boardId/links/linkId/scan/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/campaigns/boards/boardId/links/linkId/scan/status");

xhr.send(data);
import requests

url = "https://api.linkfire.com/campaigns/boards/boardId/links/linkId/scan/status"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{
  "data": {
    "linkStatus": "Published",
    "totalNumbersOfSteps": 22,
    "currentStepNumber": 22,
    "currentAction": "Scanning completed.",
    "isComplete": true
  },
  "transactionId": "a8c3c55a-3222-43df-b5b7-49b2a76c0b02"
}

Get marketing assets

 
gethttps://api.linkfire.com/campaigns/boards/boardId/links/linkId/assets

Path Params

boardId
uuid
required

Board identifier

linkId
uuid
required

Campaign link identifier

Headers

Api-Version
string

API version to use

 
curl --request GET \
  --url https://api.linkfire.com/campaigns/boards/boardId/links/linkId/assets
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api.linkfire.com/campaigns/boards/boardId/links/linkId/assets' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.linkfire.com/campaigns/boards/boardId/links/linkId/assets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.linkfire.com/campaigns/boards/boardId/links/linkId/assets");

xhr.send(data);
import requests

url = "https://api.linkfire.com/campaigns/boards/boardId/links/linkId/assets"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
 {
  "data": {
    "id": "5d971a76-3f17-44a1-be87-d3867b820113",
    "title": "Nana",
    "description": null,
    "status": "Published",
    "linkfireUri": "https://public-api.lnk.to/tbSAh0",
    "baseUri": "https://open.spotify.com/track/6L5X383KFSUMJDenXg4khV",
    "externalId": null,
    "artists": null,
    "album": "DJ Koze Presents Pampa, Vol. 1",
    "track": "Nana",
    "upcCodes": null,
    "isrcCodes": [
      "DEMM11600017"
    ],
    "artwork": [
      {
        "url": "https://linkstorage.linkfire.com/public-api.lnk.to/tbsah0/static/artwork-640x640.jpg",
        "width": 640,
        "heigth": 640
      }
    ],
    "widgets": [
      {
        "width": 300,
        "heigth": 250,
        "embedCode": "<iframe src = \"https://public-api.lnk.to/tbSAh0/widget?size=300x250\" width=\"300\" height=\"250\" frameborder=\"0\" allowtransparency=\"true\" scrolling=\"no\"></iframe>"
      }
    ],
    "directToServiceLinks": [
      {
        "name": "applemusic",
        "uri": "https://public-api.lnk.to/tbSAh0/applemusic",
        "countryCodes": [
          "All",
          "DK",
          "US",
          "GB",
          "JP",
          "FR"
        ]
      },
      {
        "name": "beatport",
        "uri": "https://public-api.lnk.to/tbSAh0/beatport",
        "countryCodes": [
          "All"
        ]
      },
      {
        "name": "spotify",
        "uri": "https://public-api.lnk.to/tbSAh0/spotify",
        "countryCodes": [
          "All"
        ]
      }
    ],
    "created": "2017-03-02T15:16:16.66",
    "channels": null
  },
  "transactionId": "ac687335-cc67-4b30-ba4c-7d58afe71c95"
}