VerificationQuestion Schema

Use verification questions to collect employer or institution responses beyond core verification fields (dates, title, degree, and similar). Define custom questions when you create an order; responses are returned on terminal webhooks after the verifier completes the form. Attach questions on each search via searchTypes[].verificationQuestions. See SearchTypeDto.

Download this guide

Prerequisites

Authentication — Bearer token required. See Authentication.
Create order — Questions are sent in the Create order body under each searchTypes[] entry.
Supported search types — EMPLOYMENT and EDUCATION only.

Standard employment and education form fields are always prepended automatically. Custom questions follow in the order you send them.

Integration flow

Define custom questions on each relevant searchTypes[] entry at order creation.
The platform sends a form (PDF and/or online questionnaire link), including custom questions and standard questions.
Responses are extracted from the returned form or eform payload.
On verification.completed, answers appear in data.verificationQuestions (and data.questionnaire). Incomplete or invalid required answers escalate via verification.action_required instead — those paths do not also send verification.completed.

Questions are defined at order creation only. You cannot add or change questions after the order is submitted.

Supported Fields (request)

Send these fields when creating an order. Do not send fieldKey, origin, or conditionMet — the platform assigns those.

Field	Required	Type	Rules and behavior
`questionId`	Yes	`integer`	Stable ID you assign. Minimum `1`. Must be unique within the search’s `verificationQuestions` array.
`type`	Yes	enum	One of: `free_text`, `single_select`, `multi_select`, `rating_scale`, `yes_no`, `numeric`, `checkbox`.
`prompt`	Yes	`string`	Question text shown to the verifier. Length 1–500.
`description`	No	`string`	Helper text under the prompt. Max 500 characters.
`required`	No	`boolean`	Default `false`. When `true` (including with a `condition`), counts as required for channel selection at send time.
`options`	Conditional	`array`	Required for `single_select` and `multi_select`. Each item is `{ value, label }` (1–200 characters each). 1–25 options; `value` must be unique within the array.
`scale`	Conditional	`object`	Required for `rating_scale`. `{ min, max }` with `0 ≤ min < max ≤ 100`. Optional `minLabel` / `maxLabel`.
`minSelections`	No	`integer`	`multi_select` only. `1 ≤ minSelections ≤ maxSelections ≤ options.length`.
`maxSelections`	No	`integer`	`multi_select` only. Same bounds as `minSelections`.
`condition`	No	`object`	One-level dependency. See Conditional questions.
`allowComment`	No	`boolean`	Default `false`. When `true`, the verifier may add a free-text comment.
`selectedAnswer`	No	`string` \| `string[]` \| `null`	Pre-fill. Use `string[]` for `multi_select`; string for other types. Each string ≤ 2000 characters. Default `null`.
`comment`	No	`string` \| `null`	Pre-filled comment. ≤ 2000 characters. Default `null`.

Validation limits

Constraint	Value
Maximum custom questions per search (request)	50
Maximum total questions per search (standard + custom)	50
`questionId`	Integer ≥ 1, unique in the array
`prompt`	1–500 characters
`description`	≤ 500 characters
`options[].value` / `options[].label`	1–200 characters each
`options` array length (`single_select` / `multi_select`)	1–25 items, unique `value` per option
`selectedAnswer` (each string, including array entries)	≤ 2000 characters
`comment`	≤ 2000 characters

Invalid payloads return 400 Bad Request. See Error handling.

Question types

Type	Use when	Verifier input
`free_text`	Open-ended text	Free text
`single_select`	Exactly one choice from a list	One of `options[].value`
`multi_select`	One or more choices from a list	Array of `options[].value`
`rating_scale`	Numeric rating in a range	Integer as string within `scale.min`–`scale.max`
`yes_no`	Binary yes/no	`"Yes"` or `"No"`
`numeric`	Numeric value	Numeric string (e.g. `"42"`, `"3.5"`)
`checkbox`	Boolean flag	`"true"` or `"false"`

Type-specific rules

`type`	`options`	`scale`	`selectedAnswer` (request and response)
`free_text`	Absent	Absent	Any string
`single_select`	Required (≥ 1)	Absent	One of `options[].value`
`multi_select`	Required (≥ 1)	Absent	`string[]` of `options[].value`
`rating_scale`	Absent	Required (`min < max`)	Stringified integer in range
`yes_no`	Absent	Absent	`"Yes"` or `"No"`
`numeric`	Absent	Absent	Numeric string `-?\d+(\.\d+)?` when pre-filled
`checkbox`	Absent	Absent	`"true"` or `"false"` when pre-filled

For single_select and multi_select, matching is case-sensitive against options[].value. Align webhook parsing with those values.

minSelections / maxSelections bounds are enforced whenever the question is present on the returned form — independent of required. If you set minSelections: 1 on an optional (required: false) multi_select question, a verifier who leaves it at zero selections still triggers VERIFICATION_DATA_INVALID (see Incomplete or invalid answers) on PDF/fax/voice inbound paths. To make a multi_select question truly skippable, omit minSelections (or set it only when the question is also required: true).

There is no first-class “unable to answer” path for required free_text or numeric questions. When verifiers may not know the answer, prefer a select type with an Unknown / N/A option.

Conditional questions

Optional condition attaches a one-level dependency on an earlier question:

Field	Type	Description
`dependsOn`	`integer`	`questionId` of the parent. Must appear earlier in the merged questionnaire (custom array order, or a standard question ID).
`operator`	`"equals"` \| `"in"`	How parent answer is compared to `values`.
`values`	`string[]`	Non-empty. For `equals`, the first value is the expected match.

Allowed parent types: yes_no, single_select, checkbox, numeric, rating_scale (not free_text or multi_select). Nesting: One level only — a parent that itself has a condition is rejected. Semantics after extraction:

Parent matches → conditionMet: true; required applies if set.
Parent does not match → conditionMet: false; child selectedAnswer is cleared to null. Excess answers still allow completion when other required fields are satisfied.

Ordering and schema version

Display order = array order of verificationQuestions in the request.
The resolved form is standard questions first, then custom questions in request order.
Questionnaire instances use schemaVersion "1".

Response fields (webhook)

Each question in webhook payloads includes the request fields plus:

Field	Type	Description
`fieldKey`	`string`	Machine-readable key. Standard: fixed slug (e.g. `eligible_for_rehire`). Custom: `q{questionId}_` + slug from prompt (max 127 characters).
`origin`	`"standard"` \| `"custom"`	Platform default vs your request.
`selectedAnswer`	`string` \| `string[]` \| `null`	Extracted answer. `null` if unanswered. Arrays for `multi_select` only.
`comment`	`string` \| `null`	Comment when `allowComment` is true.
`conditionMet`	`boolean`	Present when the question has a `condition`.

Where responses appear

Location	Event	Present when	Contents
`data.verificationQuestions`	`verification.completed`	Questionnaire pinned on the search (always for EMPLOYMENT/EDUCATION)	Flat array with responses (standard + custom, ordered)
`data.questionnaire`	`verification.completed`	Same as above	Full `QuestionnaireInstance`: `{ schemaVersion, searchType, questions }`. `questions` is the same array as `verificationQuestions`.
`metadata.verificationQuestions`	`verification.action_required`	Questionnaire-gate escalations	Partial answered set plus subtype metadata (`missingQuestionIds` / `invalidFields`)

Prefer indexing by fieldKey for standard questions and by questionId (or fieldKey) for custom questions. Always branch on type before reading selectedAnswer — multi_select returns a string[], every other type returns a string or null.

Channel selection and escalations

Outbound does not branch on whether custom questions are required. Email and fax send a verification PDF in parallel when those channels are enabled. The email body includes the questionnaire URL when the search has a non-empty questionnaireUrl.

Situation	Outbound behavior
Email available	Email with verification PDF attached; questionnaire URL in body when present on the search
Fax available	Fax with verification PDF and cover page (no questionnaire URL)
Voice available with email or fax	Voice attempt in parallel with email/fax
Voice only (no email, no fax)	Escalates with `reasonCode: HUMAN_ESCALATION` and `metadata.escalationSubtype: VOICE_ONLY_NOT_SUPPORTED`
No channels available	Escalates — no outbound channels to attempt

Incomplete or invalid answers

On PDF / fax / voice inbound paths (not host-validated eform):

`metadata.escalationSubtype`	When	Extra metadata
`MISSING_REQUIRED_INFORMATION`	Applicable required custom question blank	`missingQuestionIds`, `verificationQuestions` (partial)
`VERIFICATION_DATA_INVALID`	Exclusive multi-marks, out-of-option values, or `multi_select` outside min/max	`invalidFields`, `verificationQuestions` (partial)

These paths emit verification.action_required with reasonCode: HUMAN_ESCALATION and do not emit verification.completed. Online eform completeness for required questions depends on the eform host. Preferred structured payload shape:

{
  "answers": { "<fieldKey>": "string | string[] | null" },
  "comments": { "<fieldKey>": "string" }
}

Standard questions

The platform always prepends standard questions for the search type. Standard questionId values live in a reserved range (700001+ employment, 700101+ education). Collision is keyed by (questionId, fieldKey) against the active standard set:

Exact questionId + fieldKey match → idempotent skip (custom copy ignored)
Same questionId, different fieldKey → 400 Bad Request
Same fieldKey, different questionId → 400 Bad Request

Retired standard IDs (for example former 700003 employment status, 700007 salary, 700101 graduated, 700107 gpa) are reusable as custom IDs. Standard question definitions cannot be overridden.

Employment (`searchType: "EMPLOYMENT"`)

All employment standard questions are optional (required: false).

questionId	fieldKey	Type	Prompt	allowComment
700001	`eligible_for_rehire`	`single_select`	Eligible for Rehire by your organization?	Yes
700002	`reason_for_leaving`	`single_select`	Reason for Leaving?	Yes
700004	`start_date`	`free_text`	Start Date	No
700005	`end_date`	`free_text`	End Date	No
700006	`position_or_degree`	`free_text`	Position	No
700008	`additional_comments`	`free_text`	Additional Comments	No

fieldKey	Allowed `options[].value` values
`eligible_for_rehire`	`Yes`, `No`, `No Comment`, `Info N/A`, `Current Employee`
`reason_for_leaving`	`Terminated`, `Laid Off`, `Voluntary Departure`, `No Comment`, `Info Not Available`, `Current Employee`, `Other`

Education (`searchType: "EDUCATION"`)

All education standard questions are optional (required: false) with allowComment: false.

questionId	fieldKey	Type	Prompt
700102	`graduation_date`	`free_text`	Graduation Date
700103	`start_date`	`free_text`	Start Date
700104	`end_date`	`free_text`	End Date
700105	`position_or_degree`	`free_text`	Degree
700106	`major_or_department`	`free_text`	Major
700110	`graduated`	`single_select`	Graduated?
700108	`honors`	`free_text`	Honors
700109	`additional_comments`	`free_text`	Additional Comments

fieldKey	Allowed `options[].value` values
`graduated`	`Yes`, `No`, `Currently Enrolled`

Internal QuestionnaireInstance

The platform stores questions as a QuestionnaireInstance:

{
  "schemaVersion": "1",
  "searchType": "EMPLOYMENT",
  "questions": [ /* VerificationQuestion[] */ ]
}

On verification.completed, both are present when a questionnaire is pinned:

data.verificationQuestions — the questions array (convenient flat access)
data.questionnaire — the full instance (schemaVersion, searchType, questions)

Examples

Custom questions on order creation

Include a questionnaireUrl when you have required custom questions and a usable email contact — that routes the verifier to your eform instead of a verification PDF.

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT",
      "externalSearchId": "emp-2024-001",
      "questionnaireUrl": "https://verify.example.com/form/abc123",
      "questionnaireAccessCode": "ACCESS123",
      "verificationQuestions": [
        {
          "questionId": 100001,
          "type": "single_select",
          "prompt": "Would you rehire this candidate for a similar role?",
          "required": true,
          "options": [
            { "value": "Yes", "label": "Yes" },
            { "value": "No", "label": "No" },
            { "value": "No Comment", "label": "No Comment" }
          ]
        },
        {
          "questionId": 100002,
          "type": "multi_select",
          "prompt": "Which skills did the candidate demonstrate?",
          "description": "Select all that apply.",
          "required": true,
          "minSelections": 1,
          "maxSelections": 3,
          "options": [
            { "value": "leadership", "label": "Leadership" },
            { "value": "communication", "label": "Communication" },
            { "value": "technical", "label": "Technical" },
            { "value": "unknown", "label": "Unknown / N/A" }
          ]
        },
        {
          "questionId": 100003,
          "type": "free_text",
          "prompt": "Please explain why they are not eligible for rehire.",
          "required": true,
          "condition": {
            "dependsOn": 700001,
            "operator": "equals",
            "values": ["No"]
          }
        },
        {
          "questionId": 100004,
          "type": "yes_no",
          "prompt": "Was the candidate eligible for benefits?",
          "required": false
        },
        {
          "questionId": 100005,
          "type": "rating_scale",
          "prompt": "Overall performance rating",
          "required": false,
          "scale": { "min": 1, "max": 5, "minLabel": "Poor", "maxLabel": "Excellent" }
        },
        {
          "questionId": 100006,
          "type": "numeric",
          "prompt": "Approximate hours worked per week",
          "required": false
        },
        {
          "questionId": 100007,
          "type": "checkbox",
          "prompt": "I confirm the information above is accurate to the best of my knowledge.",
          "required": true
        },
        {
          "questionId": 100008,
          "type": "free_text",
          "prompt": "Additional notes for the hiring team",
          "required": false,
          "allowComment": false,
          "condition": {
            "dependsOn": 100004,
            "operator": "equals",
            "values": ["Yes"]
          }
        }
      ]
    }
  ]
}

In the example above, condition.dependsOn: 700001 targets the standard employment eligible_for_rehire question. 100008 depends on a custom yes_no parent (100004).

Minimal optional questions (no eform required)

When every custom question is optional, channel selection stays on the standard parallel PDF path. You can omit questionnaireUrl:

{
  "searchType": "EDUCATION",
  "externalSearchId": "edu-2024-001",
  "verificationQuestions": [
    {
      "questionId": 200001,
      "type": "yes_no",
      "prompt": "Did the student complete a thesis or capstone?",
      "required": false
    },
    {
      "questionId": 200002,
      "type": "free_text",
      "prompt": "Thesis or capstone title",
      "required": false,
      "condition": {
        "dependsOn": 200001,
        "operator": "equals",
        "values": ["Yes"]
      }
    }
  ]
}

Webhook response (`verification.completed`)

Answers arrive on the completed webhook. data.verificationQuestions is the flat array; data.questionnaire wraps the same questions with schema metadata. Core verification results (verificationResult, employmentVerification / educationVerification) are unchanged — questions are additive.

{
  "event": "verification.completed",
  "occurredAt": "2024-06-15T14:30:00.000Z",
  "data": {
    "searchId": "srch_abc123",
    "externalSearchId": "emp-2024-001",
    "searchType": "EMPLOYMENT",
    "channel": "EMAIL",
    "verificationResult": {
      "outcome": "VERIFIED",
      "discrepancy": false
    },
    "verificationQuestions": [
      {
        "questionId": 700001,
        "fieldKey": "eligible_for_rehire",
        "origin": "standard",
        "type": "single_select",
        "prompt": "Eligible for Rehire by your organization?",
        "required": false,
        "options": [
          { "value": "Yes", "label": "Yes" },
          { "value": "No", "label": "No" },
          { "value": "No Comment", "label": "No Comment" },
          { "value": "Info N/A", "label": "Info N/A" },
          { "value": "Current Employee", "label": "Current Employee" }
        ],
        "allowComment": false,
        "selectedAnswer": "Yes",
        "comment": null
      },
      {
        "questionId": 100001,
        "fieldKey": "q100001_would_you_rehire_this_candidate_for_a_similar_role",
        "origin": "custom",
        "type": "single_select",
        "prompt": "Would you rehire this candidate for a similar role?",
        "required": true,
        "options": [
          { "value": "Yes", "label": "Yes" },
          { "value": "No", "label": "No" },
          { "value": "No Comment", "label": "No Comment" }
        ],
        "allowComment": false,
        "selectedAnswer": "Yes",
        "comment": null
      },
      {
        "questionId": 100002,
        "fieldKey": "q100002_which_skills_did_the_candidate_demonstrate",
        "origin": "custom",
        "type": "multi_select",
        "prompt": "Which skills did the candidate demonstrate?",
        "required": true,
        "options": [
          { "value": "leadership", "label": "Leadership" },
          { "value": "communication", "label": "Communication" },
          { "value": "technical", "label": "Technical" },
          { "value": "unknown", "label": "Unknown / N/A" }
        ],
        "minSelections": 1,
        "maxSelections": 3,
        "allowComment": false,
        "selectedAnswer": ["leadership", "communication"],
        "comment": null
      },
      {
        "questionId": 100003,
        "fieldKey": "q100003_please_explain_why_they_are_not_eligible_for_rehire",
        "origin": "custom",
        "type": "free_text",
        "prompt": "Please explain why they are not eligible for rehire.",
        "required": true,
        "condition": {
          "dependsOn": 700001,
          "operator": "equals",
          "values": ["No"]
        },
        "conditionMet": false,
        "selectedAnswer": null,
        "comment": null
      },
      {
        "questionId": 100005,
        "fieldKey": "q100005_overall_performance_rating",
        "origin": "custom",
        "type": "rating_scale",
        "prompt": "Overall performance rating",
        "required": false,
        "scale": { "min": 1, "max": 5, "minLabel": "Poor", "maxLabel": "Excellent" },
        "selectedAnswer": "4",
        "comment": null
      },
      {
        "questionId": 100007,
        "fieldKey": "q100007_i_confirm_the_information_above_is_accurate_to_the_best_of_my_knowledge",
        "origin": "custom",
        "type": "checkbox",
        "prompt": "I confirm the information above is accurate to the best of my knowledge.",
        "required": true,
        "selectedAnswer": "true",
        "comment": null
      }
    ],
    "questionnaire": {
      "schemaVersion": "1",
      "searchType": "EMPLOYMENT",
      "questions": []
    }
  }
}

In a live payload, questionnaire.questions is the same array as data.verificationQuestions (shown abbreviated as [] above to keep the example readable).

Parsing answers in your handler

function indexAnswers(verificationQuestions = []) {
  const byId = new Map()
  const byKey = new Map()
  for (const q of verificationQuestions) {
    byId.set(q.questionId, q)
    byKey.set(q.fieldKey, q)
  }
  return { byId, byKey }
}

function handleVerificationCompleted(data) {
  const { byId, byKey } = indexAnswers(data.verificationQuestions)

  // Standard field
  const rehire = byKey.get('eligible_for_rehire')?.selectedAnswer // "Yes" | "No" | ...

  // Custom single_select
  const wouldRehire = byId.get(100001)?.selectedAnswer

  // multi_select is always an array (or null)
  const skills = byId.get(100002)?.selectedAnswer // string[] | null
  if (Array.isArray(skills)) {
    // persist skills.join(',') or store as JSON array
  }

  // Conditional child — skip when conditionMet === false
  const explain = byId.get(100003)
  if (explain?.conditionMet === true && explain.selectedAnswer) {
    // store free-text explanation
  }

  // rating_scale / numeric arrive as strings
  const rating = byId.get(100005)?.selectedAnswer // e.g. "4"
  const hours = byId.get(100006)?.selectedAnswer // e.g. "40"

  // checkbox
  const confirmed = byId.get(100007)?.selectedAnswer === 'true'
}

Escalation: missing required answer

{
  "event": "verification.action_required",
  "occurredAt": "2024-06-15T14:30:00.000Z",
  "data": {
    "searchId": "srch_abc123",
    "externalSearchId": "emp-2024-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "HUMAN_ESCALATION",
    "status": "QA Review",
    "channel": "FAX",
    "metadata": {
      "source": "inbound",
      "escalationSubtype": "MISSING_REQUIRED_INFORMATION",
      "missingQuestionIds": [100001],
      "verificationQuestions": [
        {
          "questionId": 100001,
          "fieldKey": "q100001_would_you_rehire_this_candidate_for_a_similar_role",
          "origin": "custom",
          "type": "single_select",
          "prompt": "Would you rehire this candidate for a similar role?",
          "required": true,
          "selectedAnswer": null,
          "comment": null
        }
      ],
      "inboundMessageContext": {
        "from": "hr@employer.example",
        "subject": "Re: Employment verification",
        "bodyPreview": "Please see the attached completed form.",
        "timestamp": "2024-06-15T14:25:00.000Z"
      },
      "artifactUrls": [
        {
          "name": "attachment-1",
          "url": "https://storage.example/signed/verification-form.pdf"
        }
      ]
    }
  }
}

Escalation: invalid answer marks

{
  "event": "verification.action_required",
  "occurredAt": "2024-06-15T14:32:00.000Z",
  "data": {
    "searchId": "srch_abc123",
    "externalSearchId": "emp-2024-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "HUMAN_ESCALATION",
    "status": "QA Review",
    "channel": "EMAIL",
    "metadata": {
      "source": "inbound",
      "escalationSubtype": "VERIFICATION_DATA_INVALID",
      "invalidFields": [
        {
          "fieldKey": "q100002_which_skills_did_the_candidate_demonstrate",
          "reason": "fewer than minSelections (1)"
        }
      ],
      "verificationQuestions": [
        {
          "questionId": 100002,
          "fieldKey": "q100002_which_skills_did_the_candidate_demonstrate",
          "origin": "custom",
          "type": "multi_select",
          "prompt": "Which skills did the candidate demonstrate?",
          "required": true,
          "minSelections": 1,
          "maxSelections": 3,
          "selectedAnswer": [],
          "comment": null
        }
      ]
    }
  }
}

Escalation: voice-only contact

{
  "event": "verification.action_required",
  "occurredAt": "2024-06-15T14:05:00.000Z",
  "data": {
    "searchId": "srch_abc123",
    "externalSearchId": "emp-2024-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "HUMAN_ESCALATION",
    "status": "QA Review",
    "metadata": {
      "escalationSubtype": "VOICE_ONLY_NOT_SUPPORTED",
      "source": "outbound"
    }
  }
}

Route these escalations the same way as other HUMAN_ESCALATION events — alert ops, show escalationSubtype in review UI, and use partial metadata.verificationQuestions when present. See Webhook events.

Implementation notes

Stable IDs — Reuse the same questionId across orders for correlation. Custom fieldKey is derived from the prompt; changing the prompt changes fieldKey.
Pre-fill — Set selectedAnswer / comment at order creation when known. The verifier may still change values on the form.
Parsing — Index by fieldKey for standard questions and by questionId or fieldKey for custom. Use origin to distinguish them. Treat multi_select answers as arrays.
No custom questions — Standard questions still appear on the form and in webhooks (data.verificationQuestions / data.questionnaire).
Escape hatches — For required free_text / numeric there is no built-in “unable to answer” path. Prefer single_select / multi_select with an Unknown / N/A option when verifiers may not know the answer.
Eform preferred payload — When hosting your own questionnaire, post structured answers keyed by fieldKey (see Incomplete or invalid answers).
Delivery — Question answers ride the same webhook delivery path as other terminal events (HMAC signature, retries, idempotency via X-Event-Id). See Webhook integration.

Common integration pitfalls

Pitfall	What happens	Recommendation
Duplicate `questionId`	`400 Bad Request`	Unique IDs within each `verificationQuestions` array
Custom + standard exceed 50	Order creation fails with `400`	Keep standard + custom ≤ 50
Custom `questionId` or `fieldKey` collides with an active standard identity	`400 Bad Request` (or idempotent skip if both `questionId` and `fieldKey` match)	Collision is keyed by `questionId`+`fieldKey` against current standards — retired IDs (e.g. former `700003`) are reusable; avoid reusing active standard IDs or unprefixed standard fieldKeys
Wrong `options[].value` casing	Answers may not match your parser	Match webhook `selectedAnswer` to `value` exactly
Missing `options` on select types	`400 Bad Request`	Include at least one `{ value, label }`
Duplicate `options[].value` within a question	`400 Bad Request`	Each option `value` must be unique for that question
More than 25 `options` on a question	`400 Bad Request`	Split into fewer, broader options or use `free_text`
`selectedAnswer` or `comment` string over 2000 characters	`400 Bad Request`	Trim pre-filled text to ≤ 2000 characters
`minSelections` set on an optional (`required: false`) `multi_select`	Verifier who leaves it blank triggers `VERIFICATION_DATA_INVALID` on PDF/fax/voice inbound	Only set `minSelections` when the question is also `required: true`
Condition on unknown / later parent	`400 Bad Request`	Parent must exist earlier; standard IDs are valid parents
Sending `fieldKey` / `origin` / `conditionMet`	Ignored or rejected	Omit response-only fields on create
Assuming every `selectedAnswer` is a string	Runtime type errors on `multi_select`	Branch on `type === "multi_select"` (array) vs other types (string \| null)
Ignoring `verification.action_required` for CQ gates	Missed incomplete/invalid forms	Handle `MISSING_REQUIRED_INFORMATION`, `VERIFICATION_DATA_INVALID`, and `VOICE_ONLY_NOT_SUPPORTED`
Assuming required CQ skips the email PDF	Missing form attachment	Email always attaches the verification PDF; the questionnaire URL is added to the body when present

FAQ

Are standard questions always included? Yes. Standard employment/education questions are always prepended — even when you send zero custom questions. Custom questions follow in request order. Can I update questions after creating an order? No. Define all questions in the initial Create order request. Questions are immutable after submit. Does multi_select break existing consumers? Only for that type: selectedAnswer is a string[]. Other types remain strings (or null). Update consumers that assume every answer is a string. When do I get data.questionnaire vs only data.verificationQuestions? Both are present together whenever a questionnaire is pinned on the search (EMPLOYMENT and EDUCATION searches). Use whichever shape is more convenient; the question objects are identical. Do questionnaire escalations also send verification.completed? No. Gate escalations (MISSING_REQUIRED_INFORMATION, VERIFICATION_DATA_INVALID) and VOICE_ONLY_NOT_SUPPORTED emit verification.action_required only.

SearchTypeDto — Where verificationQuestions attaches to each search
Create order — Full request body reference
Webhook events — verification.completed and verification.action_required payload reference
Webhook integration — Delivery, signatures, retries, and handler examples
Webhook overview — Lifecycle timing for question responses

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

VerificationQuestion

VerificationQuestion Schema

Prerequisites

Integration flow

Supported Fields (request)

Validation limits

Question types

Type-specific rules

Conditional questions

Ordering and schema version

Response fields (webhook)

Where responses appear

Channel selection and escalations

Incomplete or invalid answers

Standard questions

Employment (`searchType: "EMPLOYMENT"`)

Education (`searchType: "EDUCATION"`)

Internal QuestionnaireInstance

Examples

Custom questions on order creation

Minimal optional questions (no eform required)

Webhook response (`verification.completed`)

Parsing answers in your handler

Escalation: missing required answer

Escalation: invalid answer marks

Escalation: voice-only contact

Implementation notes

Common integration pitfalls

FAQ

​VerificationQuestion Schema

​Prerequisites

​Integration flow

​Supported Fields (request)

​Validation limits

​Question types

​Type-specific rules

​Conditional questions

​Ordering and schema version

​Response fields (webhook)

​Where responses appear

​Channel selection and escalations

​Incomplete or invalid answers

​Standard questions

​Employment (searchType: "EMPLOYMENT")

​Education (searchType: "EDUCATION")

​Internal QuestionnaireInstance

​Examples

​Custom questions on order creation

​Minimal optional questions (no eform required)

​Webhook response (verification.completed)

​Parsing answers in your handler

​Escalation: missing required answer

​Escalation: invalid answer marks

​Escalation: voice-only contact

​Implementation notes

​Common integration pitfalls

​FAQ

​Related documentation

VerificationQuestion Schema

Prerequisites

Integration flow

Supported Fields (request)

Validation limits

Question types

Type-specific rules

Conditional questions

Ordering and schema version

Response fields (webhook)

Where responses appear

Channel selection and escalations

Incomplete or invalid answers

Standard questions

Employment (`searchType: "EMPLOYMENT"`)

Education (`searchType: "EDUCATION"`)

Internal QuestionnaireInstance

Examples

Custom questions on order creation

Minimal optional questions (no eform required)

Webhook response (`verification.completed`)

Parsing answers in your handler

Escalation: missing required answer

Escalation: invalid answer marks

Escalation: voice-only contact

Implementation notes

Common integration pitfalls

FAQ

Related documentation