PATCH
/
v1
/
projects
/
{projectId}
Update a project
curl --request PATCH \
  --url https://api-staging.respondent.io/v1/projects/{projectId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-api-secret: <x-api-secret>' \
  --data '{
  "publicTitle": "<string>",
  "publicInternalName": "<string>",
  "publicDescription": "<string>",
  "targetMarketType": "b2c",
  "typeOfResearch": "inPerson",
  "targetResearchMethodology": "oneOnOne",
  "unmoderatedStudyOrSurvey": {
    "remoteCommunicationDetails": "<string>",
    "specialInstructions": "<string>"
  },
  "participantTimeRequiredMinutes": 123,
  "incentiveAmount": 123,
  "targetNumberOfParticipants": 123,
  "targetCountry": "AX",
  "targetCountries": [
    "AX"
  ],
  "targetLocationRespondentInPerson": {
    "id": "<string>",
    "address1": "<string>",
    "zipcode": "<string>",
    "city": "<string>",
    "region": "<string>",
    "state": "<string>",
    "country": "AX",
    "formattedAddress": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "targetHouseholdIncome": [
    "<30000"
  ],
  "targetGenders": "male",
  "targetEducation": [
    "somehighschool"
  ],
  "targetEthnicities": [
    "americanindianalaskannative"
  ],
  "targetAgeGroups": [
    "18-20"
  ],
  "ndaType": "none",
  "ndaLink": "<string>",
  "automations": {
    "autopay": true,
    "autoinvite": true
  },
  "keyQualifiers": [
    "targetProjectTopics"
  ],
  "filterPastParticipation": {
    "hasNeverParticipated": true,
    "months": "-1",
    "since": "2023-11-07T05:31:56Z"
  },
  "targetCities": [
    {
      "location": {
        "googleId": "<string>",
        "region": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "AF",
        "zipcode": "<string>",
        "location": {
          "longitude": 123,
          "latitude": 123
        }
      }
    }
  ],
  "ndaDetails": {
    "ndaType": "none",
    "ndaLink": "<string>"
  },
  "externalResearcher": {
    "researcherId": "<string>",
    "researcherName": "<string>",
    "teamId": "<string>",
    "companyName": "<string>",
    "companyId": "<string>",
    "bookingUrl": "<string>"
  },
  "targetProjectTopics": [
    "<string>"
  ]
}'
{
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "publicTitle": "<string>",
  "publicInternalName": "<string>",
  "publicDescription": "<string>",
  "organizationId": "<string>",
  "teamId": "<string>",
  "projectStatus": "DRAFT",
  "projectRecruitingStatus": "RECRUITING",
  "targetMarketType": "b2b",
  "typeOfResearch": "inPerson",
  "targetResearchMethodology": "oneOnOne",
  "unmoderatedStudyOrSurvey": {
    "remoteCommunicationDetails": "<string>",
    "specialInstructions": "<string>"
  },
  "participantTimeRequiredMinutes": 123,
  "incentiveAmount": 123,
  "targetNumberOfParticipants": 123,
  "targetCountry": "AX",
  "targetCountries": [
    "AX"
  ],
  "targetCities": [
    {
      "location": {
        "id": "<string>",
        "googleId": "<string>",
        "region": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "AX",
        "zipcode": "<string>",
        "address1": "<string>",
        "formattedAddress": "<string>",
        "location": {
          "longitude": 123,
          "latitude": 123
        }
      }
    }
  ],
  "targetJobFunctions": [
    "accountingAuditing"
  ],
  "targetCompanySize": [
    "selfemployed"
  ],
  "targetLocationRespondentInPerson": {
    "id": "<string>",
    "address1": "<string>",
    "zipcode": "<string>",
    "city": "<string>",
    "region": "<string>",
    "state": "<string>",
    "country": "AX",
    "formattedAddress": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "targetHouseholdIncome": [
    "<30000"
  ],
  "targetGenders": "male",
  "targetEducation": [
    "somehighschool"
  ],
  "targetEthnicities": [
    "americanindianalaskannative"
  ],
  "targetAgeGroups": [
    "18-20"
  ],
  "screenerQuestions": [
    {
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "questionType": "radio",
      "uid": "<string>",
      "text": "<string>",
      "answers": [
        {
          "createdAt": "<string>",
          "updatedAt": "<string>",
          "uid": "<string>",
          "text": "<string>",
          "answerValue": 123,
          "goToQuestionUid": "<string>",
          "isOther": true,
          "id": "<string>"
        }
      ],
      "isRequired": true,
      "skipLogic": true,
      "includeOtherOption": true,
      "isEnd": true,
      "logic": {
        "answerUid": "<string>",
        "goToQuestionUid": "<string>",
        "skipLogicType": {
          "id": 1,
          "text": "Selected"
        },
        "multipleAnswers": [
          {
            "answer": "<string>",
            "logicType": {
              "id": 1,
              "text": "Selected"
            }
          }
        ],
        "multipleAnswersBoolType": {
          "id": 1,
          "text": "AND"
        }
      },
      "minValue": 123,
      "maxValue": 123,
      "step": 123,
      "order": 123,
      "warnings": [
        "<string>"
      ],
      "id": "<string>"
    }
  ],
  "inviteSurveyLink": "<string>",
  "closedDetails": {
    "closed": true,
    "closedMessage": "<string>",
    "closedOnDate": "2023-11-07T05:31:56Z",
    "closedByUserId": "<string>"
  },
  "closed": true,
  "closedMessage": "<string>",
  "closedOnDate": "2023-11-07T05:31:56Z",
  "closedByUserId": "<string>",
  "ndaDetails": {
    "ndaType": "none",
    "ndaLink": "<string>",
    "ndaFileUrl": "<string>"
  },
  "ndaType": "none",
  "ndaFileUrl": "<string>",
  "ndaLink": "<string>",
  "filterPastParticipation": {
    "hasNeverParticipated": true,
    "since": "2023-11-07T05:31:56Z",
    "months": "-1"
  },
  "externalResearcher": {
    "researcherId": "<string>",
    "researcherName": "<string>",
    "teamId": "<string>",
    "companyName": "<string>",
    "companyId": "<string>",
    "bookingUrl": "<string>"
  },
  "seniority": [
    "unpaid"
  ],
  "publishedAt": "2023-11-07T05:31:56Z",
  "automations": {
    "autopay": true,
    "autoinvite": true
  },
  "keyQualifiers": [
    "targetHouseholdIncome"
  ],
  "completionUrl": "<string>",
  "targetProfessionalIndustries": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "targetJobTitles": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "targetProjectTopics": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "targetAudienceSkills": [
    {
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "name": "<string>",
      "slug": "<string>",
      "validated": false,
      "type": "skill",
      "count": 0,
      "id": "<string>"
    }
  ],
  "id": "<string>"
}

Headers

​
x-api-key
string
required
​
x-api-secret
string
required

Path Parameters

​
projectId
string
required

Body

application/json
​
publicTitle
string

Project Title. This is visible to Respondents, do not mention any incentive amount as you may change it during your project.

​
publicInternalName
string

Internal Project Name. This is visible only to your organization. Character Limit: Min 3 and Max 50.

​
publicDescription
string

Project Details. This is visible to Respondents. Character Limit: Max 800.

​
targetMarketType
enum<string>
default:b2c

Audience type to be targeted for this project. Example values: Industry professionals (B2B) or General Population (B2C)

Available options:
b2c
​
typeOfResearch
enum<string>

Research type for this project, if it is in-person or remote

Available options:
inPerson,
remote
​
targetResearchMethodology
enum<string>

Kind of research to be conducted for this project. Details here. If typeOfResearch == inPerson → allowed values are: [oneOnOne, focusGroup, inRespondentHome, inRespondentOffice] If typeOfResearch == remote → allowed values are: [oneOnOne, focusGroup, unmoderatedStudy, survey, diaryStudy]

Available options:
oneOnOne,
focusGroup,
inRespondentHome,
inRespondentOffice,
unmoderatedStudy,
survey,
diaryStudy
​
unmoderatedStudyOrSurvey
object

For Unmoderated Studies and Surveys only.

​
participantTimeRequiredMinutes
number
​
incentiveAmount
number

Dollars ranging: Min 5 and Max 1000. Pro tip: Set your incentive at or above $2 per minute (B2C) or $3 per minute (B2B) to attract quality participants faster. More tips to pick the right incentive: https://help.respondent.io/en/articles/5471087-what-is-the-best-incentive-for-my-research-project

​
targetNumberOfParticipants
number

Number of Participants We will recruit up to 3 times your target number of qualified participants. Number Limit: Min 1 and Max 500.

​
targetCountry
enum<string>
Available options:
AX,
AL,
DZ,
AS,
AD,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BA,
BW,
BV,
BR,
VG,
IO,
BN,
BG,
BF,
BI,
CV,
CM,
CA,
KY,
CF,
TD,
CL,
CX,
CC,
CO,
KM,
CG,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
CI,
CD,
DK,
DJ,
DM,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
LA,
LV,
LB,
LR,
LY,
LI,
LT,
LU,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NU,
NF,
KP,
MK,
MP,
NO,
OM,
PW,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RO,
RW,
RE,
SH,
KN,
LC,
PM,
VC,
WS,
SM,
ST,
SA,
RS,
SC,
SL,
SG,
SK,
SI,
SB,
SO,
ZA,
GS,
KR,
ES,
LK,
SR,
SJ,
SE,
CH,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
VI,
UG,
AE,
GB,
UM,
US,
UY,
VU,
VE,
VN,
WF,
EH,
ZM,
ZW,
all
​
targetCountries
enum<string>[]
​
targetLocationRespondentInPerson
object

Required for In-Person projects only. Please provide the full address (including city & state if applicable) where the project will be conducted.

​
targetHouseholdIncome
enum<string>[]
​
targetGenders
enum<string>
Available options:
male,
female,
other,
N/A
​
targetEducation
enum<string>[]
​
targetEthnicities
enum<string>[]
​
targetAgeGroups
enum<string>[]
​
ndaType
enum<string>
default:none
deprecated

Use ndaDetails.ndaType.

Available options:
none,
file,
link
​
ndaLink
string | null
deprecated

Use ndaDetails.ndaLink.

​
automations
object
​
keyQualifiers
enum<string>[]
​
filterPastParticipation
object
  • If researcher wants to filter out participants who have participated in past projects.
  • Past Participation logic is used at Researcher level based on external reseacher id.
  • The participant must have been paid for a project to count as a past participant.
  • Past participation filtering is available within 4 hours of a payout being made, NOT immediately after payment.
​
targetCities
object[]
​
ndaDetails
object

ndaType = file is not supported on this endpoint. Use the Upload NDA File endpoint to upload NDA documents

​
externalResearcher
object

Required for all projects to identify your researcher with Respondent to differentiate from other researchers recruiting through your platform.

​
targetProjectTopics
string[]

Pass ids only. IDs differ from staging to production. Required for General Population (B2C) projects only. Tagging your projects with topics will better help match your general population project with participants that have indicated interest in these topics. Array: Min 1 and Max 2.

Response

200 - application/json
​
createdAt
string
required
​
publicTitle
string
required

Project Title. This is visible to Respondents, do not mention any incentive amount as you may change it during your project.

​
publicInternalName
string
required

Internal Project Name. This is visible only to your organization. Character Limit: Min 3 and Max 50.

​
projectStatus
enum<string>
required
Available options:
DRAFT,
PAID,
ARCHIVED,
CLOSED
​
projectRecruitingStatus
enum<string>
required
Available options:
RECRUITING,
RECRUITED,
PAUSED
​
targetMarketType
enum<string>
required

Audience type to be targeted for this project. Example values: Industry professionals (B2B) or General Population (B2C)

Available options:
b2b,
b2c
​
typeOfResearch
enum<string>
required

Research type for this project, if it is in-person or remote

Available options:
inPerson,
remote
​
targetResearchMethodology
enum<string>
required

Kind of research to be conducted for this project. Details here. If typeOfResearch == inPerson → allowed values are: [oneOnOne, focusGroup, inRespondentHome, inRespondentOffice] If typeOfResearch == remote → allowed values are: [oneOnOne, focusGroup, unmoderatedStudy, survey, diaryStudy]

Available options:
oneOnOne,
focusGroup,
inRespondentHome,
inRespondentOffice,
unmoderatedStudy,
survey,
diaryStudy
​
participantTimeRequiredMinutes
number
required
​
incentiveAmount
number
required

Dollars ranging: Min 5 and Max 1000. Pro tip: Set your incentive at or above $2 per minute (B2C) or $3 per minute (B2B) to attract quality participants faster. More tips to pick the right incentive: https://help.respondent.io/en/articles/5471087-what-is-the-best-incentive-for-my-research-project

​
targetNumberOfParticipants
number
required

Number of Participants We will recruit up to 3 times your target number of qualified participants. Number Limit: Min 1 and Max 500.

​
externalResearcher
object
required

Required for all projects to identify your researcher with Respondent to differentiate from other researchers recruiting through your platform.

​
id
string
required
​
updatedAt
string
​
publicDescription
string

Project Details. This is visible to Respondents. Character Limit: Max 800.

​
organizationId
string<ObjectId>
​
teamId
string<ObjectId>
​
unmoderatedStudyOrSurvey
object

For Unmoderated Studies and Surveys only.

​
targetCountry
enum<string>
Available options:
AX,
AL,
DZ,
AS,
AD,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BA,
BW,
BV,
BR,
VG,
IO,
BN,
BG,
BF,
BI,
CV,
CM,
CA,
KY,
CF,
TD,
CL,
CX,
CC,
CO,
KM,
CG,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
CI,
CD,
DK,
DJ,
DM,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
LA,
LV,
LB,
LR,
LY,
LI,
LT,
LU,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NU,
NF,
KP,
MK,
MP,
NO,
OM,
PW,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RO,
RW,
RE,
SH,
KN,
LC,
PM,
VC,
WS,
SM,
ST,
SA,
RS,
SC,
SL,
SG,
SK,
SI,
SB,
SO,
ZA,
GS,
KR,
ES,
LK,
SR,
SJ,
SE,
CH,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
VI,
UG,
AE,
GB,
UM,
US,
UY,
VU,
VE,
VN,
WF,
EH,
ZM,
ZW,
all
​
targetCountries
enum<string>[]
​
targetCities
object[]
​
targetJobFunctions
enum<string>[]
​
targetCompanySize
enum<string>[]
​
targetLocationRespondentInPerson
object

Required for In-Person projects only. Please provide the full address (including city & state if applicable) where the project will be conducted.

​
targetHouseholdIncome
enum<string>[]
​
targetGenders
enum<string>
Available options:
male,
female,
other,
N/A
​
targetEducation
enum<string>[]
​
targetEthnicities
enum<string>[]
​
targetAgeGroups
enum<string>[]
​
screenerQuestions
object[]
​
inviteSurveyLink
string
​
closedDetails
object
​
closed
boolean
deprecated

Use projectStatus: 'CLOSED'

​
closedMessage
string
deprecated

Use closedDetails.closedMessage.

​
closedOnDate
string<date-time>
deprecated

Use closedDetails.closedOnDate.

​
closedByUserId
string
deprecated

Use closedDetails.closedByUserId.

​
ndaDetails
object
​
ndaType
enum<string>
default:none
deprecated

Use ndaDetails.ndaType.

Available options:
none,
file,
link
​
ndaFileUrl
string | null
deprecated

Use ndaDetails.ndaFileUrl

​
ndaLink
string | null
deprecated

Use ndaDetails.ndaLink.

​
filterPastParticipation
object
  • If researcher wants to filter out participants who have participated in past projects.
  • Past Participation logic is used at Researcher level based on external reseacher id.
  • The participant must have been paid for a project to count as a past participant.
  • Past participation filtering is available within 4 hours of a payout being made, NOT immediately after payment.
​
seniority
enum<string>[]
​
publishedAt
string<date-time>
​
automations
object
  • Autopay is used to automatically pay participants after they complete a project.
    • If not provided, defaults to true.
  • Autoinvite is used to automatically invite participants to a project if they qualify after completing the screener.
    • Only available when targetResearchMethodology is one of: [unmoderatedStudy, survey].
    • If not provided, defaults to false.
​
keyQualifiers
enum<string>[]
​
completionUrl
string | null

Researchers can provide participants with this link at the conclusion of their survey or study, enabling them to self-report task completion. Available for projects where the targetResearchMethodology is either unmoderatedStudy or survey.

​
targetProfessionalIndustries
object[]

Required for Industry professionals (B2B) projects Array: Min 1 and Max 5.

​
targetJobTitles
object[]

Available for Industry professionals (B2B) projects. Array: Max 30.

​
targetProjectTopics
object[]

Required for General Population (B2C) projects only Tagging your projects with topics will better help match your general population project with participants that have indicated interest in these topics. Array: Min 1 and Max 2.

​
targetAudienceSkills
object[]

Array: Min 0 and Max 25. Select skills, knowledge areas, tools and/or certifications you would like to target.