NAV
bash php

Introduction

Welcome to the Pinpoll API! You can use our API to access Pinpoll API endpoints.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request

# create/read or update users
curl "api_endpoint_here"
  -X-Api-Key "your_api_key"

# user requests
curl "api_endpoint_here"
  -Authorization "Bearer user_key"
<?php
// Just pass the correct header with each request

// create/read or update users
$request = new HttpRequest();
$request->setUrl('api_endpoint_here');
$request->setHeaders(array(
  'x-api-key' => 'your_api_key'
));

// user requests
$request = new HttpRequest();
$request->setUrl('api_endpoint_here');
$request->setHeaders(array(
  'Authorization' => 'Bearer user_key'
));
?>

Make sure to replace your_api_key with your API key and user_key with the token issued for the specific user.

Pinpoll uses API keys to allow access to the API. You can request a new Pinpoll API key via email to support@pinpoll.com.

Pinpoll expects for the API key to be included in all API requests, that create/read or update users. The API key must be included in a header that looks like the following:

X-Api-Key: your_api_key

With your Pinpoll API key you can register/sign-in Pinpoll users. Upon registration or sign-in, Pinpoll will issue a token for the specified user. This token must be included in all API requests, issued on the user's behalf:

Authorization: Bearer user_token

User Sign Up

curl -X POST -H "X-Api-Key: your_api_key" -d '{
  "email": "test@test.com",
  "language" : "de",
  "firstname" : "Testy",
  "lastname" : "Testwoman",
  "username" : "test123",
  "gender" : "female",
  "app_key" : "my_password",
  "domain" : "http://testdomain.com"
}' "https://pinpoll.com/v1/auth/signup"
<?php
$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/auth/signup');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'x-api-key' => 'your_api_key'
));

$request->setBody('{
  "email": "test@test.com",
  "language" : "de",
  "firstname" : "Testy",
  "lastname" : "Testwoman",
  "username" : "test123",
  "gender" : "female",
  "app_key" : "my_password",
  "domain" : "http://testdomain.com"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

The above command returns JSON structured like this:

{
  "success": "User registered"
}

This endpoint registers a new user. The response contains a token issued for the specified user in the header. This token must be included in all subsequent calls to the API. For security reasons, the token will expire after a certain amount of time. See Token Refresh for details.

HTTP Request

POST https://pinpoll.com/auth/signup

JSON Body Parameters

Parameter Values Mandatory Description
email string x The user's email address
app_key string x The user's key to access Pinpoll
language string x The user's preferred language
firstname string The user's first name
lastname string The user's last name
domain string The user's domain
username string Identification string for this user

User Sign In

curl -X POST -H "X-Api-Key: your_api_key" -d '{
"email": "test@test.com",
"app_key" : "my_password",
}' "https://pinpoll.com/v1/auth/signin"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/auth/signin');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'x-api-key' => 'your_api_key'
));

$request->setBody('{
"email": "test11@test.com",
"app_key" : "my_password",
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "user": {
    "user_group_id": 1,
    "username": "test123",
    "email": "test11@test.com",
    "image": null,
    "firstname": "Testy",
    "lastname": "Testwoman",
    "company": null,
    "vatid": null,
    "gender": "unspecified",
    "useowndomain": false,
    "language": "de",
    "timezone": null,
    "location": null,
    "street": null,
    "postal_code": null,
    "city": null,
    "country": null,
    "description": null,
    "deactivated": 0,
    "created_at": "2016-10-10 09:13:29",
    "updated_at": "2016-10-10 09:13:29",
    "stripe_id": null,
    "card_brand": null,
    "card_last_four": null,
    "trial_ends_at": null,
    "app_id": 3,
    "is_poweruser": false,
    "group": {
      "id": 1,
      "title": "Free",
      "created_at": "2015-09-04 07:52:42",
      "updated_at": "2015-09-04 07:55:37",
      "permissions": [
        {
          "title": "EDIT.NONCOMMERCIAL.ONLY"
        }
      ]
    }
  }
}

This endpoint performs a user log in. The response contains a token issued for the specified user in the header. This token must be included in all subsequent calls to the API. For security reasons, the token will expire after a certain amount of time. See Token Refresh for details.

HTTP Request

POST https://pinpoll.com/auth/signin

JSON Body Parameters

Parameter Values Mandatory Description
email string x The user's email address
app_key string if no 'cockpit_password' provided The user's key to access Pinpoll
cockpit_password string if no 'app_key' provided The user's cockpit password. If both, cockpit password and app_key are sent, the app_key will be registered for the specified user and subsequent logins can be performed providing the app_key only.

Token Refresh

curl -X POST -H "Authorization: Bearer user_token" "https://pinpoll.com/v1/auth/refresh"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/auth/refresh');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The token issued for a specific user expires after a certain amount of time. If a token has expired, API calls will fail with error code 400 and message {"error":"token_expired"}. Call this endpoint to refresh the token. If the token has not been used for a long period of time, refresh will fail with error code 400 or 401 and you will need to call Sign In again to obtain a new valid token.

HTTP Request

POST https://pinpoll.com/auth/refresh

Polls

Retrieve a list of polls

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/polls"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

[
{
  "id": 4419,
  "category_id": 4,
  "active": 1,
  "multiple_vote_interval": "WEEK",
  "sort": 0,
  "reset_at": null,
  "created_at": "2016-08-02 12:58:18",
  "updated_at": "2016-09-12 21:15:02",
  "deleted_at": null,
  "isOwn": true,
  "locale": null,
  "timeout": null,
  "embedsetting": {
    "layout_id": null,
    "color": "#ff0000",
    "bgcolor": "#2e3239",
    "darken": 40,
    "height": 0,
    "showRecommendations": true,
    "recommendationBtnsDelay": 4,
    "showMap": true,
    "showShareButtons": true,
    "customCss": null,
    "recaptcha": false,
    "hide_logo": {
      "error": 1,
      "message": "Permission needed",
      "data": null,
      "permission": {
        "title": "USE.EMBED.HIDELOGO",
        "price": {
          "price": 99,
          "per_poll": 1,
          "description": "payment.items.permissions.logo",
          "tax": 20
        }
      }
    }
  },
  "answers": [
    {
      "id": 12254,
      "poll_id": 4419,
      "sort": 0,
      "votes": 0,
      "reset_at": null,
      "deleted_at": null,
      "created_at": "2016-08-02 12:58:19",
      "updated_at": "2016-08-02 12:58:19",
      "answer": "a"
    },
    {
      "id": 12255,
      "poll_id": 4419,
      "sort": 1,
      "votes": 1,
      "reset_at": null,
      "deleted_at": null,
      "created_at": "2016-08-02 12:58:19",
      "updated_at": "2016-09-12 21:10:59",
      "answer": "b"
    }
  ],
  "question": "Test"
}
]

This endpoint retrieves all polls for the user specified by user_token.

HTTP Request

GET https://pinpoll.com/v1/polls

Retrieve a single Poll

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/polls/1"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls/1');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "id": 1,
  "category_id": 4,
  "active": 1,
  "multiple_vote_interval": "WEEK",
  "sort": 0,
  "reset_at": null,
  "created_at": "2016-08-02 12:58:18",
  "updated_at": "2016-09-12 21:15:02",
  "deleted_at": null,
  "isOwn": true,
  "locale": null,
  "timeout": null,
  "embedsetting": {
    "layout_id": null,
    "color": "#ff0000",
    "bgcolor": "#2e3239",
    "darken": 40,
    "height": 0,
    "showRecommendations": true,
    "recommendationBtnsDelay": 4,
    "showMap": true,
    "showShareButtons": true,
    "customCss": null,
    "recaptcha": false,
    "hide_logo": {
      "error": 1,
      "message": "Permission needed",
      "data": null,
      "permission": {
        "title": "USE.EMBED.HIDELOGO",
        "price": {
          "price": 99,
          "per_poll": 1,
          "description": "payment.items.permissions.logo",
          "tax": 20
        }
      }
    }
  },
  "answers": [
    {
      "id": 12254,
      "poll_id": 4419,
      "sort": 0,
      "votes": 0,
      "reset_at": null,
      "deleted_at": null,
      "created_at": "2016-08-02 12:58:19",
      "updated_at": "2016-08-02 12:58:19",
      "answer": "a"
    },
    {
      "id": 12255,
      "poll_id": 4419,
      "sort": 1,
      "votes": 1,
      "reset_at": null,
      "deleted_at": null,
      "created_at": "2016-08-02 12:58:19",
      "updated_at": "2016-09-12 21:10:59",
      "answer": "b"
    }
  ],
  "question": "Test"
}

This endpoint retrieves a specific poll.

HTTP Request

GET https://pinpoll.com/v1/polls/<ID>

URL Parameters

Parameter Values Description
ID int The ID of the poll

Retrieve datatable of polls

curl -X POST -H "Authorization: Bearer user_token" -d '{
  "start": "0",
  "length": "2"
}' "https://pinpoll.com/v1/polls/datatables"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/datatables');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

$request->setBody('{
  "start": "0",
  "length": "2"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "draw": 0,
  "recordsTotal": 15,
  "recordsFiltered": 15,
  "data": [
    {
      "id": 4411,
      "votes": 4,
      "created_at": "2016-07-22 12:32:53",
      "active": 1,
      "question": "Test",
      "locale": "en",
      "category": "finance",
      "user_image": null
    },
    {
      "id": 4414,
      "votes": 0,
      "created_at": "2016-08-01 10:29:38",
      "active": 0,
      "question": "Test3",
      "locale": "en",
      "category": "beauty",
      "user_image": null
    }
  ],
  "input": {
    "start": "0",
    "length": "2"
  }
}

This endpoint retrieves a datatable of all polls the user (identifies by user_token) has permission to view.

HTTP Request

POST https://pinpoll.com/v1/polls/datatables

JSON Body Parameters

Parameter Values Mandatory Description
start integer Index to start from
length integer Number of polls to fetch

Create a new Poll

curl -X POST -H "Authorization: Bearer user_token" -d '{
  "question": "my_question",
  "answers": ["my_first_option","my_second_option"],
  "category_id" : "1",
  "layout_id" : "1",
  "color":"#DB1032",
  "bgcolor":"#2E3239",
  "darken" :"50",
  "height" :"0"
}' "https://pinpoll.com/v1/polls"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

$request->setBody('{
  "question": "my_question",
  "answers": ["my_first_option","my_second_option"],
  "category_id" : "1",
  "layout_id" : "1",
  "color":"#DB1032",
  "bgcolor":"#2E3239",
  "darken" :"50",
  "height" :"0"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "category_id": "1",
  "user_id": 109,
  "id": 4493,
  "locale": null,
  "answers": [
    {
      "sort": 0,
      "poll_id": 4493,
      "id": 12401,
      "answer": "my_first_option"
    },
    {
      "sort": 1,
      "poll_id": 4493,
      "id": 12402,
      "answer": "my_second_option"
    }
  ],
  "question": "my_question"
}

This endpoint creates a new poll

HTTP Request

POST https://pinpoll.com/v1/polls

JSON Body Parameters

Parameter Values Mandatory Description
question string x The poll's question
answers array x Text for each answer option
category_id integer x Category that best describes this poll's topic
layout_id integer x Layout to use for this poll
color string x Highlight color
bgcolor string x Background color
image string base64 encoded image
darken int x Darken all images 100=black, 0=original image

Activate poll

curl -X POST -H "Authorization: Bearer user_token" "https://pinpoll.com/v1/polls/1/activate"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls/1/activate');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "active": 1
}

This endpoint activates a poll

HTTP Request

POST https://pinpoll.com/v1/polls/<ID>/activate

URL Parameters

Parameter Values Description
ID int The ID of the poll

Set timeout

curl -X POST -H "Authorization: Bearer user_token" -d '{
  "timeout_start":"2016-10-12 11:39:09",
    "timeout_end":"2016-10-12 12:40:09"
}' "https://pinpoll.com/v1/polls/1/timeout"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls/1/timeout');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

$request->setBody('{
  "timeout_start":"2016-10-12 11:39:09",
    "timeout_end":"2016-10-12 12:40:09"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "id": 1,
  "category_id": 3,
  "active": true,
  "multiple_vote_interval": null,
  "sort": 0,
  "reset_at": "2016-07-28 11:30:56",
  "created_at": "2016-07-22 12:32:53",
  "updated_at": "2016-10-12 11:25:34",
  "deleted_at": null,
  "isOwn": true,
  "locale": null,
  "timeout": {
    "poll_id": 4411,
    "start_at": "2016-10-12 11:39:09",
    "timeout_at": "2016-10-12 12:40:09",
    "start_at_calculated": "2016-10-12 11:39:09"
  },
  "embedsetting": {
    "layout_id": null,
    "color": "#ff0000",
    "bgcolor": "#2e3239",
    "darken": 40,
    "height": 0,
    "showRecommendations": true,
    "recommendationBtnsDelay": 4,
    "showMap": true,
    "showShareButtons": true,
    "customCss": null,
    "recaptcha": false,
    "hide_logo": {
      "error": 1,
      "message": "Permission needed",
      "data": null,
      "permission": {
        "title": "USE.EMBED.HIDELOGO",
        "price": {
          "price": 99,
          "per_poll": 1,
          "description": "payment.items.permissions.logo",
          "tax": 20
        }
      }
    }
  },
  "question": "Test"
}

This endpoint sets the interval of time a poll is active for.

HTTP Request

POST https://pinpoll.com/v1/polls/<ID>/timeout

URL Parameters

Parameter Values Description
ID int The ID of the poll

Reset poll

curl -X POST -H "Authorization: Bearer user_token" "https://pinpoll.com/v1/polls/1/reset"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls/1/reset');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "poll": {
    "id": 1,
    "category_id": 3,
    "active": 1,
    "multiple_vote_interval": null,
    "sort": 0,
    "reset_at": "2016-10-12 11:44:56",
    "created_at": "2016-07-22 12:32:53",
    "updated_at": "2016-10-12 11:25:34",
    "deleted_at": null,
    "isOwn": true,
    "stats": {
      "lifetime": {
        "votes": 0,
        "views": 0,
        "views_unique": 0,
        "votes_unique": 0,
        "recommendation_clicks": 0,
        "recommendation_clicks_after_vote": 0
      },
      "range": {
        "votes": 0,
        "views": 2,
        "views_unique": 0,
        "votes_unique": 0,
        "recommendation_clicks": 0,
        "recommendation_clicks_after_vote": 0,
        "range": {
          "period": 720,
          "start": "2016-09-12 11:44:56",
          "end": "2016-10-12 12:44:56"
        }
      },
      "history": {},
      "embeds": []
    },
    "countries": [],
    "cities": [],
    "result": [
      {
        "answer_id": 12237,
        "votes": "0.00",
        "votes_view": 0,
        "color": "#13458E"
      },
      {
        "answer_id": 12238,
        "votes": "0.00",
        "votes_view": 0,
        "color": "#EA0064"
      }
    ],
    "topembed": "http://pinpollcom.dev/cockpit/polls/4411",
    "locale": "en",
    "timeout": {
      "poll_id": 1,
      "start_at": "2016-10-12 11:39:09",
      "timeout_at": "2016-10-12 12:40:09",
      "start_at_calculated": "2016-10-12 11:39:09"
    },
    "embedsetting": {
      "layout_id": null,
      "color": "#ff0000",
      "bgcolor": "#2e3239",
      "darken": 40,
      "height": 0,
      "showRecommendations": true,
      "recommendationBtnsDelay": 4,
      "showMap": true,
      "showShareButtons": true,
      "customCss": null,
      "recaptcha": false,
      "hide_logo": {
        "error": 1,
        "message": "Permission needed",
        "data": null,
        "permission": {
          "title": "USE.EMBED.HIDELOGO",
          "price": {
            "price": 99,
            "per_poll": 1,
            "description": "payment.items.permissions.logo",
            "tax": 20
          }
        }
      }
    },
    "image": null,
    "answers": [
      {
        "id": 12237,
        "poll_id": 1,
        "sort": 0,
        "votes": 0,
        "reset_at": "2016-10-12 11:44:56",
        "deleted_at": null,
        "created_at": "2016-07-22 12:32:53",
        "updated_at": "2016-10-12 11:44:56",
        "color": "#13458E",
        "image": null,
        "answer": "a"
      },
      {
        "id": 12238,
        "poll_id": 1,
        "sort": 1,
        "votes": 0,
        "reset_at": "2016-10-12 11:44:56",
        "deleted_at": null,
        "created_at": "2016-07-22 12:32:53",
        "updated_at": "2016-10-12 11:44:56",
        "color": "#EA0064",
        "image": null,
        "answer": "b"
      }
    ],
    "question": "Test"
  }
}

This endpoint resets all votes on a poll.

HTTP Request

POST https://pinpoll.com/v1/polls/<ID>/reset

URL Parameters

Parameter Values Description
ID int The ID of the poll

Delete poll

curl -X POST -H "Authorization: Bearer user_token" "https://pinpoll.com/v1/polls/1"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls/1');
$request->setMethod(HTTP_METH_DELETE);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "delete":true
}

This endpoint deletes a poll.

HTTP Request

POST https://pinpoll.com/v1/polls/<ID>

URL Parameters

Parameter Values Description
ID int The ID of the poll

Retrieve votes for time range

curl -X POST -H "Authorization: Bearer user_token" -d '{{
    "range":
        {
        "start":"2016-09-14 10:14:10",
        "end":"2016-10-13 10:14:10",
        "period":"30d\n"
        }
}' "https://pinpoll.com/v1/polls/1/range"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/polls/1/range');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

$request->setBody('{
    "range":
        {
        "start":"2016-09-14 10:14:10",
        "end":"2016-10-13 10:14:10",
        "period":"30d\n"
        }
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "range": {
    "votes": 0,
    "views": 0,
    "views_unique": 0,
    "votes_unique": 0,
    "recommendation_clicks": 5,
    "recommendation_clicks_after_vote": 1,
    "range": {
      "start": "2016-09-14 10:14:10",
      "end": "2016-10-13 10:14:10",
      "period": "30d\n"
    }
  },
  "embeds": []
}

This endpoint retrieves the number of votes and views for a given time range.

HTTP Request

POST https://pinpoll.com/v1/polls/<ID>/range

URL Parameters

Parameter Values Description
ID int The ID of the poll

JSON Body Parameters

If no range is given, 24h is used as default.

Parameter Values Mandatory Description
range[start] date Start of period
range[end] date End of period
range[period] string Example given: 30d, 7d, 24h

Statistics

Retrieve poll statistics

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/stats"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/stats');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  {
    "votes": "14050",
    "votes_month": "291035",
    "countries": [
      {
        "location": "AT",
        "votes": "8815"
      },
      {
        "location": "US",
        "votes": "2458"
      },
      {
        "location": "DE",
        "votes": "1503"
      },
      {
        "location": "CH",
        "votes": "296"
      },
      {
        "location": "EU",
        "votes": "156"
      },
      {
        "location": "LI",
        "votes": "119"
      },
      {
        "location": "CA",
        "votes": "101"
      },
      {
        "location": "GB",
        "votes": "84"
      },
      {
        "location": "AU",
        "votes": "58"
      },
      {
        "location": "IN",
        "votes": "40"
      }
    ],
    "cities": [
      {
        "location": "Vienna",
        "votes": "443"
      },
      {
        "location": "Salzburg",
        "votes": "411"
      },
      {
        "location": "Provo",
        "votes": "270"
      },
      {
        "location": "Dornbirn",
        "votes": "165"
      },
      {
        "location": "Feldkirch",
        "votes": "164"
      },
      {
        "location": "Bregenz",
        "votes": "153"
      },
      {
        "location": "Munich",
        "votes": "116"
      },
      {
        "location": "Frankfurt",
        "votes": "111"
      },
      {
        "location": "Lustenau",
        "votes": "106"
      },
      {
        "location": "Linz",
        "votes": "84"
      }
    ]
  }
}

This endpoint retrieves statistics for all polls of the last 24h. It returns the following data:

votes - the number of votes over the last 24 hours

votes_month - the number of votes in the last month

countries - 10 countries with most votes over the last 24 hours

cities - 10 cities with most votes over the last 24 hours

HTTP Request

GET https://pinpoll.com/v1/stats

Retrieve top polls

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/top"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/top');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "hours": [
    13,
    14,
    15,
    16,
    17,
    18,
    19,
    20,
    21,
    22,
    23,
    0,
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12
  ],
  "polls": [
    {
      "id": 29989,
      "user_id": 7207,
      "category_id": 20,
      "active": 1,
      "multiple_vote_interval": null,
      "sort": 0,
      "reset_at": null,
      "created_at": "2016-10-12 12:35:32",
      "updated_at": "2016-10-13 12:24:01",
      "deleted_at": null,
      "isOwn": false,
      "votesByHour": [
        398,
        229,
        227,
        120,
        121,
        109,
        91,
        53,
        49,
        30,
        22,
        4,
        3,
        6,
        6,
        7,
        9,
        24,
        29,
        28,
        14,
        17,
        10,
        2
      ],
      "viewsByHour": [
        1437,
        886,
        744,
        558,
        460,
        367,
        314,
        241,
        184,
        128,
        76,
        32,
        23,
        14,
        20,
        21,
        47,
        99,
        129,
        104,
        95,
        60,
        50,
        13
      ],
      "locale": null,
      "timeout": null,
      "embedsetting": {
        "layout_id": 1,
        "color": "#0e0000",
        "bgcolor": "#b1dad9",
        "darken": 40,
        "height": 0,
        "showRecommendations": false,
        "recommendationBtnsDelay": 4,
        "showMap": false,
        "showShareButtons": false,
        "customCss": null,
        "recaptcha": false,
        "hide_logo": true
      },
      "question": "Mehr Geld f\u00fcr den ORF: Stimmen Sie einer Geb\u00fchrenerh\u00f6hung zu?"
    },
    {
      "id": 30004,
      "user_id": 1218,
      "category_id": 25,
      "active": 1,
      "multiple_vote_interval": null,
      "sort": 0,
      "reset_at": null,
      "created_at": "2016-10-12 15:48:48",
      "updated_at": "2016-10-13 12:25:15",
      "deleted_at": null,
      "isOwn": false,
      "votesByHour": [
        0,
        0,
        0,
        62,
        175,
        118,
        167,
        146,
        129,
        121,
        36,
        25,
        6,
        8,
        4,
        15,
        39,
        116,
        135,
        81,
        44,
        40,
        35,
        26
      ],
      "viewsByHour": [
        0,
        0,
        0,
        96,
        276,
        182,
        271,
        224,
        190,
        174,
        73,
        36,
        18,
        12,
        6,
        28,
        73,
        184,
        226,
        141,
        89,
        72,
        61,
        35
      ],
      "locale": null,
      "timeout": null,
      "embedsetting": {
        "layout_id": 1,
        "color": "#f3b900",
        "bgcolor": "#00acf2",
        "darken": 40,
        "height": 0,
        "showRecommendations": false,
        "recommendationBtnsDelay": 4,
        "showMap": false,
        "showShareButtons": false,
        "customCss": null,
        "recaptcha": false,
        "hide_logo": false
      },
      "question": "Sind die ORF-Geb\u00fchren noch gerechtfertigt?"
    },
    {
      "id": 29991,
      "user_id": 7207,
      "category_id": 20,
      "active": 1,
      "multiple_vote_interval": null,
      "sort": 0,
      "reset_at": null,
      "created_at": "2016-10-12 12:41:30",
      "updated_at": "2016-10-13 12:24:49",
      "deleted_at": null,
      "isOwn": false,
      "votesByHour": [
        322,
        176,
        173,
        98,
        99,
        75,
        58,
        43,
        28,
        25,
        11,
        5,
        3,
        4,
        5,
        3,
        5,
        18,
        28,
        22,
        10,
        11,
        7,
        3
      ],
      "viewsByHour": [
        1436,
        886,
        744,
        557,
        458,
        367,
        315,
        240,
        184,
        128,
        77,
        32,
        23,
        14,
        20,
        20,
        47,
        99,
        128,
        103,
        95,
        60,
        50,
        13
      ],
      "locale": null,
      "timeout": null,
      "embedsetting": {
        "layout_id": 1,
        "color": "#0e0000",
        "bgcolor": "#b1dad9",
        "darken": 40,
        "height": 0,
        "showRecommendations": false,
        "recommendationBtnsDelay": 4,
        "showMap": false,
        "showShareButtons": false,
        "customCss": null,
        "recaptcha": false,
        "hide_logo": true
      },
      "question": "Zahlen Sie GIS?"
    },
    {
      "id": 29990,
      "user_id": 7207,
      "category_id": 20,
      "active": 1,
      "multiple_vote_interval": null,
      "sort": 0,
      "reset_at": null,
      "created_at": "2016-10-12 12:40:42",
      "updated_at": "2016-10-13 12:23:35",
      "deleted_at": null,
      "isOwn": false,
      "votesByHour": [
        317,
        162,
        168,
        90,
        89,
        67,
        53,
        45,
        32,
        28,
        15,
        4,
        2,
        4,
        5,
        4,
        6,
        18,
        19,
        21,
        13,
        8,
        5,
        1
      ],
      "viewsByHour": [
        1437,
        885,
        741,
        556,
        458,
        366,
        315,
        241,
        184,
        128,
        77,
        32,
        23,
        14,
        20,
        20,
        47,
        99,
        128,
        103,
        95,
        60,
        48,
        13
      ],
      "locale": null,
      "timeout": null,
      "embedsetting": {
        "layout_id": 1,
        "color": "#0e0000",
        "bgcolor": "#b1dad9",
        "darken": 40,
        "height": 0,
        "showRecommendations": false,
        "recommendationBtnsDelay": 4,
        "showMap": false,
        "showShareButtons": false,
        "customCss": null,
        "recaptcha": false,
        "hide_logo": true
      },
      "question": "Sollte der ORF weniger Werbung machen?"
    },
    {
      "id": 30003,
      "user_id": 7207,
      "category_id": 26,
      "active": 1,
      "multiple_vote_interval": null,
      "sort": 0,
      "reset_at": null,
      "created_at": "2016-10-12 15:40:45",
      "updated_at": "2016-10-13 12:25:11",
      "deleted_at": null,
      "isOwn": false,
      "votesByHour": [
        0,
        0,
        19,
        145,
        107,
        114,
        121,
        90,
        65,
        64,
        43,
        12,
        2,
        6,
        8,
        6,
        17,
        41,
        60,
        41,
        32,
        23,
        18,
        10
      ],
      "viewsByHour": [
        0,
        0,
        141,
        856,
        653,
        708,
        693,
        615,
        511,
        409,
        197,
        93,
        25,
        31,
        30,
        39,
        144,
        356,
        475,
        372,
        251,
        140,
        180,
        108
      ],
      "locale": null,
      "timeout": null,
      "embedsetting": {
        "layout_id": 1,
        "color": "#0e0000",
        "bgcolor": "#b1dad9",
        "darken": 40,
        "height": 0,
        "showRecommendations": false,
        "recommendationBtnsDelay": 4,
        "showMap": false,
        "showShareButtons": false,
        "customCss": null,
        "recaptcha": false,
        "hide_logo": true
      },
      "question": "Klassische Abfahrt oder Sprint-Abfahrt in zwei Durchg\u00e4ngen?"
    }
  ]
}

This endpoint retrieves the top polls in terms of votes for the last 24 hours.

The image below shows a sample view for the top 5 polls: Sample view

HTTP Request

GET https://pinpoll.com/v1/top

Categories

Retrieve a list of categories

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/categories"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/categories');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "title": "Arts & Humanities",
    "shortcut": "arts_hum",
    "created_at": "2012-04-05 16:49:16",
    "updated_at": "2016-01-19 12:09:51"
  },
  {
    "id": 2,
    "title": "Beauty & Style",
    "shortcut": "beauty",
    "created_at": "2012-04-05 16:49:27",
    "updated_at": "2016-01-19 12:09:59"
  },
  {
    "id": 3,
    "title": "Business & Finance",
    "shortcut": "finance",
    "created_at": "2012-04-05 16:49:38",
    "updated_at": "2016-01-19 12:10:04"
  },
  {
    "id": 4,
    "title": "Cars & Transportation",
    "shortcut": "transport",
    "created_at": "2012-04-05 16:49:48",
    "updated_at": "2016-01-19 12:10:09"
  },
  {
    "id": 5,
    "title": "Computers & Internet",
    "shortcut": "computer",
    "created_at": "2012-04-05 16:49:59",
    "updated_at": "2016-01-19 12:10:13"
  },
  {
    "id": 6,
    "title": "Consumer Electronics",
    "shortcut": "electronics",
    "created_at": "2012-04-05 16:50:10",
    "updated_at": "2016-01-19 12:10:18"
  },
  {
    "id": 7,
    "title": "Dining Out",
    "shortcut": "dining",
    "created_at": "2012-04-05 16:50:18",
    "updated_at": "2016-01-19 12:10:23"
  },
  {
    "id": 8,
    "title": "Education & Reference",
    "shortcut": "education",
    "created_at": "2012-04-05 16:50:27",
    "updated_at": "2016-01-19 12:10:25"
  },
  {
    "id": 9,
    "title": "Entertainment & Music",
    "shortcut": "entertainment",
    "created_at": "2012-04-05 16:50:36",
    "updated_at": "2016-01-19 12:11:33"
  },
  {
    "id": 10,
    "title": "Environment",
    "shortcut": "environment",
    "created_at": "2012-04-05 16:50:44",
    "updated_at": "2016-01-19 12:11:38"
  },
  {
    "id": 11,
    "title": "Events",
    "shortcut": "events",
    "created_at": "2012-04-05 16:50:52",
    "updated_at": "2016-01-19 12:11:43"
  },
  {
    "id": 12,
    "title": "Family & Relationships",
    "shortcut": "fam_relation",
    "created_at": "2012-04-05 16:51:03",
    "updated_at": "2016-01-19 12:11:48"
  },
  {
    "id": 13,
    "title": "Food & Drink",
    "shortcut": "food_drink",
    "created_at": "2012-04-05 16:51:12",
    "updated_at": "2016-01-19 12:11:53"
  },
  {
    "id": 14,
    "title": "Games & Recreation",
    "shortcut": "games",
    "created_at": "2012-04-05 16:51:20",
    "updated_at": "2016-01-19 12:11:57"
  },
  {
    "id": 15,
    "title": "Health",
    "shortcut": "health",
    "created_at": "2012-04-05 16:51:30",
    "updated_at": "2016-01-19 12:12:02"
  },
  {
    "id": 16,
    "title": "Home & Garden",
    "shortcut": "home_garden",
    "created_at": "2012-04-05 16:51:39",
    "updated_at": "2016-01-19 12:12:06"
  },
  {
    "id": 17,
    "title": "Local Businesses",
    "shortcut": "local_bus",
    "created_at": "2012-04-05 16:52:01",
    "updated_at": "2016-01-19 12:12:10"
  },
  {
    "id": 18,
    "title": "News",
    "shortcut": "news",
    "created_at": "2012-04-05 16:52:11",
    "updated_at": "2016-01-19 12:12:14"
  },
  {
    "id": 19,
    "title": "Pets",
    "shortcut": "pets",
    "created_at": "2012-04-05 16:52:20",
    "updated_at": "2016-01-19 12:12:19"
  },
  {
    "id": 20,
    "title": "Politics & Government",
    "shortcut": "politics",
    "created_at": "2012-04-05 16:52:29",
    "updated_at": "2016-01-19 12:12:24"
  },
  {
    "id": 21,
    "title": "Pregnancy & Parenting",
    "shortcut": "parenting",
    "created_at": "2012-04-05 16:52:38",
    "updated_at": "2016-01-19 12:12:28"
  },
  {
    "id": 22,
    "title": "Science & Mathematics",
    "shortcut": "science",
    "created_at": "2012-04-05 16:52:48",
    "updated_at": "2016-01-19 12:12:33"
  },
  {
    "id": 23,
    "title": "Social Science",
    "shortcut": "social_science",
    "created_at": "2012-04-05 16:52:56",
    "updated_at": "2016-01-19 12:12:37"
  },
  {
    "id": 24,
    "title": "Photography",
    "shortcut": "photography",
    "created_at": "2012-04-05 16:53:04",
    "updated_at": "2016-01-19 12:12:42"
  },
  {
    "id": 25,
    "title": "Society & Culture",
    "shortcut": "society_cult",
    "created_at": "2012-04-05 16:53:12",
    "updated_at": "2016-01-19 12:12:46"
  },
  {
    "id": 26,
    "title": "Sports & Fitness",
    "shortcut": "sports",
    "created_at": "2012-04-05 16:53:21",
    "updated_at": "2016-01-19 12:12:50"
  },
  {
    "id": 27,
    "title": "Travel & Places",
    "shortcut": "travel",
    "created_at": "2012-04-05 16:53:30",
    "updated_at": "2016-01-19 12:12:55"
  },
  {
    "id": 32,
    "title": "Other",
    "shortcut": "other",
    "created_at": "2012-04-05 16:54:21",
    "updated_at": "2016-01-19 12:12:59"
  },
  {
    "id": 36,
    "title": "Work & Career",
    "shortcut": "career",
    "created_at": "2013-09-06 11:59:24",
    "updated_at": "2016-01-19 12:13:01"
  }
]

This endpoint retrieves all categories.

HTTP Request

GET https://pinpoll.com/v1/categories

Countries

Retrieve a list of countries

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/countries"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/countries');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

[
  {
    "id": "AD",
    "name": "Andorra"
  },
  {
    "id": "AE",
    "name": "United Arab Emirates"
  },
  {
    "id": "AF",
    "name": "Afghanistan"
  },
  {
    "id": "AG",
    "name": "Antigua and Barbuda"
  },
  {
    "id": "AI",
    "name": "Anguilla"
  },
  {
    "id": "AL",
    "name": "Albania"
  },
  {
    "id": "AM",
    "name": "Armenia"
  },
  {
    "id": "AO",
    "name": "Angola"
  },
  {
    "id": "AQ",
    "name": "Antarctica"
  },
  {
    "id": "AR",
    "name": "Argentina"
  },
  {
    "id": "AT",
    "name": "Austria"
  },
  {
    "id": "AU",
    "name": "Australia"
  },
  {
    "id": "AW",
    "name": "Aruba"
  },
  {
    "id": "AZ",
    "name": "Azerbaijan"
  },
  {
    "id": "BA",
    "name": "Bosnia and Herzegovina"
  },
  {
    "id": "BB",
    "name": "Barbados"
  },
  {
    "id": "BD",
    "name": "Bangladesh"
  },
  {
    "id": "BE",
    "name": "Belgium"
  },
  {
    "id": "BF",
    "name": "Burkina Faso"
  },
  {
    "id": "BG",
    "name": "Bulgaria"
  },
  {
    "id": "BH",
    "name": "Bahrain"
  },
  {
    "id": "BI",
    "name": "Burundi"
  },
  {
    "id": "BJ",
    "name": "Benin"
  },
  {
    "id": "BM",
    "name": "Bermuda"
  },
  {
    "id": "BN",
    "name": "Brunei Darussalam"
  },
  {
    "id": "BO",
    "name": "Bolivia"
  },
  {
    "id": "BR",
    "name": "Brazil"
  },
  {
    "id": "BS",
    "name": "Bahamas"
  },
  {
    "id": "BT",
    "name": "Bhutan"
  },
  {
    "id": "BV",
    "name": "Bouvet Island"
  },
  {
    "id": "BW",
    "name": "Botswana"
  },
  {
    "id": "BY",
    "name": "Belarus"
  },
  {
    "id": "BZ",
    "name": "Belize"
  },
  {
    "id": "CA",
    "name": "Canada"
  },
  {
    "id": "CC",
    "name": "Cocos (Keeling) Islands"
  },
  {
    "id": "CF",
    "name": "Central African Republic"
  },
  {
    "id": "CG",
    "name": "Congo"
  },
  {
    "id": "CH",
    "name": "Switzerland"
  },
  {
    "id": "CI",
    "name": "Ivory Coast"
  },
  {
    "id": "CK",
    "name": "Cook Islands"
  },
  {
    "id": "CL",
    "name": "Chile"
  },
  {
    "id": "CM",
    "name": "Cameroon"
  },
  {
    "id": "CN",
    "name": "China"
  },
  {
    "id": "CO",
    "name": "Colombia"
  },
  {
    "id": "CR",
    "name": "Costa Rica"
  },
  {
    "id": "CU",
    "name": "Cuba"
  },
  {
    "id": "CV",
    "name": "Cape Verde"
  },
  {
    "id": "CX",
    "name": "Christmas Island"
  },
  {
    "id": "CY",
    "name": "Cyprus"
  },
  {
    "id": "CZ",
    "name": "Czech Republic"
  },
  {
    "id": "DE",
    "name": "Germany"
  },
  {
    "id": "DJ",
    "name": "Djibouti"
  },
  {
    "id": "DK",
    "name": "Denmark"
  },
  {
    "id": "DM",
    "name": "Dominica"
  },
  {
    "id": "DO",
    "name": "Dominican Republic"
  },
  {
    "id": "DZ",
    "name": "Algeria"
  },
  {
    "id": "EC",
    "name": "Ecuador"
  },
  {
    "id": "EE",
    "name": "Estonia"
  },
  {
    "id": "EG",
    "name": "Egypt"
  },
  {
    "id": "EH",
    "name": "Western Sahara"
  },
  {
    "id": "ER",
    "name": "Eritrea"
  },
  {
    "id": "ES",
    "name": "Spain"
  },
  {
    "id": "ET",
    "name": "Ethiopia"
  },
  {
    "id": "FI",
    "name": "Finland"
  },
  {
    "id": "FJ",
    "name": "Fiji"
  },
  {
    "id": "FK",
    "name": "Falkland Islands (Malvinas)"
  },
  {
    "id": "FM",
    "name": "Micronesia, Federated States of"
  },
  {
    "id": "FO",
    "name": "Faroe Islands"
  },
  {
    "id": "FR",
    "name": "France"
  },
  {
    "id": "GA",
    "name": "Gabon"
  },
  {
    "id": "GB",
    "name": "United Kingdom"
  },
  {
    "id": "GD",
    "name": "Grenada"
  },
  {
    "id": "GE",
    "name": "Georgia"
  },
  {
    "id": "GF",
    "name": "French Guiana"
  },
  {
    "id": "GH",
    "name": "Ghana"
  },
  {
    "id": "GI",
    "name": "Gibraltar"
  },
  {
    "id": "GL",
    "name": "Greenland"
  },
  {
    "id": "GM",
    "name": "Gambia"
  },
  {
    "id": "GN",
    "name": "Guinea"
  },
  {
    "id": "GP",
    "name": "Guadeloupe"
  },
  {
    "id": "GQ",
    "name": "Equatorial Guinea"
  },
  {
    "id": "GR",
    "name": "Greece"
  },
  {
    "id": "GS",
    "name": "South Georgia South Sandwich Islands"
  },
  {
    "id": "GT",
    "name": "Guatemala"
  },
  {
    "id": "GU",
    "name": "Guam"
  },
  {
    "id": "GW",
    "name": "Guinea-Bissau"
  },
  {
    "id": "GY",
    "name": "Guyana"
  },
  {
    "id": "HK",
    "name": "Hong Kong"
  },
  {
    "id": "HM",
    "name": "Heard and Mc Donald Islands"
  },
  {
    "id": "HN",
    "name": "Honduras"
  },
  {
    "id": "HR",
    "name": "Croatia (Hrvatska)"
  },
  {
    "id": "HT",
    "name": "Haiti"
  },
  {
    "id": "HU",
    "name": "Hungary"
  },
  {
    "id": "ID",
    "name": "Indonesia"
  },
  {
    "id": "IE",
    "name": "Ireland"
  },
  {
    "id": "IL",
    "name": "Israel"
  },
  {
    "id": "IM",
    "name": "Isle of Man"
  },
  {
    "id": "IN",
    "name": "India"
  },
  {
    "id": "IO",
    "name": "British Indian Ocean Territory"
  },
  {
    "id": "IQ",
    "name": "Iraq"
  },
  {
    "id": "IR",
    "name": "Iran (Islamic Republic of)"
  },
  {
    "id": "IS",
    "name": "Iceland"
  },
  {
    "id": "IT",
    "name": "Italy"
  },
  {
    "id": "JE",
    "name": "Jersey"
  },
  {
    "id": "JM",
    "name": "Jamaica"
  },
  {
    "id": "JO",
    "name": "Jordan"
  },
  {
    "id": "JP",
    "name": "Japan"
  },
  {
    "id": "KE",
    "name": "Kenya"
  },
  {
    "id": "KG",
    "name": "Kyrgyzstan"
  },
  {
    "id": "KH",
    "name": "Cambodia"
  },
  {
    "id": "KI",
    "name": "Kiribati"
  },
  {
    "id": "KM",
    "name": "Comoros"
  },
  {
    "id": "KN",
    "name": "Saint Kitts and Nevis"
  },
  {
    "id": "KP",
    "name": "Korea, Democratic People's Republic of"
  },
  {
    "id": "KR",
    "name": "Korea, Republic of"
  },
  {
    "id": "KW",
    "name": "Kuwait"
  },
  {
    "id": "KY",
    "name": "Cayman Islands"
  },
  {
    "id": "KZ",
    "name": "Kazakhstan"
  },
  {
    "id": "LA",
    "name": "Lao People's Democratic Republic"
  },
  {
    "id": "LB",
    "name": "Lebanon"
  },
  {
    "id": "LC",
    "name": "Saint Lucia"
  },
  {
    "id": "LI",
    "name": "Liechtenstein"
  },
  {
    "id": "LK",
    "name": "Sri Lanka"
  },
  {
    "id": "LR",
    "name": "Liberia"
  },
  {
    "id": "LS",
    "name": "Lesotho"
  },
  {
    "id": "LT",
    "name": "Lithuania"
  },
  {
    "id": "LU",
    "name": "Luxembourg"
  },
  {
    "id": "LV",
    "name": "Latvia"
  },
  {
    "id": "LY",
    "name": "Libyan Arab Jamahiriya"
  },
  {
    "id": "MA",
    "name": "Morocco"
  },
  {
    "id": "MC",
    "name": "Monaco"
  },
  {
    "id": "MD",
    "name": "Moldova, Republic of"
  },
  {
    "id": "ME",
    "name": "Montenegro"
  },
  {
    "id": "MG",
    "name": "Madagascar"
  },
  {
    "id": "MH",
    "name": "Marshall Islands"
  },
  {
    "id": "MK",
    "name": "Macedonia"
  },
  {
    "id": "ML",
    "name": "Mali"
  },
  {
    "id": "MM",
    "name": "Myanmar"
  },
  {
    "id": "MN",
    "name": "Mongolia"
  },
  {
    "id": "MO",
    "name": "Macau"
  },
  {
    "id": "MP",
    "name": "Northern Mariana Islands"
  },
  {
    "id": "MQ",
    "name": "Martinique"
  },
  {
    "id": "MR",
    "name": "Mauritania"
  },
  {
    "id": "MS",
    "name": "Montserrat"
  },
  {
    "id": "MT",
    "name": "Malta"
  },
  {
    "id": "MU",
    "name": "Mauritius"
  },
  {
    "id": "MV",
    "name": "Maldives"
  },
  {
    "id": "MW",
    "name": "Malawi"
  },
  {
    "id": "MX",
    "name": "Mexico"
  },
  {
    "id": "MY",
    "name": "Malaysia"
  },
  {
    "id": "MZ",
    "name": "Mozambique"
  },
  {
    "id": "NA",
    "name": "Namibia"
  },
  {
    "id": "NC",
    "name": "New Caledonia"
  },
  {
    "id": "NE",
    "name": "Niger"
  },
  {
    "id": "NF",
    "name": "Norfolk Island"
  },
  {
    "id": "NG",
    "name": "Nigeria"
  },
  {
    "id": "NI",
    "name": "Nicaragua"
  },
  {
    "id": "NL",
    "name": "Netherlands"
  },
  {
    "id": "NO",
    "name": "Norway"
  },
  {
    "id": "NP",
    "name": "Nepal"
  },
  {
    "id": "NR",
    "name": "Nauru"
  },
  {
    "id": "NU",
    "name": "Niue"
  },
  {
    "id": "NZ",
    "name": "New Zealand"
  },
  {
    "id": "OM",
    "name": "Oman"
  },
  {
    "id": "PA",
    "name": "Panama"
  },
  {
    "id": "PE",
    "name": "Peru"
  },
  {
    "id": "PF",
    "name": "French Polynesia"
  },
  {
    "id": "PG",
    "name": "Papua New Guinea"
  },
  {
    "id": "PH",
    "name": "Philippines"
  },
  {
    "id": "PK",
    "name": "Pakistan"
  },
  {
    "id": "PL",
    "name": "Poland"
  },
  {
    "id": "PM",
    "name": "St. Pierre and Miquelon"
  },
  {
    "id": "PN",
    "name": "Pitcairn"
  },
  {
    "id": "PR",
    "name": "Puerto Rico"
  },
  {
    "id": "PS",
    "name": "Palestine"
  },
  {
    "id": "PT",
    "name": "Portugal"
  },
  {
    "id": "PW",
    "name": "Palau"
  },
  {
    "id": "PY",
    "name": "Paraguay"
  },
  {
    "id": "QA",
    "name": "Qatar"
  },
  {
    "id": "RE",
    "name": "Reunion"
  },
  {
    "id": "RO",
    "name": "Romania"
  },
  {
    "id": "RS",
    "name": "Serbia"
  },
  {
    "id": "RU",
    "name": "Russian Federation"
  },
  {
    "id": "RW",
    "name": "Rwanda"
  },
  {
    "id": "SA",
    "name": "Saudi Arabia"
  },
  {
    "id": "SB",
    "name": "Solomon Islands"
  },
  {
    "id": "SC",
    "name": "Seychelles"
  },
  {
    "id": "SD",
    "name": "Sudan"
  },
  {
    "id": "SE",
    "name": "Sweden"
  },
  {
    "id": "SG",
    "name": "Singapore"
  },
  {
    "id": "SH",
    "name": "St. Helena"
  },
  {
    "id": "SI",
    "name": "Slovenia"
  },
  {
    "id": "SJ",
    "name": "Svalbard and Jan Mayen Islands"
  },
  {
    "id": "SK",
    "name": "Slovakia"
  },
  {
    "id": "SL",
    "name": "Sierra Leone"
  },
  {
    "id": "SM",
    "name": "San Marino"
  },
  {
    "id": "SN",
    "name": "Senegal"
  },
  {
    "id": "SO",
    "name": "Somalia"
  },
  {
    "id": "SR",
    "name": "Suriname"
  },
  {
    "id": "ST",
    "name": "Sao Tome and Principe"
  },
  {
    "id": "SV",
    "name": "El Salvador"
  },
  {
    "id": "SY",
    "name": "Syrian Arab Republic"
  },
  {
    "id": "SZ",
    "name": "Swaziland"
  },
  {
    "id": "TC",
    "name": "Turks and Caicos Islands"
  },
  {
    "id": "TD",
    "name": "Chad"
  },
  {
    "id": "TF",
    "name": "French Southern Territories"
  },
  {
    "id": "TG",
    "name": "Togo"
  },
  {
    "id": "TH",
    "name": "Thailand"
  },
  {
    "id": "TJ",
    "name": "Tajikistan"
  },
  {
    "id": "TK",
    "name": "Tokelau"
  },
  {
    "id": "TM",
    "name": "Turkmenistan"
  },
  {
    "id": "TN",
    "name": "Tunisia"
  },
  {
    "id": "TO",
    "name": "Tonga"
  },
  {
    "id": "TP",
    "name": "East Timor"
  },
  {
    "id": "TR",
    "name": "Turkey"
  },
  {
    "id": "TT",
    "name": "Trinidad and Tobago"
  },
  {
    "id": "TV",
    "name": "Tuvalu"
  },
  {
    "id": "TW",
    "name": "Taiwan"
  },
  {
    "id": "TZ",
    "name": "Tanzania, United Republic of"
  },
  {
    "id": "UA",
    "name": "Ukraine"
  },
  {
    "id": "UG",
    "name": "Uganda"
  },
  {
    "id": "UM",
    "name": "United States minor outlying islands"
  },
  {
    "id": "US",
    "name": "United States"
  },
  {
    "id": "UY",
    "name": "Uruguay"
  },
  {
    "id": "UZ",
    "name": "Uzbekistan"
  },
  {
    "id": "VA",
    "name": "Vatican City State"
  },
  {
    "id": "VC",
    "name": "Saint Vincent and the Grenadines"
  },
  {
    "id": "VE",
    "name": "Venezuela"
  },
  {
    "id": "VG",
    "name": "Virgin Islands (British)"
  },
  {
    "id": "VI",
    "name": "Virgin Islands (U.S.)"
  },
  {
    "id": "VN",
    "name": "Vietnam"
  },
  {
    "id": "VU",
    "name": "Vanuatu"
  },
  {
    "id": "WF",
    "name": "Wallis and Futuna Islands"
  },
  {
    "id": "WS",
    "name": "Samoa"
  },
  {
    "id": "XK",
    "name": "Kosovo"
  },
  {
    "id": "YE",
    "name": "Yemen"
  },
  {
    "id": "ZA",
    "name": "South Africa"
  },
  {
    "id": "ZM",
    "name": "Zambia"
  },
  {
    "id": "ZW",
    "name": "Zimbabwe"
  }
]

This endpoint retrieves all countries.

HTTP Request

GET https://pinpoll.com/v1/countries

Account

Retrieve account information

curl -X GET -H "Authorization: user_token"  "https://pinpoll.com/v1/account"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/account');
$request->setMethod(HTTP_METH_GET);


$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "user_group_id": 1,
  "username": "",
  "email": "test@pinpoll.com",
  "image": null,
  "firstname": null,
  "lastname": null,
  "company": null,
  "vatid": null,
  "gender": "unspecified",
  "useowndomain": false,
  "language": "en",
  "timezone": null,
  "location": null,
  "street": null,
  "postal_code": null,
  "city": null,
  "country": null,
  "description": null,
  "deactivated": 0,
  "created_at": "2016-10-12 12:45:18",
  "updated_at": "2016-10-12 12:45:18",
  "stripe_id": null,
  "card_brand": null,
  "card_last_four": null,
  "trial_ends_at": null,
  "app_id": 1,
  "is_poweruser": false,
  "subscription": null,
  "domains": [
    {
      "id": 74,
      "title": "http://Test.com",
      "created_at": "2016-10-12 12:45:18",
      "updated_at": "2016-10-12 12:45:18",
      "deleted_at": null
    }
  ],
  "permissions": [],
  "group": {
    "id": 1,
    "title": "Free",
    "created_at": "2015-09-04 07:52:42",
    "updated_at": "2015-09-04 07:55:37",
    "permissions": [
      {
        "title": "EDIT.NONCOMMERCIAL.ONLY"
      }
    ]
  }
}

This endpoint retrieves account information.

HTTP Request

GET https://pinpoll.com/v1/account

Update account information

curl -X PUT -H "Authorization: user_token" -d '{
  "updateprofile":"1",
  "email":"johanna@pinpoll.com",
  "gender":"female",
  "language":"de",
  "timezone":"Europe/Vienna",
  "company":"my_company",
  "vatid":"my_vat_id",
  "firstname":"Tester",
  "lastname":"Testname",
  "street":"Teststreet 1",
  "postal_code":"45534",
  "city":"Linz",
  "country":"AT"
}' "https://pinpoll.com/v1/account"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/account');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

$request->setBody('{
  "updateprofile":"1",
    "email":"johanna@pinpoll.com",
    "gender":"female",
    "language":"de",
    "timezone":"Europe/Vienna",
    "company":"my_company",
  "vatid":"my_vat_id",
    "firstname":"Tester",
    "lastname":"Testname",
    "street":"Teststreet 1",
    "postal_code":"45534",
    "city":"Linz",
    "country":"AT"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "user_group_id": 6,
  "username": "Johanna",
  "email": "johanna@pinpoll.com",
  "image": "c74d97b01eae257e44aa9d5bade97baf.jpg",
  "firstname": "Tester",
  "lastname": "Testname",
  "company": "my_company",
  "vatid": null,
  "gender": "female",
  "useowndomain": false,
  "language": "de",
  "timezone": "Europe/Vienna",
  "location": null,
  "street": "Teststreet 1",
  "postal_code": "45534",
  "city": "Linz",
  "country": "AT",
  "description": null,
  "deactivated": 0,
  "created_at": "2016-07-22 12:32:41",
  "updated_at": "2016-10-13 09:16:07",
  "stripe_id": "cus_9A6X35C5vbwkM2",
  "card_brand": null,
  "card_last_four": null,
  "trial_ends_at": "2016-10-09 12:33:11",
  "app_id": 1,
  "is_poweruser": false,
  "subscription": {
    "id": 2,
    "user_id": 109,
    "name": "main",
    "stripe_id": "sub_9A6gmzN8WVZORo",
    "stripe_plan": "Free",
    "quantity": 1,
    "trial_ends_at": null,
    "ends_at": null,
    "created_at": "2016-09-09 12:42:39",
    "updated_at": "2016-09-09 12:42:39",
    "poweruser_goals": 0
  },
  "group": {
    "id": 6,
    "title": "Premium",
    "created_at": "2016-07-25 12:17:00",
    "updated_at": "2016-07-25 12:17:00",
    "permissions": [
      {
        "title": "USE.RECAPTCHA"
      },
      {
        "title": "USE.OWN.DOMAIN"
      },
      {
        "title": "VIEW.ADVANCED.STATS"
      },
      {
        "title": "USE.POLL.TIMERANGE"
      }
    ]
  }
}

This endpoint updates an account.

HTTP Request

PUT https://pinpoll.com/v1/account

JSON Body Parameters

Parameter Values Mandatory Description
updateprofile int x 1 indicates that this is an update
email string User's email address
gender string One of {male, female, unspecified}
image string Base64 encoded profile image
deleteimg int 1 indicates that the image linked to this account shall be removed
language string User's preferred language
timezone string User's timezone
company string Company this account belongs to
firstname string The user's first name
lastname string The user's last name
street string Street part of user's address
postal_code string Postal code part of user's address
city string City part of user's address
country string Country code part of user's address, e.g.: GB, AT, DE. See Countries

Update account cockpit password

curl -X PUT -H "Authorization: user_token" -d '{
  "oldpassword":"my_old_password",
  "password":"my_new_password"
}' "https://pinpoll.com/v1/account"
<?php

$request = new HttpRequest();
$request->setUrl('https://pinpoll.com/v1/account');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'authorization' => 'Bearer user_token'
));

$request->setBody('{
  "oldpassword":"my_old_password",
  "password":"my_new_password"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

The above command returns JSON structured like this:

{
  "user_group_id": 6,
  "username": "Johanna",
  "email": "johanna@pinpoll.com",
  "image": "c74d97b01eae257e44aa9d5bade97baf.jpg",
  "firstname": "Tester",
  "lastname": "Testname",
  "company": "my_company",
  "vatid": null,
  "gender": "female",
  "useowndomain": false,
  "language": "de",
  "timezone": "Europe/Vienna",
  "location": null,
  "street": "Teststreet 1",
  "postal_code": "45534",
  "city": "Linz",
  "country": "AT",
  "description": null,
  "deactivated": 0,
  "created_at": "2016-07-22 12:32:41",
  "updated_at": "2016-10-13 09:16:07",
  "stripe_id": "cus_9A6X35C5vbwkM2",
  "card_brand": null,
  "card_last_four": null,
  "trial_ends_at": "2016-10-09 12:33:11",
  "app_id": 1,
  "is_poweruser": false,
  "subscription": {
    "id": 2,
    "user_id": 109,
    "name": "main",
    "stripe_id": "sub_9A6gmzN8WVZORo",
    "stripe_plan": "Free",
    "quantity": 1,
    "trial_ends_at": null,
    "ends_at": null,
    "created_at": "2016-09-09 12:42:39",
    "updated_at": "2016-09-09 12:42:39",
    "poweruser_goals": 0
  },
  "group": {
    "id": 6,
    "title": "Premium",
    "created_at": "2016-07-25 12:17:00",
    "updated_at": "2016-07-25 12:17:00",
    "permissions": [
      {
        "title": "USE.RECAPTCHA"
      },
      {
        "title": "USE.OWN.DOMAIN"
      },
      {
        "title": "VIEW.ADVANCED.STATS"
      },
      {
        "title": "USE.POLL.TIMERANGE"
      }
    ]
  }
}

This endpoint updates the cockpit password for an account.

HTTP Request

PUT https://pinpoll.com/v1/account

JSON Body Parameters

Parameter Values Mandatory Description
oldpasssword string x Old Password
password string x New password

Errors

The Pinpoll API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized
403 Forbidden -- You are not allowed to access this resource
404 Not Found
405 Method Not Allowed
406 Not Acceptable -- You requested a format that isn't json
410 Gone
429 Too Many Requests
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.