> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Surveys
Rate limit: 10 requests/second
Note: The `GET` method returns a list of objects, `POST` and `PATCH` accept and return a single object
##### Query String Parameters (GET)
| Name | Description | Required | Example |
| ------------- | ------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------ |
| `ids` | Comma delimited value of the Survey IDs being retreived | No | `?ids=1,2,3` |
| `project_ids` | Comma delimited value of the Project IDs associated with the Surveys being retrieved. | No | `?project_ids=1,2,3` |
| `statuses` | Comma delimited value of the statuses associated with the Surveys being retrieved. | No | `?statuses=live,complete` |
| `fields` | Dictates structure of the response. | No | `?fields=id,project_id,status` |
| `page` | Integer value of the page being retrieved | No; if omitted, the value defaults to `1`. | `?page=2` |
| `page_size` | Integer value dictating the number of objects returned per page. | No; if omitted, the value defaults to `50`. | `?page_size=100` |
##### Survey Object Definition
| Parameter | Required for `POST` | Required for `PATCH` | Description |
| ---------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | System Assigned | Yes | The ID of the Survey object. |
| `project_id` | Yes | No | The ID of the associated Project object. |
| `name` | Yes | No | The name of the Survey; there is no uniqueness constraint. |
| `status` | No | No | The status of the Survey. Allowable values:
- Draft
- Live
- Paused
- Complete |
| `respondents` | Yes | No | Target (N) of respondents desired for the Survey.
This number can represent Completes or Survey Starts depending on value used in the "calculation\_type" field. |
| `country_code` | Yes | No | The country in which respondents are being fielded. |
| `language_code` | Yes | No | The language of the survey. |
| `length_of_interview` | Yes | No | The estimated time, in minutes, required to complete the survey. |
| `incidence_rate` | Yes | No | The estimated rate of which respondents will qualify for the survey, based on termination points in the survey. |
| `collects_pii` | Yes | No | Boolean indicating if the survey collects personally-identifiable information. |
| `hashing_enabled` | Yes | No | Boolean indicating if hashing validation on the complete redirection is enabled. Research Desk supports SHA-256 and SHA-512 hashing algorithms. [Supporting documentation here](https://www.notion.so/repdata/Redirect-Hashing-Guide-4cfedc2b08fb4f82b912ef9606d6924e). |
| `out_of_field_date` | Yes | No | Target out of field date for the Survey. |
| `out_of_field_timezone` | Yes | No | User's timezone. List of values can be found in /definitions/ lookup. |
| `device_compatibilities` | Yes | No | List containing respondent device types allowed to engage with Survey.
Allowed values:
- desktop
- mobile
- tablet |
| `calculation_type` | Yes | No | Defines the calculation method for counting respondents. Allowed values:
- Completes (quotas are evaluated based on number of respondents who successfully completed client survey)
- Survey Starts (quotas are evaluated based on number of respondent who entered client survey) |
| `traffic_control_limit_type` | Yes | No | Traffic control setting which controls the pace at which data collection is paced out on an hourly cadence.
Allowable values:
- None: 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.
Note that this setting simply limits the max number of Responses that can be collected per hour from the moment the Survey goes live through to the designated out\_of\_field\_date. This setting does not guarantee that a min number of completes is collected per hour. |
| `entry_link` | Yes | No | The survey entry link to which respondents will be redirected. |
| `quota_id` | System Assigned | Yes, only if, `respondent_attributes` is present.
Note: If `respondent_attributes` is present, any quota object that is missing from the list will be removed from the survey. | ID assigned to a quota. |
| `quota_name` | Yes | No | Name used to represent a quota. |
| `quota` | Yes | No | The number of respondents, meeting the associated qualification criteria, required to complete the survey. |
| `survey_starts` | System Assigned | No | The number of respondents that qualified for this quota that have started the survey. |
| `survey_completes` | System Assigned | No | The number of respondents that qualified for this quota that have completed the survey. |
| `qualifications` | Yes | No | The questions which will be asked of the respondent prior to being redirected to the survey, and the associated allowed answer options. Qualifications are used for targeting and screening respondents. |
| `question_id` | Yes | No | Quesiton ID being used to target/screen the respondent. |
| `allowed_option_ids` | Yes | No | Array of question IDs that qualify the respondent and make up a desired quota. |
| `redirects` | System Assigned | No | The URLs to which respondents must be redirected upon the survey session ending. |
| `minimum_price_per_complete` | System Assigned | No | The recommended price floor for the survey, based on the stated length of interview and incidence rate. |
| `offered_price_per_complete` | No | No | The price charged per completed survey session, based on the length of interview and incidence rate.
This offer price can be increased using the PATCH /surveys/ endpoint to incentivise respondents and drive more traffic. A price increase may be required for more complex studies with advanced targeting applied. |
| `field_details` | System Assigned | No | High-level survey fielding statistics. |
## OpenAPI
````yaml GET /surveys
openapi: 3.0.3
info:
title: Research Desk Demand API v1.1
version: 1.0.0
description: >-
Reliable, repeatable data collection. Leverage the Research Desk Demand API
to create and manage projects, surveys, and responses.
The Research Desk Demand API is a RESTful service structured by
object-oriented endpoints, utilizing standard HTTP response codes and verbs.
Detailed filtering is supported via query string parameters. Cross-account,
user-based authorization enables focused access control and permissioning.
## Environments
Production URL: `https://demand.researchdesk.com`
Integration Staging URL: `https://stage-demand.researchdesk.com`
## Responses
All endpoints return JSON-encoded responses and standard HTTP status codes.
Error messages are designed to be displayed to end users.
Error response examples:
Response (400):
``` json
{
"message": "Survey name is required."
}
```
Response (404):
``` json
{
"message": "Survey could not be found."
}
```
Response (405):
``` json
{
"message": "Survey objects cannot be deleted."
}
```
Response (500):
``` json
{
"message": "Our server experienced an unexpected error."
}
```
# Integration Guide
- Step 1: Determining Authentication Flow
- External End-User Authentication
- Internal-User Authentication & SSO
- Server-to-Server Authentication
- Step 2: Mapping Attributes & Concepts
- Countries, Languages, and Other Definitions
- Respondent Qualifications
- Step 3: Creating & Updating Projects
- Step 4: Managing Surveys
- Constructing Entry Links
- Implementing Redirect Links
- Creating Surveys
- Soft & Full Survey Launching
- Analyzing & Updating Surveys In-Field
- Closing Surveys
- Step 5: Managing Respondents
- Validating Survey Responses
- Reconciling Survey Responses
## Step 1: Determining Authentication Flow
The Research Desk Demand API leverages email-password combinations to
authenticate API access, and utilizes JSON Web Tokens (JWT) to authorize
each API call. This authorization standard enables developers to build fully
secure applications, easily manage access, and provide better experiences
for end users.
Prior to implementing authentication and authorization, please read the
following sections to determine the workflow which best fits your needs.
Hybrid workflows are common, such as a user-facing application passing
authentication credentials from a browser while storing a set of credentials
server-side to authenticate API calls powering a recurring job.
### External End-User Authentication
Although rare, there are cases in which integrations directly leverage the
Research Desk Demand API authentication and authorization system to manage
external end users. In this case, the external user’s email address and
password should be passed directly from the browser to the Research Desk
Demand API. Once authenticated, the returned token should be stored in a
browser cookie, along with the given expiration. When a user action warrants
an API call, the expiration stored in the cookie should be validated and the
token is directly passed into the authorization header of the API call. If
the expiration has passed, the user should be prompted to re-enter their
email address and password, creating a new token which can then overwrite
the previously stored token.
When an end user wishes to terminate their session, the token value and
timestamp stored in the browser cookie should be destroyed; there is no API
action necessary.
### Internal User Authentication
For applications which are exposed to users within your company, single
sign-on (SSO) integrations are highly recommended. The Research Desk Demand
API supports Security Assertion Markup Language (SAML) based single sign-on
authentication and authorization. This method of authentication enables
companies to manage user access to the API using their consolidated system
of choice, and prevents credential exposure. To obtain certificates and
additional information, please contact your Rep Data account manager.
If your company does not leverage SSO, internal users’ browser sessions can
be authenticated and authorized in the same method as the recommended
external end-user workflow detailed above. Internal users may also leverage
their email address and password combinations to authenticate via non-custom
applications such as Postman.
### Server-to-Server Authentication
Credentials can be created, stored, and leveraged on the back-end of any
application. It is highly recommended to create separate credentials for
disparate categories of functionality, such as one set of credentials used
as a proxy for end-user activity and a separate set used to authorize API
calls necessary for a recurring job or alerting system. Once a token is
generated using a set of credentials, the expiration should be stored and
validated prior to executing any API calls.
## Step 2: Mapping Attributes & Concepts
For applications which have existing country, language, or qualification
concepts, an initial mapping exercise must be performed and mapped
relationships stored.
Integrations which solely leverage the Research Desk concepts and
attributes, most typically stateless front-end applications which expose all
available parameter values directly to users, do not require mapping.
### Countries, Languages, and Other Definitions
With a single, customizable Definitions endpoint, the Research Desk Demand
API exposes all available parameter values necessary to create and
manipulate projects, surveys, and responses. It is recommended to maintain a
mapping database table storing Research Desk value associations with all
applicable objects or definitions within your application. It is recommended
to call the Definitions endpoint at least monthly, identify any available
parameter values for which there is no stored mapping, and update your
mapping table accordingly.
### Respondent Qualifications
In order to create and launch a survey, respondent qualifications must be
defined. The Qualifications endpoint exposes all available qualifications,
and a monthly assessment and mapping exercise is recommended. The following
qualifications are recommended to be initially mapped:
- AGE
- GENDER
- ZIP
- ETHNICITY
- STANDARD_HHI
- STANDARD_EDUCATION
- STANDARD_EMPLOYMENT
- STANDARD_INDUSTRY_PERSONAL
- STANDARD_JOB_TITLE
- STANDARD_NO_OF_EMPLOYEES
- STANDARD_INDUSTRY
- STANDARD_COMPANY_REVENUE
- STANDARD_COMPANY_DEPARTMENT
- STANDARD_HOMEOWNER
## Step 3: Creating & Updating Projects
Projects represent a collection of surveys and denote which user is
responsible for the management of the project. In order to support an
organized user experience and a performant integration, it is recommended to
replicate the project structure within your application.
When creating a project, a project manager must be assigned. The calling
user may assign any user as the project manager, provided the calling user
can view the user ID as returned by the User endpoint. If the calling user
is associated with multiple Research Desk accounts, the account ID must be
specified and consistent with the user ID when creating a project.
Projects may be updated using the available PATCH functionality; there is no
functional effect on surveys when updating a project.
## Step 4: Managing Surveys
Surveys represent available survey opportunities for which a respondent may
attempt to complete.
### Constructing Entry Links
The first step in creating a survey is to construct the link to which a
respondent will be redirected when entering your survey. Typically this is a
direct link to the survey platform (Qualtrics, Alchemy, Decipher, etc) but
may also be defined as any solution your company may be using.
When defining a respondent entry link, the Response ID must always be
appended to the query string and serves as a session identifier. The
variable for Response ID is “\[%RID%\]” and can be placed anywhere within
the query string. This variable value must be captured within the survey and
returned when redirecting the respondent back to the Research Desk system.
Additional respondent qualifications and session data can also be passed via
the entry link query string. All qualifications returned by the
Qualifications endpoint can be appended to the entry link using the
following format:
variableName=\[%QUALIFICATION_NAME%\]
where “variableName” can be customized, and “QUALIFICATION_NAME” is the name
of the qualification as returned by the Qualifications endpoint. For
example, the following URL represents an entry link which would redirect a
respondent to a Qualtrics survey with age, gender, and ethnicity appended:
%5B%5B%5B%5B[https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%5B%25RID%25%5D%26respondent_age%3D%5B%25AGE%25%5D%26respondent_gender%3D%5B%25GENDER%25%5D%26respondent_ethnicity%3D%5B%25ETHNICITY%25%5D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%5D%5D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255C%255D%5D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255B%25RID%25%255D%26respondent_age%3D%255B%25AGE%25%255D%26respondent_gender%3D%255B%25GENDER%25%255D%26respondent_ethnicity%3D%255B%25ETHNICITY%25%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255D%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255C%255D%5D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255B%25RID%25%255D%26respondent_age%3D%255B%25AGE%25%255D%26respondent_gender%3D%255B%25GENDER%25%255D%26respondent_ethnicity%3D%255B%25ETHNICITY%25%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255D%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255C%255D%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255B%25RID%25%255D%26respondent_age%3D%255B%25AGE%25%255D%26respondent_gender%3D%255B%25GENDER%25%255D%26respondent_ethnicity%3D%255B%25ETHNICITY%25%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255D%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C%255D(https%3A%2F%2Fqualtrics.com%2Fsurvey%2F123%3FresponseID%3D%255C%255B%25RID%25%255C%255D%26respondent_age%3D%255C%255B%25AGE%25%255C%255D%26respondent_gender%3D%255C%255B%25GENDER%25%255C%255D%26respondent_ethnicity%3D%255C%255B%25ETHNICITY%25%255C)%255C%255D](https://qualtrics.com/survey/123?responseID=%5B%RID%%5D&respondent_age=%5B%AGE%%5D&respondent_gender=%5B%GENDER%%5D&respondent_ethnicity=%5B%ETHNICITY%%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5D%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5C%5D%5D(https://qualtrics.com/survey/123?responseID=%5B%RID%%5D&respondent_age=%5B%AGE%%5D&respondent_gender=%5B%GENDER%%5D&respondent_ethnicity=%5B%ETHNICITY%%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5D%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5C%5D%5D(https://qualtrics.com/survey/123?responseID=%5B%RID%%5D&respondent_age=%5B%AGE%%5D&respondent_gender=%5B%GENDER%%5D&respondent_ethnicity=%5B%ETHNICITY%%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5D%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5C%5D%5D(https://qualtrics.com/survey/123?responseID=%5B%RID%%5D&respondent_age=%5B%AGE%%5D&respondent_gender=%5B%GENDER%%5D&respondent_ethnicity=%5B%ETHNICITY%%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5D%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C%5D(https://qualtrics.com/survey/123?responseID=%5C%5B%RID%%5C%5D&respondent_age=%5C%5B%AGE%%5C%5D&respondent_gender=%5C%5B%GENDER%%5C%5D&respondent_ethnicity=%5C%5B%ETHNICITY%%5C)%5C%5D))))
The above example could result in the following generated entry link for a
specific respondent entering your survey:
[https://qualtrics.com/survey/123?responseID=xxx-yyy-zzz&respondentAge=1&respondentGender=2&respondentEthnicity=7](https://qualtrics.com/survey/123?responseID=xxx-yyy-zzz&respondentAge=1&respondentGender=2&respondentEthnicity=7)
where the qualification values represent the ID of the qualification option
as detailed in the Qualification endpoint.
It is highly recommended to append all qualifications to the respondent
entry link which are being used as targeting criteria for the survey. In
order to optimize the respondent experience, and therefore respondent
conversion, it is highly recommended to forgo asking respondents to answer
similar qualifications questions within the survey, and instead utilize the
values passed in the entry link.
### Implementing Redirect Links
After creating a survey using the Surveys endpoint, respondent redirects
will be generated by the Research Desk Demand API and returned in the
response body. These links serve as the destination for the respondent after
the survey session has ended, and represent the following session statuses:
**Complete:** when a respondent is redirected back to the Research Desk
platform using the Complete URL, the respondent session will be stored as
having successfully completed the survey and thus costs will be incurred.
This redirect is required to be implemented.
**Standard Termination:** when redirected using the Standard Termination
URL, the respondent session will be stored as terminated for generic
reasons. This redirect is required to be implemented.
**Quality Termination:** this redirect signals that the respondent is of
poor quality and helps Research Desk panels provide higher quality
respondents moving forward. Although implementation is encouraged, this
redirect is not required. SAME AS SECURITY
**Security Termination:** this redirect signals that the respondent is
suspected of cheating or other unacceptable behavior. Implementation is
encouraged but not required.
**Overquota Termination:** this redirect signals that the respondent was
attributed to a quota which has since been met. Implementation is encouraged
but not required.
### Creating Surveys
A number of parameters are required when creating a survey, and constrained
parameter options are returned by the Definitions endpoint. For surveys
being created as a result of user action, it is encouraged to create the
survey in a non-live state and present the user with a final verification of
the survey details before defining a status of Live.
Quotas must be defined when creating a survey, and are constructed using the
available qualifications as returned by the Qualifications endpoint.
Respondents which meet all of the qualification criteria will be counted
toward the defined quota upon completion of the survey. Please note that it
is possible to create combinations of qualifications which prevent
respondents from entering your survey, such as requiring a respondent to be
unemployed while having a job title.
## Soft & Full Launching
It is highly encouraged to implement a standard soft launch mechanism to
your survey creation workflow. Soft launches typically consist of setting
the survey to Live with quotas defined as 10% of the desired quotas. It is
encouraged to poll the API every 10 minutes to compare respondent entries
and completed sessions with those reported by the survey platform.
Additionally, it is encouraged to analyze quota attribution during the soft
launch.
If problems are identified at any time during the soft launch, the survey
may be updated to a non-live status using the available PATCH method to
prevent respondents from entering during the troubleshooting process.
Once the survey is determined to be properly functioning by automated or
manually processes, the PATCH method can be used to update the survey quotas
to the full number of respondents desired.
### Analyzing and Updating Surveys In-Field
The Research Desk Demand API represents half of a marketplace, with the
other half being integrated panels which match their respondent to your
survey opportunities. In an effort to ensure positive respondent
experiences, panels make matching decisions based on a balance of survey
length, incidence rate, required qualifications, and compensation being
offered. It is encouraged to poll the API every 10 minutes to monitor the
number of respondents entering your survey and determine if entry frequency
meets expectations. If not, and the cause is reasonably determined to be a
function of compensation being offered to respondents, it is encouraged to
increase the compensation in increments of $0.25.
### Closing Surveys
Once a survey has completed fielding, it is encouraged to update the survey
status to “Complete” using the available PATCH method for the Surveys
endpoint. After data analysis, insufficient survey responses can be
reconciled using the available PATCH method for the Responses endpoint; if
required, the survey quotas may be increased and the survey can be set back
to Live in an effort to obtain additional responses.
## Step 5: Managing Respondents
The Surveys endpoint exposes general fielding statistics including the
number of survey entrants, terminations, and completed sessions. The
Responses endpoint exposes the session statuses per respondent, as well as
enables response management.
### Validating Survey Responses
Given a survey ID, the Responses endpoint details all survey responses
processed by the Research Desk system based on respondent redirects. After a
survey has been fielded, it is highly encouraged to call the API for all
registered survey responses and compare by ID to the survey responses
collected within the survey platform.
### Reconciling Survey Responses
If survey responses which were initially registered as completed sessions
are determined to be of poor quality or fraudulent, responses can be
reconciled by utilizing the PATCH method available for the Responses
endpoint to change the session status.
# API Reference
servers:
- url: https://demand.researchdesk.com
description: Production
- url: https://stage-demand.researchdesk.com
description: Staging
security:
- AuthToken: []
paths:
/surveys:
get:
summary: Surveys
operationId: Surveys_Surveys
parameters:
- name: ids
in: query
required: false
description: Comma-delimited list of Survey IDs to retrieve.
schema:
type: string
example: 1,2,3
- name: project_ids
in: query
required: false
description: Comma-delimited list of Project IDs to filter surveys by.
schema:
type: string
example: 1,2,3
- name: statuses
in: query
required: false
description: Comma-delimited list of survey statuses to filter by.
schema:
type: string
example: Live,Complete
- name: fields
in: query
required: false
description: Comma-delimited list of field names to include in the response.
schema:
type: string
example: id,name,status
- name: page
in: query
required: false
description: Page number to retrieve. Defaults to 1.
schema:
type: integer
example: 1
- name: page_size
in: query
required: false
description: Number of results per page. Defaults to 50.
schema:
type: integer
example: 50
responses:
'200':
description: Surveys
content:
application/json:
schema:
type: object
properties:
total_surveys:
type: integer
page:
type: integer
page_size:
type: integer
surveys:
type: array
items:
type: object
properties:
id:
type: string
project_id:
type: string
name:
type: string
status:
type: string
survey_attributes:
type: object
properties:
respondents:
type: integer
country_code:
type: string
language_code:
type: string
length_of_interview:
type: integer
incidence_rate:
type: integer
minimum_price_per_complete:
type: number
offered_price_per_complete:
type: number
device_compatibilities:
type: array
items:
type: string
collects_pii:
type: boolean
hashing_enabled:
type: boolean
calculation_type:
type: string
traffic_control_limit_type:
type: string
out_of_field_date:
type: string
out_of_field_timezone:
type: string
entry_link:
type: string
redirects:
type: object
properties:
complete:
type: string
standard_termination:
type: string
quality_termination:
type: string
security_termination:
type: string
overquota_termination_term:
type: string
respondent_attributes:
type: array
items:
type: object
properties:
quota_id:
type: string
quota_name:
type: string
quota:
type: integer
survey_starts:
type: integer
survey_completes:
type: integer
qualifications:
type: array
items:
type: object
properties:
question_id:
type: integer
allowed_option_ids:
type: array
items:
type: string
field_details:
type: object
properties:
entrants:
type: integer
standard_terminates:
type: integer
quality_terminates:
type: integer
overquota_terminates:
type: integer
completes:
type: integer
length_of_interview:
type: string
nullable: true
incidence_rate:
type: string
nullable: true
cost:
type: integer
example:
total_surveys: 1
page: 1
page_size: 50
surveys:
- id: a038a197-c849-47c8-9c6d-9fe7b497601f
project_id: 78f7fc48-3e66-4b10-ae8f-e6566aa62642
name: 5G Network Decisions
status: Draft
survey_attributes:
respondents: 2000
country_code: US
language_code: EN
length_of_interview: 5
incidence_rate: 80
minimum_price_per_complete: 1.07
offered_price_per_complete: 1.07
device_compatibilities:
- Desktop
collects_pii: false
hashing_enabled: false
calculation_type: Completes
traffic_control_limit_type: None
out_of_field_date: '2024-05-21 06:00:00'
out_of_field_timezone: (UTC-10:00) Hawaii
entry_link: >-
https://repdata.decipherinc.com/survey/selfserve/53b/220106?list=2&rdud=[%RDUD]
redirects:
complete: >-
https://www-staging.rdsecured.com/return?inbound_code=1000?rdud=[%RDUD]
standard_termination: >-
https://www-staging.rdsecured.com/return?inbound_code=2000?rdud=[%RDUD]
quality_termination: >-
https://www-staging.rdsecured.com/return?inbound_code=1?rdud=[%RDUD]
security_termination: >-
https://www-staging.rdsecured.com/return?inbound_code=3000?rdud=[%RDUD]
overquota_termination_term: >-
https://www-staging.rdsecured.com/return?inbound_code=4000?rdud=[%RDUD]
respondent_attributes:
- quota_id: '1'
quota_name: 30-32
quota: 100
survey_starts: 10
survey_completes: 8
qualifications:
- question_id: 1
allowed_option_ids:
- '30'
- '31'
- '32'
- quota_id: '2'
quota_name: Nested Age 33-35 Domestic Air Travelers
quota: 100
survey_starts: 0
survey_completes: 0
qualifications:
- question_id: 1
allowed_option_ids:
- '33'
- '34'
- '35'
- question_id: 2
allowed_option_ids:
- 1
field_details:
entrants: 0
inflight: 0
abandons: 0
standard_terminates: 0
quality_terminates: 0
overquota_terminates: 0
defender_terminates: 0
completes: 0
accepted_completes: 0
accepted_unregistered_completes: 0
rejected_completes: 0
length_of_interview: null
incidence_rate: null
cost: 0
accepted_cost: 0
accepted_unregistered_cost: 0
rejected_cost: 0
final_cost: 0
final_completes: 0
components:
securitySchemes:
AuthToken:
type: apiKey
in: header
name: Authorization
description: >-
Authentication token to be sent directly in the Authorization header (no
'' prefix).
````