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 |