Pollable API Docs

Audience Model

Create an Audience

This method allows for the creation of a new polling audience. Creation of the audience requires a POST request formatted in the following way with the correct representation specified. You must be authenticated to use all methods associated with audience API.

POST /audience HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer "eyCJhYCQ...

Request Body:

{
  "name": "test_survey",
  "completes": 3,
  "url": "https://my.survey.com?survey_id=1234",
  "filters": {
    "age": [11, 12, 13, 14, 15]
  },
  "quotas": {
    "gender": { "male": 22 }
  }
}

Response:

{
  "id": 7,
  "object": "audience",
  "name": "test_survey",
  "active": false,
  "status": 11,
  "limit": 3,
  "url": "https://my.survey.com?survey_id=1234",
  "quotas": {
    "data": [
      {
        "id": 1,
        "object": "quota",
        "name": "gender",
        "quota": 22,
        "condition": "male"
      }
    ],
    "links": {
      "collection": "/audience"
    },
    "object": "list"
  },
  "filters": {
    "data": [
      {
        "id": 3,
        "object": "filter",
        "name": "age",
        "values": ["11", "12", "13", "14", "15"]
      }
    ],
    "links": {
      "collection": "/audience"
    },
    "object": "list"
  },
  "links": {
    "self": "/audience/7"
  }
}

Query Parameters

The following request parameters can be used to construct the audience of your choosing.

Request Attribute Type Description Required
name String The name of the created polling survey. Yes
completes Integer The number of completes required for survey project. Yes
url String The url to send audience respondents. Yes
length_of_interview Integer Estimated time of survey in minutes. No
incidence_rate Integer Estimated incidence for survey. No
polling_time Integer Estimated fielding time for survey poll. No
filters List[Filter] Filters to prevent unwanted audience respondents. No
quotas List[Quota] Quotas for specific categories of audience respondents. No

Audience Filters

Filters are objects that specify the allowed categories of survey respondents. The general construction is as follows:

{
  "age": [21, 22, 23, 24, 25]
}

For all filters the key represents the demographic category of the filter and the array that follows is the allowed values of that category. In this is example only respondents age 21-25 will be allowed in the survey.

Audience Quotas

Quotas are objects specified in audience creation that prevent too many respondents of a certain category. The general construction of a quota is as follows:

{
  "gender": { "male": 22 }
}

Here the key references an audience demographic category while the value represents a case of this category. The corresponding number then gives the quota amount. In this example pollable will stop sending respondents to the url after 22 men have entered the survey.

Getting an already created Audience

As part of the audience workflow you will want to retrieve the audience object to monitor the results of a poll. To do so the following request is used.

GET /audience/7 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer "eyCJhYCQ...

Response:

{
  "id": 7,
  "object": "audience",
  "name": "test_survey",
  "active": false,
  "status": 11,
  "limit": 3,
  "url": "https://my.survey.com?survey_id=1234",
  "quotas": {
    "data": [
      {
        "id": 1,
        "object": "quota",
        "name": "gender",
        "quota": 22,
        "condition": "male"
      }
    ],
    "links": {
      "collection": "/audience"
    },
    "object": "list"
  },
  "filters": {
    "data": [
      {
        "id": 3,
        "object": "filter",
        "name": "age",
        "values": ["11", "12", "13", "14", "15"]
      }
    ],
    "links": {
      "collection": "/audience"
    },
    "object": "list"
  },
  "links": {
    "self": "/audience/7"
  }
}

Updating an already created Audience

To update an audience, the request is similar to that of audience creation except for the id of audience is passed in as a path variable.

PUT /audience HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer "eyCJhYCQ...

Request Body:

{
  "name": "test_survey",
  "completes": 100
}

Response:

{
  "id": 7,
  "object": "audience",
  "name": "test_survey",
  "completes_current": 22,
  "active": false,
  "status": 11,
  "limit": 100,
  "url": "https://my.survey.com?survey_id=1234",
  "quotas": {
    "data": [
      {
        "id": 1,
        "object": "quota",
        "name": "gender",
        "quota": 22,
        "condition": "male"
      }
    ],
    "links": {
      "collection": "/audience"
    },
    "object": "list"
  },
  "filters": {
    "data": [
      {
        "id": 3,
        "object": "filter",
        "name": "age",
        "values": ["11", "12", "13", "14", "15"]
      }
    ],
    "links": {
      "collection": "/audience"
    },
    "object": "list"
  },
  "links": {
    "self": "/audience/7"
  }
}

Registering Completes

Once an audience respondent successfully completes the poll in the url they needed to be counted as complete in order to not affect the poll's incidence and length of interview. The respondent id will be passed as a query parameter in the url of the provided poll link. This id will be used to register the respondent on the backend. To do this, the following request is used.

POST /audience/completes HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer "eyCJhYCQ...

Request Body:

{
  "response_id": "test_id"
}

Response:

{
  "response_id": "test_id",
  "status": "recorded"
}

The status parameter indicates a successful registration of the survey respondent.

Registration Query Parameters

The following request parameters can be used to construct the audience of your choosing.

Request Attribute Type Description Required
response_id String ID for the survey respondent. Yes

← Response Model →