Update Survey

Surveys

curl --request PATCH \
  --url https://demand.researchdesk.com/surveys \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "status": "<string>",
  "completes_wanted": 123,
  "cpi": 123,
  "length_of_interview": 123
}'

{
  "survey": {
    "id": "a038a197-c849-47c8-9c6d-9fe7b497601f",
    "project_id": "78f7fc48-3e66-4b10-ae8f-e6566aa62642",
    "name": "5G Network Adoption and Purchasing Decisions v2",
    "status": "Draft",
    "survey_attributes": {
      "respondents": 2000,
      "country_code": "US",
      "language_code": "EN",
      "length_of_interview": 5,
      "incidence_rate": 90,
      "out_of_field_date": "2026-05-20 06:00:00",
      "out_of_field_timezone": "(UTC-06:00) Easter Island",
      "minimum_price_per_complete": 1.55,
      "offered_price_per_complete": 1.55,
      "collects_pii": true,
      "hashing_enabled": false,
      "device_compatibilities": [
        "Desktop"
      ],
      "calculation_type": "Completes",
      "traffic_control_limit_type": "None",
      "entry_link": "https://repdata.decipherinc.com/survey/selfserve/53b/220106?list=2&rid=[%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": "8f0cb8ab-c87b-4fd1-9b02-9c61f0c8a26d",
        "quota_name": "30-35",
        "quota": 200,
        "survey_starts": 0,
        "survey_completes": 0,
        "qualifications": [
          {
            "question_id": 1,
            "allowed_option_ids": [
              "30",
              "31",
              "32",
              "33",
              "34",
              "35"
            ]
          }
        ]
      }
    ]
  }
}

PATCH

surveys

Surveys

curl --request PATCH \
  --url https://demand.researchdesk.com/surveys \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "status": "<string>",
  "completes_wanted": 123,
  "cpi": 123,
  "length_of_interview": 123
}'

{
  "survey": {
    "id": "a038a197-c849-47c8-9c6d-9fe7b497601f",
    "project_id": "78f7fc48-3e66-4b10-ae8f-e6566aa62642",
    "name": "5G Network Adoption and Purchasing Decisions v2",
    "status": "Draft",
    "survey_attributes": {
      "respondents": 2000,
      "country_code": "US",
      "language_code": "EN",
      "length_of_interview": 5,
      "incidence_rate": 90,
      "out_of_field_date": "2026-05-20 06:00:00",
      "out_of_field_timezone": "(UTC-06:00) Easter Island",
      "minimum_price_per_complete": 1.55,
      "offered_price_per_complete": 1.55,
      "collects_pii": true,
      "hashing_enabled": false,
      "device_compatibilities": [
        "Desktop"
      ],
      "calculation_type": "Completes",
      "traffic_control_limit_type": "None",
      "entry_link": "https://repdata.decipherinc.com/survey/selfserve/53b/220106?list=2&rid=[%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": "8f0cb8ab-c87b-4fd1-9b02-9c61f0c8a26d",
        "quota_name": "30-35",
        "quota": 200,
        "survey_starts": 0,
        "survey_completes": 0,
        "qualifications": [
          {
            "question_id": 1,
            "allowed_option_ids": [
              "30",
              "31",
              "32",
              "33",
              "34",
              "35"
            ]
          }
        ]
      }
    ]
  }
}

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.
`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.

Authorizations

Authorization

string

header

required

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

Headers

Authorization

string

Body

application/json

Update survey fields. Supply any fields you wish to update.

name

string

status

string

completes_wanted

integer

cpi

number

length_of_interview

integer

Response

200 - application/json

Surveys

survey

object

Show child attributes

Create Survey Responses

⌘I

Overview

Integration Guide

Account Management

Lookups

Projects

Surveys

Responses

Query String Parameters (GET)

Survey Object Definition

Authorizations

Headers

Body

Response