Our newest API documentation can now be accessed here. This version will no longer be updated as of November 2025.
\nhttps://docs.repdata.com/demand
\nReliable, repeatable data collection. Leverage the Research Desk Demand API to create and manage projects, surveys, and responses.
\nThe 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.
\nProduction URL: https://demand.researchdesk.com
Integration Staging URL: https://stage-demand.researchdesk.com
All endpoints return JSON-encoded responses and standard HTTP status codes. Error messages are designed to be displayed to end users.
\nError response examples:
\nResponse (400):
\n{\n \"message\": \"Survey name is required.\"\n}\n\nResponse (404):
\n{\n \"message\": \"Survey could not be found.\"\n}\n\nResponse (405):
\n{\n \"message\": \"Survey objects cannot be deleted.\"\n}\n\nResponse (500):
\n{\n \"message\": \"Our server experienced an unexpected error.\"\n}\n\nStep 1: Determining Authentication Flow
\nExternal End-User Authentication
\nInternal-User Authentication & SSO
\nServer-to-Server Authentication
\nStep 2: Mapping Attributes & Concepts
\nCountries, Languages, and Other Definitions
\nRespondent Qualifications
\nStep 3: Creating & Updating Projects
\nStep 4: Managing Surveys
\nConstructing Entry Links
\nImplementing Redirect Links
\nCreating Surveys
\nSoft & Full Survey Launching
\nAnalyzing & Updating Surveys In-Field
\nClosing Surveys
\nStep 5: Managing Respondents
\nValidating Survey Responses
\nReconciling Survey Responses
\nThe 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.
\nPrior 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.
\nAlthough 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.
\nWhen 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.
\nFor 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.
\nIf 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.
\nCredentials 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.
\nFor applications which have existing country, language, or qualification concepts, an initial mapping exercise must be performed and mapped relationships stored.
\nIntegrations 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.
\nWith 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.
\nIn 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:
\nAGE
\nGENDER
\nZIP
\nETHNICITY
\nSTANDARD_HHI
\nSTANDARD_EDUCATION
\nSTANDARD_EMPLOYMENT
\nSTANDARD_INDUSTRY_PERSONAL
\nSTANDARD_JOB_TITLE
\nSTANDARD_NO_OF_EMPLOYEES
\nSTANDARD_INDUSTRY
\nSTANDARD_COMPANY_REVENUE
\nSTANDARD_COMPANY_DEPARTMENT
\nSTANDARD_HOMEOWNER
\nProjects 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.
\nWhen 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.
\nProjects may be updated using the available PATCH functionality; there is no functional effect on surveys when updating a project.
\nSurveys represent available survey opportunities for which a respondent may attempt to complete.
\nThe 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.
\nWhen 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.
\nAdditional 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:
\nvariableName=[%QUALIFICATION_NAME%]
\nwhere “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:
\n\nThe above example could result in the following generated entry link for a specific respondent entering your survey:
\n\nwhere the qualification values represent the ID of the qualification option as detailed in the Qualification endpoint.
\nIt 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.
\nAfter 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:
\nComplete: 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.
\nStandard 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.
\nQuality 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
\nSecurity Termination: this redirect signals that the respondent is suspected of cheating or other unacceptable behavior. Implementation is encouraged but not required.
\nOverquota Termination: this redirect signals that the respondent was attributed to a quota which has since been met. Implementation is encouraged but not required.
\nA 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.
\nQuotas 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.
\nIt 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.
\nIf 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.
\nOnce 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.
\nThe 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.
\nOnce 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.
\nThe 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.
\nGiven 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.
\nIf 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.
\nRate limit: 5 requests/hour, per email address
\nEmail and password combinations are required to generate tokens which are used for authorizing subsequent API calls. Tokens are accepted for 12 hours after generation; it is suggested to store the token in a cookie governed by timestamp logic, although it is acceptable to attempt API actions to determine token validity and re-authenticate as necessary. The token is passed as Authorization in the header for all subsequent calls.
Email addresses are unique and must be associated with an active user object.
\n","auth":{"type":"apikey","apikey":{"value":"","key":"Rate limit: 10 requests/second
\nRate limit: 10 requests/second
\nRate limit: 10 requests/second
\nRate limit: 10 requests/second
\nRate limit: 10 requests/second
\nNote: The GET method returns a list of objects, POST and PATCH accept and return a single object
Rate limit: 10 requests/second
\nNote: The GET method returns a list of objects, POST and PATCH accept and return a single object
Used for reconciliation.
\nRate limit: 6000 requests/minute
\nNote: The GET method returns a list of objects, PATCH accepts and returns a single object