Get All Live Surveys

Retrieve a list of all live surveys based on filtering criteria.

Note: The rows parameter accepts a maximum value of 500 surveys per page. The fields loi and ir are deprecated. Please use length_of_interview and incidence_rate instead.

Endpoint

POST /surveys

Headers

{
  "publisher-authentication-key": "your_project_secret_key"
}

Note: The publisher-authentication-key header corresponds to your Secret Key. The authorizationKey in the request body corresponds to your Web API Key.

Request Body

{
  "authorizationKey": "DqcInvhIFAl5WtUNwihFUIgUH77EL2hTNRU",
  "country": "US",
  "language": "English",
  "lengthOfInterviewGTE": 1,
  "lengthOfInterviewLTE": 5,
  "collectPII": false,
  "rows": 50,
  "page": 1,
  "CPIGTE": 1,
  "CPILTE": 5,
  "surveyGroupExists": false,
  "incidenceRateGTE": 1,
  "incidenceRateLTE": 25
}

Response

{
  "success": true,
  "surveys": [
    {
      "_id": "691af562a929b3a5a2232679",
      "cost_per_interview": {
        "value": 1.07,
        "currency_code": "USD"
      },
      "surveyNumber": 17633744316785364,
      "survey_number": 17633744316785364,
      "length_of_interview": 10,
      "incidence_rate": 10,
      "cpi": 1.07,
      "country": "United States of America",
      "countryCode": "US",
      "country_code": "US",
      "required_completes": 13,
      "overall_completes": 0,
      "revenue_per_click": 0,
      "survey_created_date": "2025-11-17T10:24:10.829Z",
      "survey_last_updated_date": "2025-11-17T10:24:10.829Z"
    },
    {
      "_id": "691af51da929b31134b52678",
      "cost_per_interview": {
        "value": 1.28,
        "currency_code": "USD"
      },
      "surveyNumber": 17633743620135364,
      "survey_number": 17633743620135364,
      "length_of_interview": 35,
      "incidence_rate": 20,
      "cpi": 1.28,
      "country": "United States of America",
      "countryCode": "US",
      "country_code": "US",
      "required_completes": 49,
      "overall_completes": 0,
      "revenue_per_click": 0,
      "survey_created_date": "2025-11-17T10:24:10.829Z",
      "survey_last_updated_date": "2025-11-17T10:24:10.829Z"
    },
    {
      "_id": "691af51da92923453sb52677",
      "cost_per_interview": {
        "value": 1.28,
        "currency_code": "USD"
      },
      "surveyNumber": 17633743615055360,
      "survey_number": 17633743615055360,
      "length_of_interview": 35,
      "incidence_rate": 20,
      "cpi": 1.28,
      "country": "United States of America",
      "countryCode": "US",
      "country_code": "US",
      "required_completes": 50,
      "overall_completes": 0,
      "revenue_per_click": 0,
      "survey_created_date": "2025-11-17T10:24:10.829Z",
      "survey_last_updated_date": "2025-11-17T10:24:10.829Z"
    }
  ],
  "surveysCount": 3,
  "pagination": {
    "totalDocuments": 26654,
    "rows": 3,
    "page": 1,
    "totalPages": 8885
  },
  "projectName": "New Campaign 007",
  "projectNumber": 10000092,
  "organisation": "Mirats Quanto DIY"
}

Error Response

{
  "message": "internal server error",
  "code": 500,
  "success": false
}

Authorizations

publisher-authentication-key

string

header

required

Send your Secret Key using the publisher-authentication-key header. This header is required for every request.

Body

application/json

Payload for retrieving live surveys. Includes your Web API Key plus optional filtering criteria.

authorizationKey

string

required

Web API Key (maps to authorizationKey field in SDK).

Example:

"DqcInvhIFAl5WtUNwihFUIgUH77EL2hTNRU"

country

string

required

ISO 2-letter country code (e.g., US, IN).

Example:

"US"

language

string

Language name for survey targeting.

Example:

"English"

lengthOfInterviewGTE

integer

Minimum length of interview in minutes.

Example:

1

lengthOfInterviewLTE

integer

Maximum length of interview in minutes.

Example:

5

collectPII

boolean

Only return surveys that collect personally identifiable information.

Example:

false

rows

integer

Number of surveys to return per page (1-500).

Required range: 1 <= x <= 500

Example:

50

page

integer

Page number for pagination (starts from 1).

Required range: x >= 1

Example:

1

CPIGTE

number<float>

Minimum CPI value.

Example:

1

CPILTE

number<float>

Maximum CPI value.

Example:

5

surveyGroupExists

boolean

Filter by whether a survey group exists.

Example:

false

incidenceRateGTE

integer

Minimum incidence rate.

Example:

1

incidenceRateLTE

integer

Maximum incidence rate.

Example:

25

Response

Successful response with list of live surveys

success

boolean

required

Example:

true

surveys

object[]

required

Show child attributes

surveys._id

string

required

Example:

"691af562a929b3a5a2232679"

surveys.surveyNumber

integer

required

Example:

17633744316785364

surveys.length_of_interview

integer

required

Length of interview in minutes

Example:

10

surveys.incidence_rate

integer

required

Incidence rate as a percentage

Example:

10

surveys.cpi

number<float>

required

Example:

1.28

surveys.countryCode

string

required

Example:

"US"

surveys.cost_per_interview

object

Show child attributes

surveys.cost_per_interview.value

number<float>

required

Example:

1.07

surveys.cost_per_interview.currency_code

string

required

Example:

"USD"

surveys.survey_number

integer

Example:

17633744316785364

surveys.loi

integer

deprecated

Deprecated: Use 'length_of_interview' instead. This field will be removed in a future version.

Example:

10

surveys.ir

integer

deprecated

Deprecated: Use 'incidence_rate' instead. This field will be removed in a future version.

Example:

10

surveys.country

string

Example:

"United States of America"

surveys.country_code

string

Example:

"US"

surveys.required_completes

integer

Example:

13

surveys.overall_completes

integer

Example:

0

surveys.revenue_per_click

number<float>

Example:

0

surveys.survey_created_date

string<date-time>

ISO 8601 date-time when the survey was created

Example:

"2025-11-17T10:24:10.829Z"

surveys.survey_last_updated_date

string<date-time>

ISO 8601 date-time when the survey was last updated

Example:

"2025-11-17T10:24:10.829Z"

surveysCount

integer

required

Number of surveys returned in this response

Example:

3

pagination

object

Show child attributes

pagination.totalDocuments

integer

Example:

26654

pagination.rows

integer

Example:

3

pagination.page

integer

Example:

1

pagination.totalPages

integer

Example:

8885

projectName

string

Example:

"New Campaign 007"

projectNumber

integer

Example:

10000092

organisation

string

Example:

"Mirats Quanto DIY"

API Documentation

Endpoint Examples

Get All Live Surveys