Getting started
Project Setup
Screener Response Handling
Messaging
Lookup and Reference Data
Webhooks
Team Tools
Retrieve all projects
Returns All Projects. Closed projects are not returned by default. To get a list of closed projects only, set status = CLOSED.
curl --request GET \
--url https://api-staging.respondent.io/v1/projects \
--header 'x-api-key: <x-api-key>' \
--header 'x-api-secret: <x-api-secret>'{
"page": 1,
"pageSize": 50,
"results": [
{
"createdAt": "<string>",
"publicTitle": "<string>",
"publicInternalName": "<string>",
"projectStatus": "DRAFT",
"projectRecruitingStatus": "RECRUITING",
"targetMarketType": "b2b",
"typeOfResearch": "inPerson",
"targetResearchMethodology": "oneOnOne",
"participantTimeRequiredMinutes": 123,
"incentiveAmount": 123,
"targetNumberOfParticipants": 123,
"externalResearcher": {
"researcherId": "<string>",
"researcherName": "<string>",
"teamId": "<string>",
"companyName": "<string>",
"companyId": "<string>",
"bookingUrl": "<string>"
},
"id": "<string>",
"updatedAt": "<string>",
"publicDescription": "<string>",
"organizationId": "<string>",
"teamId": "<string>",
"unmoderatedStudyOrSurvey": {
"remoteCommunicationDetails": "<string>",
"specialInstructions": "<string>"
},
"targetCountry": "AX",
"targetCountries": [
"AX"
],
"targetCities": [
{
"location": {
"city": "<string>",
"country": "AX",
"location": {
"longitude": 123,
"latitude": 123
},
"id": "<string>",
"googleId": "<string>",
"region": "<string>",
"state": "<string>",
"zipcode": "<string>",
"address1": "<string>",
"formattedAddress": "<string>"
}
}
],
"targetJobFunctions": [
"accountingAuditing"
],
"targetCompanySize": [
"selfemployed"
],
"targetLocationRespondentInPerson": {
"address1": "<string>",
"city": "<string>",
"country": "AX",
"formattedAddress": "<string>",
"latitude": 123,
"longitude": 123,
"id": "<string>",
"zipcode": "<string>",
"region": "<string>",
"state": "<string>"
},
"targetHouseholdIncome": [
"<30000"
],
"targetGenders": "male",
"targetEducation": [
"somehighschool"
],
"targetEthnicities": [
"americanindianalaskannative"
],
"targetAgeGroups": [
"18-20"
],
"screenerQuestions": [
{
"createdAt": "<string>",
"text": "<string>",
"minValue": 123,
"maxValue": 123,
"step": 123,
"id": "<string>",
"updatedAt": "<string>",
"questionType": "radio",
"uid": "<string>",
"answers": [
{
"createdAt": "<string>",
"uid": "<string>",
"answerValue": 123,
"id": "<string>",
"updatedAt": "<string>",
"text": "<string>",
"goToQuestionUid": "<string>",
"isOther": true
}
],
"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"
}
},
"order": 123,
"warnings": [
"<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"
},
"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>",
"name": "<string>",
"slug": "<string>",
"validated": false,
"type": "skill",
"id": "<string>",
"updatedAt": "<string>",
"count": 0
}
]
}
],
"totalResults": 123
}Query Parameters
Specifies which page of results to return
Number of records to return per page
If true, includes the total count of records
External identifier for the researcher who created project on your system
Current state of the project. See more details on Project Statuses.
DRAFT, PAID, ARCHIVED, CLOSED Response
Show child attributes
Show child attributes
Project Title. This is visible to Respondents, do not mention any incentive amount as you may change it during your project.
Internal Project Name. This is visible only to your organization. Character Limit: Min 3 and Max 50.
DRAFT, PAID, ARCHIVED, CLOSED RECRUITING, RECRUITED, PAUSED Audience type to be targeted for this project. Example values: Industry professionals (B2B) or General Population (B2C)
b2b, b2c Research type for this project, if it is in-person or remote
inPerson, remote 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]
oneOnOne, focusGroup, inRespondentHome, inRespondentOffice, unmoderatedStudy, survey, diaryStudy 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
Number of Participants We will recruit up to 3 times your target number of qualified participants. Number Limit: Min 1 and Max 500.
Required for all projects to identify your researcher with Respondent to differentiate from other researchers recruiting through your platform.
Show child attributes
Show child attributes
A unique researcher ID provided by you, used to associate and filter projects.
To be used when sending messages or emails to the respondent. Full name not required.
Optional additional filtering. This researcher's internal teamId from your organization.
Optional additional filtering. This researcher's internal companyId from your organization.
Link to book a meeting with the researcher. Required if targetResearchMethodology of project is oneOnOne or focusGroup.
Required when publishing a project. This is visible to Respondents. A short description of the project visible to participants. This should clearly outline the purpose, requirements, and expectations for participation. Character Limit: Max 800.
For Unmoderated Studies and Surveys only.
Show child attributes
Show child attributes
Custom url for the study, to be sent in the invitation . Can be updated when inviting the participant.
Special instructions for the study, to be sent in the invitation. Can be updated when inviting the participant. Character limit: Max 2000.
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 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 Show child attributes
Show child attributes
Show child attributes
Show child attributes
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 Available for Industry professionals (B2B) projects Max: 3
accountingAuditing, administrative, advertising, analyst, artCreative, businessDevelopment, consulting, customerService, distribution, design, education, finance, generalBusiness, healthcareProvider, humanResources, informationTechnology, legal, management, manufacturing, marketing, other, publicRelations, purchasing, productManagement, projectManagement, production, qualityAssurance, research, sales, science, strategyPlanning, supplyChain, training, writingEditing selfemployed, 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10000+, all Required for In-Person projects only. Please provide the full address (including city & state if applicable) where the project will be conducted.
Show child attributes
Show child attributes
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 <30000, 30000-39999, 40000-59999, 60000-79999, 80000-99999, 100000-149999, 150000-199999, 200000+, all, all male, female, other, nonbinary, transmale, transfemale, prefernottoanswer, N/A somehighschool, highschoolgraduate, somecollegenodegree, tradetechnicalvocationaltraining, associatedegree, bachelordegree, masterdegree, doctoratedegree, N/A americanindianalaskannative, hispaniclatino, blackorafricanamerican, asianpacificislander, whitecaucasian, middleeastern, multipleethnicity, prefernotdisclose, N/A 18-20, 21-29, 30-39, 40-54, 55+, N/A Show child attributes
Show child attributes
radio, multiLineTextbox, checkbox, singleLineTextbox, numericBox, sliderScale Show child attributes
Show child attributes
CHECKBOX: { id: 3, answerValues: [ { id: 1, text: 'May Select' }, { id: 2, text: 'Must Select' }, { id: 3, text: 'Disqualify' }, ], }, RADIO: { id: 1, answerValues: [ { id: 1, text: 'Qualify' }, { id: 2, text: 'Disqualify' }, ], },
Required unless isOther, then text will be set to 'Other'
Skip logic for radio questions. Uid of question to skip to.
Is 'Other' answer with comment field
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Use projectStatus: 'CLOSED'
Use closedDetails.closedMessage.
Use closedDetails.closedOnDate.
Use closedDetails.closedByUserId.
Use ndaDetails.ndaType.
none, file, link Use ndaDetails.ndaFileUrl
Use ndaDetails.ndaLink.
- 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.
Show child attributes
Show child attributes
If true → only include participants who have never participated in a project with the researcher.
If false → only include participants who have not participated in a project with the researcher in the past months months.
It's autocalculated based on the hasNeverParticipated / months entered and displays in the API response
Number of months to exclude participants who have previously participated in a study.
Used only when hasNeverParticipated is false. For example, months: 3 excludes participants who participated in the past 3 months.
-1, 1, 2, 3, 6, 9, 12 unpaid, student, training, entrylevel, senior, manager, director, chiefofficer, partner, vicepresident - Autopay is used to automatically pay participants after they complete a project.
- If not provided, defaults to
true.
- If not provided, defaults to
- Autoinvite is used to automatically invite participants to a project if they qualify after completing the screener.
- Only available when
targetResearchMethodologyis one of: [unmoderatedStudy,survey]. - If not provided, defaults to
false.
- Only available when
Converts signals into required match filters. Details here.
targetHouseholdIncome, targetProfessionalIndustries, targetCompanySize, targetProjectTopics, targetAudienceSkills 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.
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.
Array: Min 0 and Max 25. Select skills, knowledge areas, tools and/or certifications you would like to target.
Show child attributes
Show child attributes
The total number of results possible, which is only provided in the response when includeCount is passed as true within a request.
Was this page helpful?
curl --request GET \
--url https://api-staging.respondent.io/v1/projects \
--header 'x-api-key: <x-api-key>' \
--header 'x-api-secret: <x-api-secret>'{
"page": 1,
"pageSize": 50,
"results": [
{
"createdAt": "<string>",
"publicTitle": "<string>",
"publicInternalName": "<string>",
"projectStatus": "DRAFT",
"projectRecruitingStatus": "RECRUITING",
"targetMarketType": "b2b",
"typeOfResearch": "inPerson",
"targetResearchMethodology": "oneOnOne",
"participantTimeRequiredMinutes": 123,
"incentiveAmount": 123,
"targetNumberOfParticipants": 123,
"externalResearcher": {
"researcherId": "<string>",
"researcherName": "<string>",
"teamId": "<string>",
"companyName": "<string>",
"companyId": "<string>",
"bookingUrl": "<string>"
},
"id": "<string>",
"updatedAt": "<string>",
"publicDescription": "<string>",
"organizationId": "<string>",
"teamId": "<string>",
"unmoderatedStudyOrSurvey": {
"remoteCommunicationDetails": "<string>",
"specialInstructions": "<string>"
},
"targetCountry": "AX",
"targetCountries": [
"AX"
],
"targetCities": [
{
"location": {
"city": "<string>",
"country": "AX",
"location": {
"longitude": 123,
"latitude": 123
},
"id": "<string>",
"googleId": "<string>",
"region": "<string>",
"state": "<string>",
"zipcode": "<string>",
"address1": "<string>",
"formattedAddress": "<string>"
}
}
],
"targetJobFunctions": [
"accountingAuditing"
],
"targetCompanySize": [
"selfemployed"
],
"targetLocationRespondentInPerson": {
"address1": "<string>",
"city": "<string>",
"country": "AX",
"formattedAddress": "<string>",
"latitude": 123,
"longitude": 123,
"id": "<string>",
"zipcode": "<string>",
"region": "<string>",
"state": "<string>"
},
"targetHouseholdIncome": [
"<30000"
],
"targetGenders": "male",
"targetEducation": [
"somehighschool"
],
"targetEthnicities": [
"americanindianalaskannative"
],
"targetAgeGroups": [
"18-20"
],
"screenerQuestions": [
{
"createdAt": "<string>",
"text": "<string>",
"minValue": 123,
"maxValue": 123,
"step": 123,
"id": "<string>",
"updatedAt": "<string>",
"questionType": "radio",
"uid": "<string>",
"answers": [
{
"createdAt": "<string>",
"uid": "<string>",
"answerValue": 123,
"id": "<string>",
"updatedAt": "<string>",
"text": "<string>",
"goToQuestionUid": "<string>",
"isOther": true
}
],
"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"
}
},
"order": 123,
"warnings": [
"<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"
},
"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>",
"name": "<string>",
"slug": "<string>",
"validated": false,
"type": "skill",
"id": "<string>",
"updatedAt": "<string>",
"count": 0
}
]
}
],
"totalResults": 123
}