Build Your First Integration

Overview

In the last section, you learned to set up your developer account and gain access to the Linkfire API.

Now, we will take a look at how to build your first Linkfire integration.

At its core, Linkfire makes it easy to create smart music campaign links to a multitude of music services. To create and manage links and creative assets, you will make use of the Campaign API.

Without further ado, let us get started!

1. Authentication

First, you need to authenticate with the API via OAuth 2.0 and get your bearer token. Please refer to the Authentication section in the Getting Started guide.

2. Get the ID of the Board You Want to Create a Link on

All Linkfire links live inside setting containers known as boards. You will always have at least one board available. Some organizations have many boards, e.g. for different teams, genres, artists and so on.

Each board has a title and a unique ID. The ID is a required input parameter for the majority of Linkfire API's endpoints.

You can get a list of all your boards and their IDs by calling the Get boards endpoint.

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/settings/boards',
  headers: 
   {
     authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b',
     'content-type': 'application/json' }};

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

  console.log(body);
});
{
  "data": [
    {
      "id": "9d4db9f8-f558-49b1-b753-074cf77265ca", //boardID
      "parentId": null,
      "name": "my-linkfire-board",
      "domains": [
        "cb54d38b-ec35-4cb3-bdb9-5d6b404ef667",
        "c1515328-2a0b-4a4d-92d8-952b8e684476"
      ],
      "images": []
    }
  ],
  "transactionId": "33b1245f-4325-4b0b-96b2-4cc7403a45e3"
}

Make a note of the boardID in the response object as you will need it later.

3. Get the ID of the Domain You Want to Use For Your Link (Optional)

Boards have a default {{boardname}}.lnk.to domain. If you want to use another domain, you can specify this setting on link creation.
This comes in handy e.g. if you manage many artist campaigns on a board, each with their own artist specific subdomain. Learn more about setting up custom subdomains here.

Call the Get board domains endpoint with the BoardID from step 2 to see the available domains on your board.

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/settings/boards/{{boardId}}/domains',
  headers: 
   {
     authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b',
     'content-type': 'application/json' }};

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

  console.log(body);
});
{
  "data": [
    {
      "id": "cb54d38b-ec35-4cb3-bdb9-5d6b404ef667", // domainID
      "name": "mydomain.lnk.to",
      "isFavorite": true
    },
    {
      "id": "c1515328-2a0b-4a4d-92d8-952b8e684476", // domainID
      "name": "myotherdomain.lnk.to",
      "isFavorite": false
    }
  ],
  "transactionId": "5d35778a-00bd-43da-bffa-9dbc9ca09105"
}

4. Create Linkfire Campaign(s) With Your Music Metadata

Create a Single Link

The Campaign API supports link creation via metadata such as UPC/ISRC codes, artist name, track & album title and music service URLs.

To create a single campaign, make a POST request to the Create campaign link endpoint with the BoardID from step 2, the product's metadata, and—optionally—the DomainID from step 3.
If DomainID is not specified, it will use the default domain for the board.

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardId}}/links',
  headers: 
    {
     authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b',
     'content-type': 'application/json' },
  body: 
    { baseUrl: 'https://open.spotify.com/track/5BSvMOjhomXGMXXUSDGxvU',
      mediaType: 'Music',
      code: 'getSchwifty',
      title: 'Get Schwifty',
      domainId: "a74ef734-9ada-4635-91a5-54ccc0437c1b",
      tags: 'demo' 
    },
  json: true };

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

  console.log(body);
});

Once the campaign link is successfully created, the API returns a JSON object with LinkId and the URL for your campaign link.

{
  "data": {
    "url": "https://public-api.lnk.to/getSchwifty",
    "tags": ["demo"],
    "boardId": "9d4db9f8-f558-49b1-b753-074cf77265ca",
    "created": "2017-03-17T08:43:22.4911799Z",
    "updated": null,
    "status": "NoScanningResults",
    "isScanning": true,
    "images": null,
    "video": null,
    "audio": null,
    "id": "07d16f00-0db3-47e6-8df5-764c086fe5f7",
    "mediaType": "Music",
    "subMediaType": null,
    "title": "Get Schwifty",
    "description": null,
    "baseUrl": "https://open.spotify.com/track/5BSvMOjhomXGMXXUSDGxvU",
    "isrc": null,
    "upc": null
  },
  "transactionId": "e99f8d9d-086e-4662-b855-e54019ad76d5"
}

Create Many Links at Once

For certain use-cases, you might want to create many links at once.
For example, if you want to create campaigns for an entire back catalog of products, or if you distribute a significant amount of new releases every week.

In this case, we advise you batch create your campaigns.

To create batches of links, make a POST request to the Create multiple campaign links endpoint with BoardID, an array of CSV/XML/JSON formatted product metadata such as URLs, UPC or ISRC codes, and—optionally—a DomainID.

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardid}}/links/batch',
  headers: 
    {
     'content-type': 'application/json',
     authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b' },
  body: 
    [
      { baseUrl: 'https://open.spotify.com/track/5BSvMOjhomXGMXXUSDGxvU',
        mediaType: 'Music' 
      },
      { upc: '00602557317718', 
        mediaType: 'Music' 
      },
      { isrc: 'SEWDL6001400', 
        mediaType: 'Music' 
      } 
    ],
  json: true };

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

  console.log(body);
});

The API then queues the entire batch of products for link creation, which processes them on a First-In-First-Out (FIFO) basis.

Please note, that when you create batches of links, the endpoint does NOT return a linkID and Link URL. Instead, it returns a BatchID, used to identify the link batch later on.

{
  "data": {
    "batchId": "a271fc85-4444-4ebf-b216-7da42f980599"
  },
  "transactionId": "1b637f08-138b-4c72-b4f0-bdb024209ca6"
}

Please note that all Linkfire links have auto-redirect enabled by default (recommended).
For example, on her first visit to a Linkfire Campaign a fan selects to listen to the product on Spotify. If auto-redirect is enabled, a cookie is added to her browser.
On future visits to a Linkfire Campaign, she is redirected directly to Spotify, omitting the landing page.

We recommend testing your links in an incognito browser (or delete your cookies).

A PHP example of how to create campaign links in batches is available at the Linkfire GitHub Repository

5. Check the Status of Your Campaign(s)

Check Scanning Status of a Single Link

Please note that your fresh and shiny new campaign link may not be ready for distribution right away. The Linkfire Platform first need to scan the link to find the right content and artwork across our 25+ integrated music services partners.

The scanning usually takes 7 to 30 seconds per link. This depends on service available on your board. Content links, i.e. blog posts, and other "non-media" links, do not need scanning. They are usually ready to distribute right away.

To check the scanning status of your link, call the Get scanning status endpoint.

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardID}}/links/{{linkId}}/scan/status',
  headers: 
    { authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b' } };

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

  console.log(body);
});
{
  "data": {
    "linkStatus": "Published",
    "totalNumbersOfSteps": 22,
    "currentStepNumber": 22,
    "currentAction": "Scanning completed.",
    "isComplete": true
  },
  "transactionId": "a8c3c55a-3222-43df-b5b7-49b2a76c0b02"
}

Once the returned link status is "Published" your campaign is ready for distribution.

Check Scanning Status of a Batch of Links

You can also check scanning status for a batch of links. The links are displayed in the scanning status list as they are being processed from the link creation queue.

To check the scanning status for a batch of links, call the Get batch scanning status endpoint with your BoardID and the BatchID from step 4.

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardID}}/batches/{{batchID}}/scan/status',
  headers: 
   { authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b' } };

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

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

If you forgot your BatchID, you can call the Get batch identifiers endpoint with your BoardID. It will return a list of batches and their creation dates.

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardID}}/batches',
  headers: 
    { authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b' } };
   
request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
{
  "data": [
    {
      "id": "a271fc85-4444-4ebf-b216-7da42f980599", // batchID
      "creatorId": "54dc8d36-f899-4e2c-b84b-db0eee888881",
      "created": "2017-03-16T15:23:56.323"
    },
    {
      "id": "9641201e-fbdb-4798-b718-1180d305d1b9", // batchID
      "creatorId": "54dc8d36-f899-4e2c-b84b-db0eee888881",
      "created": "2017-03-16T15:10:24.507"
    }
  ],
  "transactionId": "05b1da72-2633-4bf2-88e1-ba0653ad3c5e"
}

Rescan Link(s)

If a product is not available on a music service upon link creation—as is often the case with new releases—you can make a POST request to the Rescan campaign link(s) endpoint to rescan the link(s).

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardID}}/links/rescan',
  headers: 
    { authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b' } };
  body: [ 
    'f1433531-c487-42f1-9a0a-5af2ae6e35f0',
    'f1433531-c487-42f1-9a0a-5afCr0mul0n5'
  ],
  json: true };

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

  console.log(body);
});

6. Get Creative Assets for Your Campaign

Once your campaign link has finished scanning, it is ready to share.

The Linkfire platform automatically creates a Marketing Asset Package for your campaign links. This includes a Linkfire landing page, direct-to-service short links, embeddable widgets and artwork.

To get the marketing assets for your link, call the Get marketing assets endpoint with the BoardID and LinkID of your link.

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.linkfire.com/campaigns/boards/{{boardID}}/links/{{linkID}}/assets',
  headers: 
    { authorization: 'Bearer 80085L09-2da0-37eb-0266-RickC1379f9b' } };
request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
{
  "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"
}

Conclusion

That is it, Awesome job! You now know the basics of building Linkfire API integrations. We are excited to see what you will create!

Next, we recommend that you explore our API reference docs to familiarize yourself with the available endpoints.

If you have questions about the API, use-cases or need technical help, reach out to us at [email protected]