Screening Questions

Screening questions are asked to participants during application. Most are multi-option questions that qualify or disqualify based on the chosen answer (design these so the qualifying answer is not obvious). You can also ask open-ended freeform questions (pick: "text") when you want a written response to review rather than an automatic qualify/reject.

Example

[
  {
    "key": "role_type",
    "text": "Which best describes your current role?",
    "pick": "one",
    "answers": [
      { "text": "Individual contributor", "qualify_logic": "may" },
      { "text": "People manager", "qualify_logic": "may" },
      { "text": "Executive / C-suite", "qualify_logic": "may" },
      { "text": "Not currently employed", "qualify_logic": "reject" }
    ]
  },
  {
    "key": "facility_size",
    "text": "What is the approximate total square footage of facilities you currently oversee?",
    "pick": "one",
    "answers": [
      { "text": "I don't manage any facilities", "qualify_logic": "reject" },
      { "text": "Under 10,000 sqft", "qualify_logic": "reject" },
      { "text": "10,000 - 50,000 sqft", "qualify_logic": "may" },
      { "text": "50,001 - 100,000 sqft", "qualify_logic": "may" },
      { "text": "100,001 - 500,000 sqft", "qualify_logic": "must_one_of" },
      { "text": "Over 500,000 sqft", "qualify_logic": "must_one_of" }
    ]
  },
  {
    "key": "team_size",
    "text": "How many direct reports do you have?",
    "pick": "one",
    "answers": [
      { "text": "1-5", "qualify_logic": "may" },
      { "text": "6-15", "qualify_logic": "may" },
      { "text": "16-50", "qualify_logic": "may" },
      { "text": "Over 50", "qualify_logic": "may" }
    ]
  }
]

The key field is a client-defined identifier for the question. It is required when the question is referenced by a quota.

Whether or not you send one, every question reads back with a key, and that same value is returned as screening_answers[].key on GET /submissions/{submissionId}. That is how you join an answer to the question that produced it. Treat the value as opaque: when you omit key we assign one, and the format is not part of the contract.

Question Fields

Question Types

Open-Ended Questions

Set pick: "text" for a freeform response. Open-ended questions have no answers and no qualifying logic, so they do not auto-screen participants. Submissions are routed to manual review for you to read the response and approve or reject. Quotas cannot target open-ended questions.

[
  {
    "key": "biggest_challenge",
    "text": "What is the biggest challenge you face managing your facilities today?",
    "pick": "text"
  }
]

Qualify Logic

Note: On multi-select (pick: "any"), must means this exact answer is required, while must_one_of means at least one of a group. Use must for each individually-required option (e.g. "must have run Google Ads") and must_one_of for an any-of group (e.g. "Meta OR TikTok").

Single-select collapse: on pick: "one" and pick: "boolean" only one answer can be picked, so may / must / must_one_of all persist as the same qualifying disposition (and read back as must). Only reject and review change the outcome on a single-select — use pick: "any" when you need a distinct disposition per answer.

On multi-select, min_qualifying raises the "at least one of" bar for the must_one_of group: with three must_one_of answers and min_qualifying: 2, a participant must select at least two of the three to qualify. Omitted or 1 keeps the default "at least one of" behavior. It is ignored for other pick types.

Grid Questions

Set pick: "grid" for a matrix question that asks the same set of choices about several items. Omit answers and provide grid instead. Per-cell qualify_logic uses the same values as answers.

Use grid.pick to control how many columns a participant may choose per row: "one" (default) is a single column per row, and "any" lets them select any number of columns per row (a "select all that apply per row" matrix).

[
  {
    "key": "platforms",
    "text": "How active are you on each platform?",
    "pick": "grid",
    "grid": {
      "rows": [
        { "key": "youtube", "text": "YouTube" },
        { "key": "tiktok", "text": "TikTok" }
      ],
      "columns": [
        { "value": "active", "text": "Active" },
        { "value": "never", "text": "Never" }
      ],
      "cell_actions": [
        {
          "row": "youtube",
          "column": "active",
          "qualify_logic": "must_one_of"
        },
        { "row": "tiktok", "column": "active", "qualify_logic": "must_one_of" }
      ]
    }
  }
]

Ask Only If (Display Conditions)

Use display_condition to show a question only when earlier answers match -- for example, ask a Meta-specific follow-up only if the participant said they use Meta. Each condition references an earlier question by its key and one of its answers (for a grid source, use "Row: Column"). Conditions are combined with join (and / or). A condition that references a later question returns a BAD_REQUEST error.

[
  {
    "key": "platforms",
    "text": "Which platforms do you use?",
    "pick": "any",
    "answers": [
      { "text": "Meta", "qualify_logic": "may" },
      { "text": "TikTok", "qualify_logic": "may" }
    ]
  },
  {
    "key": "meta_spend",
    "text": "What is your monthly Meta ad spend?",
    "pick": "one",
    "answers": [
      { "text": "$10k+", "qualify_logic": "must" },
      { "text": "Under $10k", "qualify_logic": "reject" }
    ],
    "display_condition": {
      "conditions": [
        {
          "screening_question": "platforms",
          "answer": "Meta",
          "operator": "eq"
        }
      ],
      "join": "and"
    }
  }
]

Rich Text Prompts

Set question_rich_text to render the prompt with Markdown (GitHub-flavored: bold, bullet lists, links). text stays required and remains the plaintext source of truth used by the voice agent and search, so keep the two in sync — question_rich_text only changes how the prompt is displayed to participants.

[
  {
    "key": "compliance",
    "text": "Which compliance frameworks has your team completed in the last 12 months?",
    "question_rich_text": "Which compliance frameworks has your team **completed** in the last 12 months?\n\n- Count only audits that closed\n- Exclude in-progress engagements",
    "pick": "any",
    "answers": [
      { "text": "SOC 2", "qualify_logic": "must_one_of" },
      { "text": "ISO 27001", "qualify_logic": "must_one_of" },
      { "text": "None of these", "qualify_logic": "reject" }
    ]
  }
]

Consistency Checks (Conditional Rules)

conditional_rules catch inconsistent or low-quality answers that per-answer qualify logic can't express on its own — for example, a participant who claims a senior role but selects none of the tasks that role would actually do. When a rule's conditions match, it either rejects the participant or flags the submission for human review.

Unlike a display_condition (which references an earlier question to gate visibility), a consistency-check condition may reference any question by key, or omit screening_question to test an answer on the question the rule lives on (a self-check). Write one all-and rule per pattern you want to catch.

[
  {
    "key": "role",
    "text": "What is your role?",
    "pick": "one",
    "answers": [
      { "text": "Store Manager", "qualify_logic": "may" },
      { "text": "Associate", "qualify_logic": "may" }
    ]
  },
  {
    "key": "tasks",
    "text": "Which of these do you do day to day?",
    "pick": "any",
    "answers": [
      { "text": "Approve schedules", "qualify_logic": "may" },
      { "text": "Manage the P&L", "qualify_logic": "may" },
      { "text": "None of these", "qualify_logic": "may" }
    ],
    "conditional_rules": [
      {
        "conditions": [
          { "screening_question": "role", "answer": "Store Manager" },
          { "answer": "None of these", "operator": "eq" }
        ],
        "join": "and",
        "outcome": "review"
      }
    ]
  }
]

The second condition omits screening_question, so it tests an answer on the tasks question the rule lives on: a "Store Manager" who also picks "None of these" is flagged for review.

Branching (Skip Rules)

skip_rules let a question jump the participant forward — to a later question, or straight to the end of the screener — based on how they answered it. A rule tests the answers of the question it lives on, and the target must be a later question (the screener only walks forward). Not available for pick: "text" or "grid".

[
  {
    "key": "uses_product",
    "text": "Do you currently use the product?",
    "pick": "boolean",
    "answers": [
      { "text": "Yes", "qualify_logic": "may" },
      { "text": "No", "qualify_logic": "may" }
    ],
    "skip_rules": [
      {
        "conditions": [
          {
            "screening_question": "uses_product",
            "answer": "No",
            "operator": "eq"
          }
        ],
        "join": "and",
        "target_question": null
      }
    ]
  },
  {
    "key": "plan_tier",
    "text": "Which plan are you on?",
    "pick": "one",
    "answers": [
      { "text": "Free", "qualify_logic": "may" },
      { "text": "Pro", "qualify_logic": "may" }
    ]
  }
]

A participant who answers "No" skips straight to the end; everyone else continues to the plan-tier question.

Reading Screen-Out Rates

GET /opportunities/{opportunityId} returns screening_stats on a live opportunity: one entry per question, keyed by the same key you authored.

{
  "screening_question": "years_experience",
  "graded": 412,
  "rejected": 321,
  "rejection_rate": 0.78,
  "answers": [
    { "text": "0-10", "selected": 91, "share": 0.22 },
    { "text": "Over 10 years", "selected": 321, "share": 0.78 }
  ]
}

graded counts the finished screeners that were graded on this question, which is not the same as how many people answered it. A screener with skip_rules or a display_condition stops grading at the first failure, so an answer the evaluator never reached carries no verdict and is excluded here.

That distinction is what makes rejection_rate useful: it is the share of the population that could have been rejected on this question, not the share of everyone who applied. A question late in a branching screener can show a high rate on a small graded count, which means it is strict among the few who got that far, not that it is your main bottleneck. Sort by rejected when you want the question costing you the most applicants, and by rejection_rate when you want the strictest one.

answers[].share is out of the same graded count, so a lopsided split is the signal that a question is narrower than intended. In the example above, widening the accepted range on years_experience is worth more than touching any other question.