Skip to main content

We’re happy to announce Newswire has acquired HeadTalker!

From the beginning of HeadTalker, we have always placed the comments and happiness of our community first and we believe with this acquisition, we’ll continue to build out our vision for social media virality for brand campaigns as well as improving the opportunities to our user base.

Newswire and HeadTalker are committed to create new and better ways to take a social media message viral.

For now, HeadTalker with continue to function as it does today. Your Headtalker account and campaigns will continue as normal and we’ll be providing more details on upcoming plans for Headtalker in the coming weeks.

If you have any questions, please contact us.

Team HeadTalker and Newswire

API

Welcome to the HeadTalker API.

The HeadTalker API allows you to view your campaign stats and info in a simple, programmatic way using conventional HTTP requests.

Create An API Key

API General Info

API Version 1.0.0
Status: Live

The API will return standard HTTP statuses including error codes for each request.

HTTP Statuses Description
200 This generally indicates the request was successful.
403 This indicates there was an issue with the request sent.
429 This happens when your being rate limited by the API.
500 This generally indicates a server side issue on our end.
Example 403 Status

This an example 403 status response with a helpful error message.



          
Example 429 Status

This an example 429 status response when being rate limited.



          
Example Rate Limit Headers

This an example of the rate limit headers returned.


  RateLimit-Limit: 600
  RateLimit-Remaining: 420
  RateLimit-Reset: 1461720567
          

The number of API request that can be made is capped at 600 per hour.

Campaign ID's Endpoint

HTTP Method: GET
Status: Live

Access all your campaign ID's through this endpoint.

Name Type Description
ids array An array of unique identifiers for all your campaigns.


          
Example CURL Request

Try it out by pasting this command into your terminal.

curl -H "Authorization: Basic 3d125e6fddae98e1d2e586ea79bff621" https://headtalker.com/api/campaign-ids/

Campaign Info Endpoint

HTTP Method: GET
Status: Live

Access your campaign's information through this endpoint.

Name Type Description
id number A unique identifier for each campaign.
url string A unique URL to access the campaign.
title string The title of the campaign.
author string The name of the author who created the campaign.
photo string The featured image URL for the campaign.
video string A unique identifier for a YouTube video.
message string The message that will share once the campaign ends.
link string The message link that will share once the campaign ends.
goal number The goal is the amount of supporters needed for a successful campaign.
end_date number A unix timestamp for the end date of the campaign.


          
Example CURL Request

Try it out by pasting this command into your terminal.

curl -H "Authorization: Basic 3d125e6fddae98e1d2e586ea79bff621" https://headtalker.com/api/campaign-info/?id=XXXXX

Campaign Stats Endpoint

HTTP Method: GET
Status: Live

Access your campaign's stats through this endpoint.

Name Type Description
id number A unique identifier for each campaign.
fb_supporters number The total count of Facebook supporters.
tw_supporters number The total count of Twitter supporters.
tb_supporters number The total count of Tumblr supporters.
ln_supporters number The total count of LinkedIn supporters.
total_supporters number The total count of supporters for all social networks.
total_reach number The combined social reach for every supporter.
timestamps array The total count of supporters for each social network with timestamps.


          
Example CURL Request

Try it out by pasting this command into your terminal.

curl -H "Authorization: Basic 3d125e6fddae98e1d2e586ea79bff621" https://headtalker.com/api/campaign-stats/?id=XXXXX

Campaign Link Endpoint

HTTP Method: GET
Status: Live

Access your shortlink stats and track your messages analytics through this endpoint.

Name Type Description
id number A unique identifier for each campaign.
clicks array The total counts of clicks and unique clicks.
timestamps array The total clicks with date timestamps for each day of the campaign + 2 weeks after.
countries object The total clicks per country with country abbreviations.
Example CURL Request

Try it out by pasting this command into your terminal.

curl -H "Authorization: Basic 3d125e6fddae98e1d2e586ea79bff621" https://headtalker.com/api/campaign-link/?id=XXXXX

Countries Endpoint

HTTP Method: GET
Status: Live

Access all possible countries with abbreviations for your shortlink analytics through this endpoint.

Name Type Description
countries_list object The list of all possible countries with abbreviations.


          
Example CURL Request

Try it out by pasting this command into your terminal.

curl -H "Authorization: Basic 3d125e6fddae98e1d2e586ea79bff621" https://headtalker.com/api/countries-list/
Got a question, suggestion, or need some help getting started?
Get In Touch