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 KeyAPI General Info
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
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
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
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
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
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/