Skip to main content
GET
/
definitions
Definitions
curl --request GET \
  --url https://demand.researchdesk.com/definitions \
  --header 'Authorization: <api-key>'
{
  "survey_attributes": {
    "countries": [
      {
        "name": "Argentina",
        "code": "AR",
        "language_options": [
          {
            "name": "English",
            "code": "EN"
          },
          {
            "name": "Spanish",
            "code": "ES"
          }
        ]
      },
      {
        "name": "Australia",
        "code": "AU",
        "language_options": [
          {
            "name": "English",
            "code": "EN"
          }
        ]
      },
      {
        "name": "Chile",
        "code": "CL",
        "language_options": [
          {
            "name": "English",
            "code": "EN"
          },
          {
            "name": "Spanish",
            "code": "ES"
          }
        ]
      },
      {
        "name": "Norway",
        "code": "NO",
        "language_options": [
          {
            "name": "Norwegian",
            "code": "NO"
          }
        ]
      }
    ],
    "time_zones": [
      "(UTC+09:30) Darwin",
      "(UTC+13:00) Samoa",
      "(UTC+03:00) Moscow, St. Petersburg",
      "(UTC+10:00) Guam, Port Moresby",
      "(UTC+07:00) Tomsk",
      "(UTC+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius",
      "(UTC+10:30) Lord Howe Island",
      "(UTC-05:00) Bogota, Lima, Quito, Rio Branco",
      "(UTC+01:00) West Central Africa",
      "(UTC-09:00) Coordinated Universal Time-09",
      "(UTC+08:00) Taipei",
      "(UTC+09:00) Seoul",
      "(UTC+02:00) Damascus",
      "(UTC+03:00) Istanbul",
      "(UTC+10:00) Brisbane",
      "(UTC+05:30) Sri Jayawardenepura",
      "(UTC+04:00) Abu Dhabi, Muscat",
      "(UTC+04:00) Saratov"
    ],
    "calculation_types": [
      "Survey Starts",
      "Completes"
    ],
    "traffic_control_limits": [
      "Even Pacing",
      "None",
      "Accelerated Pacing"
    ],
    "device_compatibilities": [
      "Desktop",
      "Tablet",
      "Mobile"
    ],
    "statuses": [
      "Live",
      "Paused",
      "Complete",
      "Draft",
      "Cancelled"
    ]
  },
  "response_attributes": {
    "statuses": [
      "Qualified",
      "Complete",
      "Standard Termination",
      "Quality Termination",
      "Security Termination",
      "Overquota Termination"
    ],
    "reconciliation_statuses": [
      "Accepted",
      "Rejected",
      "Auto Accepted",
      "Unrecognized",
      "Unprocessed",
      "Past System Deadline"
    ]
  },
  "qualification_attributes": {
    "categories": [
      "B2B/Employment",
      "Demographics",
      "Children",
      "Health",
      "Household",
      "Interests",
      "Shopping",
      "Technology",
      "Travel",
      "Geography",
      "Automotive",
      "Politics",
      "Financial",
      "Food/Beverage",
      "Media",
      "Gaming/Electronics",
      "Smoking/Tobacco",
      "Other",
      "Custom Qualification",
      "Verified Sample"
    ],
    "types": [
      "Single Punch",
      "Multi Punch",
      "Numeric - Open End",
      "Text - Open End",
      "Derived",
      "Zip Code"
    ]
  }
}
Rate limit: 10 requests/second
Query String Parameters
ParameterDescriptionRequiredExample
fieldsComma delimited value of definition keys, dictating the structure of the response.No; if omitted, all parameters will be returned?fields=survey_attributes
survey_attributesComma delimited value of keys within the survey_attributes object, dictating the structure of the response.No; if omitted, all parameters will be returned?survey_attributes=statuses
response_attributesComma delimited value of keys within the response_attributes object, dictating the structure of the response.No; if omitted, all parameters will be returned?response_attributes=statuses
qualification_attributesComma delimited value of keys within the qualification_attributes object, dictating the structure of the response.No; if omitted, all parameters will be returned?qualification_attributes=categories
Survey Attributes Object Definition
ParameterDescription
countriesThe countries supported for sampling, including available language options.
time_zonesThe timezones that are supported.
calculation_typesSurvey Starts: Quotas are measured and calculated on entrants into the Survey URL.
Completes: Quotas are measured and calculated on survey completes.
traffic_control_limitsNone: No restriction to traffic generation.
Even Pacing: Max Responses across fielding timeline is near-linear with 1.1x Responses allowed per hourly increment.
Accelerated Pacing: Max Responses across fielding timeline is somewhat linear with 1.4x Responses allowed per hourly increment.
device_compatibilitiesDesktop: Indicates the survey accepts and supports respondents using desktop or laptop computers
Tablet: Indicates the survey accepts and supports respondents using mid-size screens typical of tablets
Mobile: Indicates the survey accepts and supports respondents using browsers or applications on their mobile device; fully responsive rendering is required.
statusesDraft: The default, non-functional status indicating the survey has been priced.
Live: A launched survey that is actively sourcing respondents and incurring costs.
Paused: A previously launched survey that has been paused and is no longer actively sourcing respondents.
Complete: A survey that has completed fielding.
Cancelled: A survey that has been cancelled by a user.
Response Attributes Object Definition
ParameterDescription
statusesQualified: The respondent qualified for the survey opportunity, was redirected to the live survey entry link, and has not ended the survey session.
Complete: The respondent has successfully completed the survey session.
Standard Termination: The survey session was terminated due to inability to meet a standard survey qualification criteria.
Quality Termination: The survey session was terminated due to a quality issue with the respondent.
Overquota Termination: The survey session was terminated due to the quota for the qualifying repsondent criteria having already been met.
reconciliation_statusesAccepted: A respondent that has been accepted by a user.
Rejected: A respondent that has been rejected by a user.
Auto Accepted: A respondent that has not been accepted or rejected by a user, but the window for rejecting it has past.
Unrecognized: A respondent that a user has tried to reconcile but does not exist or is associated with another survey.
Unprocessed: A respondent that has not been accepted or rejected, but could still be reconciled.
Past System Deadline: This status would be returned if a user tries to reconcile a respondent outside the reconciliation window.
Qualification Attributes Object Definition
ParameterDescription
categoriesThe category describing the qualification.
typesSingle Punch: The respondent is allowed to select a single answer option.
Multi-Punch: The respondent is allowed to select multiple answer options.
Numeric - Open End: The respondent is allowed to input any number.
Text - Open End: The respondent is allowed to input any text.
Derived: Value is derived from another answer choice collected for the respondent (e.g. State is derived from Zip Code).
Zip Code: Respondent’s zip/postal code. Zip/postal codes should be passed as an array. Postal codes should be limited to: first chars 5 for US, first 3 for UK, first 3 for Canada.

Authorizations

​
Authorization
string
header
required

Authentication token to be sent directly in the Authorization header (no '' prefix).

Headers

​
Authorization
string

Response

200 - application/json

Definitions

​
survey_attributes
object
​
response_attributes
object
​
qualification_attributes
object
⌘I