​

Search type

​

Fields

​

Search type options

​

Example

{
  "searchType": "EMPLOYMENT",
  "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?",
      "required": true,
      "minSelections": 1,
      "maxSelections": 3,
      "options": [
        { "value": "leadership", "label": "Leadership" },
        { "value": "communication", "label": "Communication" },
        { "value": "technical", "label": "Technical" }
      ]
    },
    {
      "questionId": 100003,
      "type": "free_text",
      "prompt": "What were the candidate's strengths?",
      "required": false
    }
  ]
}

​

Multiple search types

[
  {
    "searchType": "EMPLOYMENT",
    "externalSearchId": "client-emp-001",
    "searchConfig": {
      "thirdPartyBan": ["TALX_WORK_NUMBER"]
    }
  },
  {
    "searchType": "EDUCATION",
    "externalSearchId": "client-edu-001",
    "searchConfig": {
      "thirdPartyBan": ["NSCH"]
    }
  }
]

​

Verification questions behavior

• Standard questions are always prepended; custom questions follow request order.
• A custom question that reuses an active standard questionId with a different fieldKey, or an active standard fieldKey with a different questionId, is rejected with 400 Bad Request. Exact questionId+fieldKey matches are treated as idempotent (the custom copy is skipped). Collision is keyed against the current standard set — retired standard IDs are reusable.
• Conditions may dependsOn earlier custom IDs or standard question IDs.
• Questions are stored as a QuestionnaireInstance (schemaVersion "1"). Webhooks expose both the flat questions array (data.verificationQuestions) and the full instance (data.questionnaire).
• Maximum 50 total questions (standard + custom).

• Usable email + questionnaireUrl set → email includes both verification PDF and questionnaire link in body; fax sends PDF; voice attempts a call when paired with email or fax.
• Usable email, no questionnaireUrl → email still includes the verification PDF (no link in the body).
• Fax only → fax PDF path.
• Voice only → HUMAN_ESCALATION with VOICE_ONLY_NOT_SUPPORTED.

​

Validation rules

• Enum validation: searchType must be EMPLOYMENT or EDUCATION.
• verificationQuestions: Maximum 50 items. Unique questionId per array. Type-specific rules (options for select types, scale for rating_scale, condition graph, minSelections / maxSelections for multi_select) are validated at order creation.
• searchConfig: if present (even as {}) it fully replaces any request-level defaultSearchConfig for this search.
• thirdPartyBan: when set inside searchConfig, values must be canonical vendor codes. See Third-party ban.

​

Related schemas

• Verification question — Question type definitions, channel selection, and webhook output format
• Webhook events — Where answers and questionnaire escalations appear
• Verification request — Main verification request schema
• Create Order — Full field reference tables
• Third-party ban — Client guide for vendor-specific third-party suppression