GET
/
v1
/
projects
/
{projectId}
Retrieve a specific project
curl --request GET \
  --url https://api-staging.respondent.io/v1/projects/{projectId} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-api-secret: <x-api-secret>'
{
  "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

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.