> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-filled answers (selectedAnswer)

> Send a default answer for a custom verification question, by question type, and see what comes back on the webhook.

# 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](#standard-questions-cannot-be-pre-filled).

[Download this guide](https://documentation.theary.ai/assets/downloads/guides/prefilled-answers.pdf)

Pre-fills are sent on [Create order](https://documentation.theary.ai/api-reference/endpoints/create-order.md), inside `searchTypes[].verificationQuestions[]`. For the full question schema, see [Verification question](https://documentation.theary.ai/api-reference/schemas/verification-question.md).

> [!WARNING]
>
> 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 |

> [!TIP]
>
> 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](https://documentation.theary.ai/webhooks/events.md).

| 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

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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` |

> [!NOTE]
>
> 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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
[
  {
    "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](https://documentation.theary.ai/api-reference/schemas/verification-question.md#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](https://documentation.theary.ai/guides/error-handling.md).

| 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.

## Related docs

* [Verification question](https://documentation.theary.ai/api-reference/schemas/verification-question.md)
* [SearchTypeDto](https://documentation.theary.ai/api-reference/schemas/search-type.md)
* [Create order](https://documentation.theary.ai/api-reference/endpoints/create-order.md)
* [Webhook events](https://documentation.theary.ai/webhooks/events.md)
* [Webhook integration](https://documentation.theary.ai/webhooks/integration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.