External screeners

• How the flow works end to end, and the two response statuses it adds
• Setting up a project: the screener link and the declared question catalog
• Receiving participants (the respondent_* correlation parameters)
• Posting answers back, corrections, and how the qualification verdict is derived
• The return contract — the two rules your redirect must follow
• Webhooks and status handling

​

How the flow works

1. A participant applies to your project and completes the Respondent screener as usual.
2. If they qualify, their screener response moves to SECOND_SCREENER_IN_PROGRESS and Respondent shows them a handoff page explaining they’ll finish the screener on your platform. When they continue, they arrive at your externalScreenerLink with correlation parameters appended.
3. The participant completes your screener on your site.
4. You post their answers back with Post external screener answers, then redirect them to the Respondent page they came from. You must ensure all answers are posted before the user can be redirected back.
5. Once the answers cover your declared question catalog (or you signal early completion), the response moves to SECOND_SCREENER_SUBMITTED. From there it behaves exactly like a classic submitted application: it’s visible to the researcher, counts toward the project’s applications, and can be invited — manually or by auto-invite.

​

Setting up a project

• externalScreenerLink — the URL of your screener. Participants are sent here with correlation parameters appended, so the URL may include its own query string.
• externalQuestions — the declared catalog of your screener’s questions. Answer rows you post back are validated against these questionIds, and the catalog defines when a response counts as complete.

PUT /v1/projects/{projectId}/external-screener-questions/bulk

[
  {
    "questionId": "team-size",
    "questionType": "RADIO",
    "text": "How many people do you manage?",
    "options": ["None", "1-5", "6-20", "More than 20"]
  },
  {
    "questionId": "tooling",
    "questionType": "TEXT",
    "text": "Which tools does your team use day to day?"
  }
]

• The endpoint replaces the whole catalog (like the screener questions bulk endpoint). Send the full list every time.
• questionId is your stable identifier — answer rows reference it, and completion is counted against it. Duplicate questionIds are rejected.
• questionType is one of RADIO, CHECKBOX, TEXT, NUMBER, or OTHER. Use OTHER for anything not modelled — the text keeps the answers legible to researchers either way.
• Don’t change questionIds while a project is live: answers already posted are keyed by them, and completion counting depends on the declared set.

​

Receiving participants

​

Posting answers back

POST /v1/projects/{respondent_project_id}/screener-responses/{respondent_screener_response_id}/external-screener-answers

{
  "answers": [
    {
      "questionId": "team-size",
      "answerValues": ["6-20"],
      "qualifies": true
    },
    {
      "questionId": "tooling",
      "answerText": "Jira, Figma, and an internal planning tool",
      "qualifies": true
    }
  ]
}

• Rows upsert idempotently per questionId. Re-sending a row replaces the earlier one, so a correction is just another POST — including flipping an earlier qualifies verdict. Respondent re-derives the response’s state from the stored rows on every write.
• Each row must reference a declared questionId (undeclared ids are rejected) and must carry content: at least one of answerValues (a non-empty array — multi-select friendly) or answerText (a non-empty string).
• Completion: the response moves to SECOND_SCREENER_SUBMITTED once the stored rows cover every declared question. If participants may legitimately skip questions on your side, send "complete": true alongside the answers to settle the response early — you can post in as many batches as you like before that.
• The verdict is derived: the response ends up qualified only if every stored row has qualifies: true. A failed verdict settles the response on SECOND_SCREENER_SUBMITTED with qualified: false — visible to the researcher, but excluded from qualified counts and auto-invite.
• You can keep posting corrections while the response is in SECOND_SCREENER_IN_PROGRESS, SECOND_SCREENER_SUBMITTED, or PENDING. Once the participant has been invited, the response is closed to answer writes.
• For an overall disqualification decision that isn’t tied to answer rows, use Qualify participant with qualifyStatus: false — same as on classic projects. Note that a later answers re-post re-derives the verdict from the rows, which can undo a manual flip.

​

The return contract

https://app.respondent.io/participants/projects/{respondent_project_id}/apply

​

Webhooks and statuses

• the handoff: status DRAFT → SECOND_SCREENER_IN_PROGRESS
• the submission: status SECOND_SCREENER_IN_PROGRESS → SECOND_SCREENER_SUBMITTED

• Plain PENDING on an external-screener project means “held” — the response is in an identity-verification or review hold. It settles back to SECOND_SCREENER_SUBMITTED when released. Your answer posts are still accepted during the hold.
• Cancel invite reverts to SECOND_SCREENER_SUBMITTED, not PENDING — the participant already completed your screener, so withdrawing an invitation doesn’t send them through it again.
• List screener responses accepts both new values in its statuses filter.

​

Quick reference