Pre-filled answers (`selectedAnswer`)

Set selectedAnswer on a custom question when you already know the likely answer. If the verifier leaves that question blank, the pre-filled value is the answer you receive. If the verifier answers it, their answer replaces yours. Standard questions cannot be pre-filled.

Download this guide

Pre-fills are sent on Create order, inside searchTypes[].verificationQuestions[]. For the full question schema, see Verification question.

The verifier never sees a pre-fill. Every answer box on the verification form is drawn empty. A pre-fill is a fallback answer, not a value the verifier is asked to confirm.

Before you start

Rule	Detail
Search types	`EMPLOYMENT` and `EDUCATION` only.
When	At order creation only. Questions, including pre-fills, cannot be changed after the order is created.
Omitted value	`selectedAnswer` defaults to `null`, which means no pre-fill.
Length	Each string, including each array entry, is at most 2000 characters.
Comments	`comment` is a pre-fill for the comment box. Set `allowComment: true` when you send one.

Value shape by question type

selectedAnswer is a string for every type except multi_select, which takes an array of strings. Numbers and booleans are never accepted, including for numeric, rating_scale, and checkbox.

`type`	Shape	Accepted pre-fill	Stored and returned as
`free_text`	`string`	Any string	Exactly what you sent
`single_select`	`string`	An `options[].value` or `options[].label`, any case	The matching `options[].value`
`multi_select`	`string[]`	Exact `options[].value` strings. Case-sensitive. Labels are rejected.	The array you sent
`rating_scale`	`string`	An integer string inside `scale.min`–`scale.max`. Surrounding spaces and leading zeros are allowed.	The bare integer, such as `"4"`
`yes_no`	`string`	`"Yes"` or `"No"`, any case	`"Yes"` or `"No"`
`numeric`	`string`	A plain decimal: optional `-`, digits, optional `.` and digits	Exactly what you sent
`checkbox`	`string`	Exactly `"true"` or `"false"`, lowercase	Exactly what you sent

Read selectedAnswer from the webhook as a string, or a string[] for multi_select. Branch on type before parsing. Convert numeric and rating_scale answers to numbers in your own code.

What comes back on the webhook

Answers arrive in data.verificationQuestions on verification.completed. See Webhook events.

What the verifier does	`selectedAnswer` on the webhook
Leaves the question blank, or returns the form untouched	Your pre-fill
Writes text or a number in the box	The verifier’s answer
Selects a radio option (`single_select`, `yes_no`)	The verifier’s option value
Checks one or more `multi_select` options	Exactly the options the verifier checked. Your pre-fill is replaced, not added to.
Checks no `multi_select` options	Your pre-fill
Checks the `checkbox`	`"true"`
Leaves the `checkbox` unchecked on a returned form	`"false"`, even over a `"true"` pre-fill
States an answer in the email reply instead of the form	The verifier’s answer. An answer on the returned form wins over the email text.

The same rules apply to answers from an earlier reply. If one reply checks dental and a later copy of the form comes back with nothing checked, the answer stays ["dental"].

Examples by type

Each example is one entry in searchTypes[].verificationQuestions[], followed by the webhook selectedAnswer for a blank return and for a verifier who answers.

free_text

{
  "questionId": 100010,
  "type": "free_text",
  "prompt": "Department the employee worked in",
  "selectedAnswer": "Engineering"
}

Verifier	Webhook `selectedAnswer`
Leaves it blank	`"Engineering"`
Writes “Finance”	`"Finance"`

Spaces are kept exactly as sent. A value made only of spaces counts as blank, so it does not satisfy required.

single_select

You can send the option label. It is stored as the option value, and the webhook always returns the value.

{
  "questionId": 100011,
  "type": "single_select",
  "prompt": "Eligible for a similar role?",
  "allowComment": true,
  "options": [
    { "value": "yes", "label": "Yes" },
    { "value": "no", "label": "No" },
    { "value": "unknown", "label": "Unknown" }
  ],
  "selectedAnswer": "YES",
  "comment": "Confirmed in HRIS"
}

Verifier	Webhook `selectedAnswer`	Webhook `comment`
Leaves it blank	`"yes"`	`"Confirmed in HRIS"`
Selects No and writes “Left on bad terms”	`"no"`	`"Left on bad terms"`

multi_select

Send exact options[].value strings in an array. Labels and case variants are rejected.

{
  "questionId": 100012,
  "type": "multi_select",
  "prompt": "Which benefits did the employee have?",
  "maxSelections": 2,
  "options": [
    { "value": "health", "label": "Health" },
    { "value": "dental", "label": "Dental" },
    { "value": "vision", "label": "Vision" }
  ],
  "selectedAnswer": ["health"]
}

Verifier	Webhook `selectedAnswer`
Checks nothing	`["health"]`
Checks Dental	`["dental"]`
Checks Health and Vision	`["health", "vision"]`

A non-empty pre-fill must respect minSelections and maxSelections. With maxSelections: 2, ["health", "dental", "vision"] returns 400. Repeated values count once, so ["health", "health"] is one selection. An empty array ([]) is accepted and behaves like no pre-fill, even when minSelections is set.

rating_scale

{
  "questionId": 100013,
  "type": "rating_scale",
  "prompt": "Overall performance",
  "scale": { "min": 1, "max": 5, "minLabel": "Poor", "maxLabel": "Excellent" },
  "selectedAnswer": "4"
}

Verifier	Webhook `selectedAnswer`
Leaves it blank	`"4"`
Writes 2	`"2"`

" 04 " is accepted and stored as "4". 4, "4.0", "4 stars", and values outside the scale return 400.

yes_no

{
  "questionId": 100014,
  "type": "yes_no",
  "prompt": "Was the employee eligible for benefits?",
  "selectedAnswer": "yes"
}

Verifier	Webhook `selectedAnswer`
Leaves it blank	`"Yes"`
Selects No	`"No"`

"Y", "true", and "Maybe" return 400. To allow an “unsure” answer, use single_select with an Unknown option instead.

numeric

A numeric pre-fill is a string, such as "40", "-5", "0", or "37.5". A JSON number like 40 is rejected.

{
  "questionId": 100015,
  "type": "numeric",
  "prompt": "Approximate hours worked per week",
  "selectedAnswer": "40"
}

Verifier	Webhook `selectedAnswer`
Leaves it blank	`"40"`
Writes “20”	`"20"`
Writes “about 20 hours”	`"about 20 hours"`
Writes “n/a”	Escalates as `VERIFICATION_DATA_INVALID`

Pre-fill	Result
`"40"`, `"-5"`, `"0"`, `"37.5"`	Accepted
`40` (JSON number)	`400`
`"+40"`, `"1,000"`, `"1e3"`, `".5"`, `"40."`, `" 40"`	`400`
`"40 hours"`	`400`

Only your pre-fill must be a plain decimal string. A verifier’s answer is returned as written, so it can include units such as "20 hours". A verifier answer that does not start with a number escalates instead of completing. Parse the leading number in your own code.

checkbox

{
  "questionId": 100016,
  "type": "checkbox",
  "prompt": "Records were verified against payroll",
  "required": true,
  "selectedAnswer": "true"
}

Verifier	Webhook `selectedAnswer`
Returns the form with the box unchecked	`"false"`
Returns the form with the box checked	`"true"`
Replies without returning the form, and doesn’t mention it	`"true"`

A checkbox is an attestation, so the returned form always decides it. An unchecked box is reported as "false" even over a "true" pre-fill, because the verifier never saw your pre-fill and did not confirm it. The pre-fill only stands when the verifier answers some other way, such as an email reply without the form. "True", "TRUE", "yes", "1", and true return 400.

Full order example

All seven types on one employment search:

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "emp-2026-0142",
      "verificationQuestions": [
        { "questionId": 100010, "type": "free_text", "prompt": "Department the employee worked in", "selectedAnswer": "Engineering" },
        {
          "questionId": 100011,
          "type": "single_select",
          "prompt": "Eligible for a similar role?",
          "options": [
            { "value": "yes", "label": "Yes" },
            { "value": "no", "label": "No" }
          ],
          "selectedAnswer": "Yes"
        },
        {
          "questionId": 100012,
          "type": "multi_select",
          "prompt": "Which benefits did the employee have?",
          "options": [
            { "value": "health", "label": "Health" },
            { "value": "dental", "label": "Dental" }
          ],
          "selectedAnswer": ["health"]
        },
        { "questionId": 100013, "type": "rating_scale", "prompt": "Overall performance", "scale": { "min": 1, "max": 5 }, "selectedAnswer": "4" },
        { "questionId": 100014, "type": "yes_no", "prompt": "Was the employee eligible for benefits?", "selectedAnswer": "Yes" },
        { "questionId": 100015, "type": "numeric", "prompt": "Approximate hours worked per week", "selectedAnswer": "40" },
        { "questionId": 100016, "type": "checkbox", "prompt": "Records were verified against payroll", "selectedAnswer": "true" }
      ]
    }
  ]
}

If the verifier returns the form with only Dental checked, the custom answers on verification.completed are:

{
  "verificationQuestions": [
    { "questionId": 100010, "origin": "custom", "type": "free_text", "selectedAnswer": "Engineering" },
    { "questionId": 100011, "origin": "custom", "type": "single_select", "selectedAnswer": "yes" },
    { "questionId": 100012, "origin": "custom", "type": "multi_select", "selectedAnswer": ["dental"] },
    { "questionId": 100013, "origin": "custom", "type": "rating_scale", "selectedAnswer": "4" },
    { "questionId": 100014, "origin": "custom", "type": "yes_no", "selectedAnswer": "Yes" },
    { "questionId": 100015, "origin": "custom", "type": "numeric", "selectedAnswer": "40" },
    { "questionId": 100016, "origin": "custom", "type": "checkbox", "selectedAnswer": "false" }
  ]
}

The example is abbreviated: live payloads also include the standard questions, the generated fieldKey, and every request field on each question. Match answers to your questions by questionId.

Interactions with other question settings

`required`

A non-blank pre-fill satisfies required. If the verifier skips a required question that has a pre-fill, the search can still complete with your pre-fill. It does not escalate as MISSING_REQUIRED_INFORMATION. Leave selectedAnswer unset on questions the verifier must answer themselves. These pre-fills do not count as answered:

null
""
a string made only of spaces
[]

A checkbox value of "false" does count as answered.

`condition`

A conditional question only keeps an answer while its condition is met. When a reply is processed and the parent’s answer does not match condition.values, the child’s selectedAnswer is cleared to null, including your pre-fill. This also happens when the parent is left unanswered.

[
  {
    "questionId": 100020,
    "type": "yes_no",
    "prompt": "Did the employee manage a team?",
    "selectedAnswer": "Yes"
  },
  {
    "questionId": 100021,
    "type": "numeric",
    "prompt": "How many direct reports?",
    "condition": { "dependsOn": 100020, "operator": "equals", "values": ["Yes"] },
    "selectedAnswer": "6"
  }
]

Verifier	`100020`	`100021`
Leaves both blank	`"Yes"`	`"6"` (`conditionMet: true`)
Selects No	`"No"`	`null` (`conditionMet: false`)
Writes 9 for direct reports	`"Yes"`	`"9"`

To keep a child’s pre-fill, pre-fill its parent with a matching value as well.

`allowComment` and `comment`

A comment pre-fill follows the same rules as selectedAnswer: a blank comment box keeps it, and a written comment replaces it. When allowComment is false, a comment is still accepted and returned, but the form has no comment box, so the verifier cannot change it.

Standard questions cannot be pre-filled

Standard questions, such as 700001 eligible_for_rehire, cover the core verification fields: rehire eligibility, reason for leaving, dates, and position. Their answers always come from the verifier. A selectedAnswer or comment on a standard question returns 400. This keeps the verifier’s answer and the question in agreement. A verifier can answer rehire eligibility in an email or on a call, and that answer is returned in the verified data (verifiedRehire). It is not written to the standard question, so a pre-fill there could report your value next to a different answer from the verifier. To record something you already know about a standard field, add a custom question for it.

Validation errors

An invalid pre-fill returns 400 Bad Request, and no order is created. See Error handling.

You send	Error message includes
`yes_no` with `"Maybe"`	`selectedAnswer must be "Yes" or "No" (case-insensitive) when provided`
`single_select` with a value that matches no option	`selectedAnswer must match an option value or label when provided`
`multi_select` with a string, a label, or an unknown value	`selectedAnswer must be an array of option values`
`multi_select` with more values than `maxSelections`, or fewer than `minSelections`	`a non-empty selectedAnswer must have between minSelections and maxSelections distinct values`
`rating_scale` with `"9"` on a 1–5 scale, or `"4.0"`	`selectedAnswer must be an integer string within the scale when provided`
`numeric` with `"40 hours"`	`selectedAnswer must be a numeric string when provided`
`checkbox` with `"True"`	`selectedAnswer must be "true" or "false" when provided`
A JSON number or boolean, on any type	`selectedAnswer must be a string or string[]`
A string over 2000 characters	`selectedAnswer must be a string or string[] with each value at most 2000 characters`
A `selectedAnswer` or `comment` on a standard question	`standard question 700001 ("eligible_for_rehire") cannot be pre-filled`

Checklist

Send numeric, rating_scale, and checkbox pre-fills as strings.
Send multi_select pre-fills as an array of exact option values, inside minSelections and maxSelections.
Leave selectedAnswer unset on required questions the verifier must answer themselves.
Pre-fill a conditional question’s parent as well as the child.
Set allowComment: true when you send a comment.
Pre-fill custom questions only. A pre-fill on a standard question returns 400.
Read selectedAnswer by type: a string[] for multi_select, a string or null for everything else.

Core concepts

Guides

Examples

Troubleshooting

Pre-filled answers (selectedAnswer)

Pre-filled answers (`selectedAnswer`)

Before you start

Value shape by question type

What comes back on the webhook

Examples by type

free_text

single_select

multi_select

rating_scale

yes_no

numeric

checkbox

Full order example

Interactions with other question settings

`required`

`condition`

`allowComment` and `comment`

Standard questions cannot be pre-filled

Validation errors

Checklist

​Pre-filled answers (selectedAnswer)

​Before you start

​Value shape by question type

​What comes back on the webhook

​Examples by type

​free_text

​single_select

​multi_select

​rating_scale

​yes_no

​numeric

​checkbox

​Full order example

​Interactions with other question settings

​required

​condition

​allowComment and comment

​Standard questions cannot be pre-filled

​Validation errors

​Checklist

​Related docs

Pre-filled answers (`selectedAnswer`)

Before you start

Value shape by question type

What comes back on the webhook

Examples by type

free_text

single_select

multi_select

rating_scale

yes_no

numeric

checkbox

Full order example

Interactions with other question settings

`required`

`condition`

`allowComment` and `comment`

Standard questions cannot be pre-filled

Validation errors

Checklist

Related docs