> ## 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. # Update Project 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) | Parameter | Description | Required | Example | | --------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------- | | `ids` | Comma delimited value of the Project IDs being retreived. | No | `?ids=1,2,3` | | `project_manager_ids` | Comma delimited value of the Project Manager (User) IDs associated with the Projects being retreived. | No | `?project_manager_ids=1,2,3` | | `page` | Integer value of the page being retrieved | No; if omitted, the value defaults to `0`. | `?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` | ##### Project Object Definition | Parameter | Required for `POST` | Required for `PATCH` | Description | | -------------------- | ------------------- | -------------------- | ------------------------------------------------------------------------- | | `id` | System Assigned | Yes | The ID of the Project object. | | `account_id` | Yes | No | The ID of the associated Account object. | | `project_manager_id` | Yes | No | The ID of the associated Project Manager (User) object. | | `project_name` | Yes | No | The name of the Project; there is no uniqueness constraint. | | `project_number` | Yes | No | Client project identifier; nonfunctional. | | `session_exclusions` | No | No | List of Project IDs of which sessions will not be allowed in the Project. | ## OpenAPI ````yaml PATCH /projects 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: /projects: patch: summary: Projects operationId: Projects_Projects parameters: [] requestBody: required: true content: application/json: schema: type: object properties: id: type: integer account_id: type: integer project_manager_id: type: integer name: type: string project_number: type: string session_exclusions: type: array items: type: integer business_unit: type: string format: uuid description: >- Business unit identifier (send the token value directly; not prefixed). example: id: c9cf2545-9474-436e-933c-f6dc2cf8a39b account_id: fcb8f022-87fa-42c4-b08a-816a8de9758c project_manager_id: 44b83408-5091-70ae-5cea-b8045195294d name: 5G Network Adoption and Purchasing Decisions project_number: 5G-001 session_exclusions: - 2 - 3 - 4 business_unit: 27daf638-e54c-4e20-a279-c55bccb6a58d responses: '200': description: Projects content: application/json: schema: type: object properties: id: type: integer account_id: type: integer project_manager_id: type: integer project_name: type: string project_number: type: string session_exclusions: type: array items: type: integer example: id: c9cf2545-9474-436e-933c-f6dc2cf8a39b account_id: fcb8f022-87fa-42c4-b08a-816a8de9758c project_manager_id: 44b83408-5091-70ae-5cea-b8045195294d project_name: 5G Network Adoption and Purchasing Decisions project_number: 5G-001 session_exclusions: - 2 - 3 - 4 business_unit: 27daf638-e54c-4e20-a279-c55bccb6a58d components: securitySchemes: AuthToken: type: apiKey in: header name: Authorization description: >- Authentication token to be sent directly in the Authorization header (no '' prefix). ````