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/