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 the answers to the Respondent screener qualifies them for the study, the participant is shown 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 due to skip logic, disqualification etc.), the response moves to PENDING — the same status a classic application reaches when it is submitted — provided nothing else is outstanding on our side. The participant may be required to complete identity verification steps on the Respondent platform, so the response stays EXTERNAL_SCREENER_IN_PROGRESS until they complete it, and moves to PENDING on its own afterwards. Do not treat a response that has not yet reached PENDING as an error. From PENDING it behaves like any classic application: one that passed (qualified: true) and is not held is visible to the researcher, counts toward the project’s applications, and can be invited — manually or by auto-invite. A failed verdict stays PENDING too but is never auto-invited, and a held response is not visible to the researcher until its hold resolves.

​

Setting up a project

• externalScreenerLink — the URL of your screener, as an absolute https:// URL (http:// and bare hostnames are rejected). 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.

​

Publishing preconditions

​

Changing the screener after publish

• Set or change externalScreenerLink with Update a project — it is one of the fields accepted on a live project. While externalQuestions are declared the link is required, so a null is rejected with a 400; send the new URL instead.
• Set or replace externalQuestions with Replace external screener questions — the same replace-all endpoint you use on a draft.

• Participants who applied before both were configured went through the classic flow and are already PENDING — they never saw your screener, and they stay invitable. If you want their answers too, screen them on your side after inviting them.
• Participants who were already handed off to your screener keep the URL they were sent to when they resume from the Respondent apply page, so a partner session they started is not broken by a link change. New applicants get the new link.
• Removing the link is only possible while no catalog is declared. Answers you already posted stay on their responses either way.

​

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: your side of the screener is complete once the stored rows cover every declared question. The response then moves to PENDING, unless a Respondent verification step is still outstanding — see step 5. 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 PENDING 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 EXTERNAL_SCREENER_IN_PROGRESS 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

• A PENDING response may still be held — in an identity-verification or review hold, it is not yet visible to the researcher. The status does not change when the hold is released. Your answer posts are accepted throughout.
• Cancel invite reverts to PENDING — the same as on a classic project. The participant’s answers are already stored, so withdrawing an invitation does not send them through your screener again.
• List screener responses accepts EXTERNAL_SCREENER_IN_PROGRESS in its statuses filter.

​

Quick reference