> ## 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. # Definitions Rate limit: 10 requests/second ##### Query String Parameters | Parameter | Description | Required | Example | | -------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------- | | `fields` | Comma delimited value of definition keys, dictating the structure of the response. | No; if omitted, all parameters will be returned | `?fields=survey_attributes` | | `survey_attributes` | Comma 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_attributes` | Comma 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_attributes` | Comma 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 | Parameter | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `countries` | The countries supported for sampling, including available language options. | | `time_zones` | The timezones that are supported. | | `calculation_types` | `Survey Starts`: Quotas are measured and calculated on entrants into the Survey URL.
`Completes`: Quotas are measured and calculated on survey completes. | | `traffic_control_limits` | `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. | | `device_compatibilities` | `Desktop`: 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. | | `statuses` | `Draft`: 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 | Parameter | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `statuses` | `Qualified`: 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_statuses` | `Accepted`: 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 | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `categories` | The category describing the qualification. | | `types` | `Single 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. | ## OpenAPI ````yaml GET /definitions 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: /definitions: get: summary: Definitions operationId: Lookups_Definitions parameters: [] responses: '200': description: Definitions content: application/json: schema: type: object properties: survey_attributes: type: object properties: countries: type: array items: type: object properties: name: type: string code: type: string language_options: type: array items: type: object properties: name: type: string code: type: string time_zones: type: array items: type: string calculation_types: type: array items: type: string traffic_control_limits: type: array items: type: string device_compatibilities: type: array items: type: string statuses: type: array items: type: string response_attributes: type: object properties: statuses: type: array items: type: string reconciliation_statuses: type: array items: type: string qualification_attributes: type: object properties: categories: type: array items: type: string types: type: array items: type: string example: 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 components: securitySchemes: AuthToken: type: apiKey in: header name: Authorization description: >- Authentication token to be sent directly in the Authorization header (no '' prefix). ````