Webhook Events

SNH AI delivers webhook events to notify your application about verification status changes in real-time. This document provides comprehensive documentation of all event types, payload structures, field definitions, and examples from the actual verification system.

Payload Structure

All webhook events follow a consistent structure with three top-level fields:

{
  "event": "<WebhookEventType>",
  "occurredAt": "<ISO 8601 timestamp>",
  "data": {
    /* Event-specific payload */
  }
}

Top-Level Fields

Field	Type	Required	Description
`event`	`WebhookEventType`	Yes	Event type identifier. One of: `verification.completed`, `verification.action_required`, `verification.notification`
`occurredAt`	`string` (ISO 8601)	Yes	Timestamp when the event was generated (server time)
`data`	`object`	Yes	Event-specific payload. Structure varies by event type

Payload Enrichment

The system automatically enriches webhook payloads with additional context: For all events with searchId:

externalSearchId: Your external identifier provided at order creation

For terminal events (verification.completed, verification.action_required):

channel: Single terminal channel used (EMAIL, VOICE, FAX, or JSON)
Root-level highest-confidence employmentVerification or educationVerification objects containing both per-field comparison in fields and backward-compatible flat provided* / verified* properties — not nested in verificationResult or metadata.extractedData
message (JSON-channel verification.action_required with status: "QA Review" only): Human-readable review summary for client UI — plain-text breakdown of each third-party history record when _processedFromJson is true. Not present on EMAIL, FAX, or VOICE action-required webhooks (including status: "QA Review"). EMAIL/FAX/VOICE verified inbound with field conflicts typically close via verification.completed and verificationResult.discrepancy: true instead.
discrepancy (on verification.completed only): Operational closeout flag on verificationResult; may be false when the best-match row only has non-critical match_with_discrepancy field statuses under tenant comparison settings

For inbound detail notifications (verification.notification with INBOUND_RECEIVED_DETAIL):

Root-level employmentVerification or educationVerification when normalized rows are available, with both fields comparison metadata and backward-compatible flat properties
Scalar extraction under metadata.extractedData without duplicate verification objects or removed applicantMismatches / applicantDiscrepancies objects
Optional applicantMismatch / _requiresManualReview boolean flags when escalation is triggered

Verification fields temporarily return one object for backward compatibility. A future version will return sorted employmentVerification and educationVerification arrays after consumers migrate to the array contract.

For EDUCATION searches:

accreditation: Institutional accreditation outcome (education searches only)

WebhookEventType Enum

Value	Description
`verification.completed`	Verification search completed with results
`verification.action_required`	Verification requires manual intervention
`verification.notification`	Intermediate notification during verification process

Pause/resume outbound updates are delivered as verification.notification with notificationType values such as OUTBOUND_PAUSED, OUTBOUNDS_PAUSED, OUTBOUND_RESUMED, and OUTBOUNDS_RESUMED.

HTTP Headers

Every webhook request includes these headers:

Header	Type	Description
`Content-Type`	`string`	Always `application/json`
`X-Event-Type`	`WebhookEventType`	Event type (e.g., `verification.completed`)
`X-Event-Id`	`string` (UUID)	Unique delivery identifier for idempotency
`X-Search-Type`	`SearchType`	Search type when available (e.g., `EMPLOYMENT`)
`X-External-Search-Id`	`string`	External identifier provided at order creation
`X-Endpoint-Source`	`string`	Routing source: `type-specific` or `fallback`
`User-Agent`	`string`	Always `Theary-Webhook-Delivery/1.0`¹
`Authorization`	`string`	Basic auth header when configured (format: `Basic <base64>`)
`X-Webhook-Signature`	`string`	HMAC-SHA256 signature when secret is configured

Signature Verification

Webhooks are signed with HMAC-SHA256 (X-Webhook-Signature: sha256=<hex>). Always verify using the raw request body bytes. Full verification examples (Node.js, Python, OpenSSL) live in Webhook Integration.

Common Enums

SearchType

Value	Description
`EMPLOYMENT`	Employment verification
`EDUCATION`	Education/credential verification

VerificationChannel

Value	Description
`EMAIL`	Email communication channel
`VOICE`	Phone/voice communication channel
`FAX`	Fax communication channel
`JSON`	Structured third-party JSON inbound channel

StandardOutcomeCode

Value	Terminal	Description
`VERIFIED`	Yes	Information successfully verified
`NO_RECORD`	Yes	No record found for the subject
`THIRD_PARTY`	Yes	Requires third-party vendor completion
`WRONG_ORG`	Yes	Request misdirected to wrong organization
`INFO_REQUESTED`	No	Additional information requested
`INSUFFICIENT`	No	Insufficient information to proceed
`RECEIVED`	No	Request received, processing
`STARTED`	No	Verification process started
`SENT`	No	Outbound communication sent
`FAILED`	No	Attempt failed (retryable)
`SUPPRESSED`	No	Communication suppressed

Event: verification.completed

Sent when a verification search completes with results.

Data Fields

Field	Type	Required	Description
`searchId`	`string` (UUID)	Yes	Unique search identifier
`verificationId`	`string` (UUID)	Yes	Verification result identifier
`externalSearchId`	`string`	No	External identifier from order creation
`searchType`	`SearchType`	No	Type of verification performed
`status`	`string`	No	Human-readable status (e.g., `QA Review`, `Completed`)
`channel`	`VerificationChannel`	No	Terminal channel that completed the verification
`verificationResult`	`VerificationResult`	Yes	Complete verification result object
`verificationQuestions`	`VerificationQuestion[]`	No	All verification question responses (standard + custom). Present when the search has a pinned questionnaire (EMPLOYMENT/EDUCATION). Each item includes `fieldKey`, `origin`, and `selectedAnswer` (`string` \| `string[]` \| `null`; arrays for `multi_select`). Conditional questions may include `conditionMet`. See Verification question.
`questionnaire`	`QuestionnaireInstance`	No	Full pinned questionnaire instance (`schemaVersion`, `searchType`, `questions`) when present. Same question objects as `verificationQuestions`; provided for consumers that need schema metadata. Absent when no questionnaire is pinned.
`employmentVerification`	`EmploymentVerification`	Conditional	Root-level highest-confidence normalized employment object for `EMPLOYMENT` searches. Includes `fields` and backward-compatible flat fields. Not duplicated under `verificationResult`.
`educationVerification`	`EducationVerification`	Conditional	Root-level highest-confidence normalized education object for `EDUCATION` searches. Not duplicated under `verificationResult`.
`accreditation`	`AccreditationResult`	No	Accreditation data (education searches only)

VerificationResult Object

Field	Type	Required	Description
`id`	`string` (UUID)	Yes	Verification result primary key
`searchId`	`string` (UUID)	Yes	Associated search ID
`outcome`	`StandardOutcomeCode`	Yes	Verification outcome
`resultDetails`	`string` or `object`	No	Raw extraction data (JSON)
`extractedData`	`object`	No	Parsed extraction data. For `JSON` channel, includes best-match scalar fields (`employerName`, `jobTitle`, dates, `verifiedDates`, `verifiedContent`, optional `extraction` duplicate for backward compatibility), `_processedFromJson`, `_thirdPartyProvider`, and optional comparison flags — but not duplicate verification objects (see root-level `employmentVerification` / `educationVerification`). May include serialized `resultDetails`. See submit-inbound-notification
`submittedAt`	`string` (ISO 8601)	No	When result was submitted
`createdAt`	`string` (ISO 8601)	No	Record creation timestamp
`updatedAt`	`string` (ISO 8601)	No	Record update timestamp
`channel`	`VerificationChannel`	No	Channel that produced the result
`additionalComments`	`string`	No	Free-form notes from verification
`discrepancy`	`boolean`	No	Operational closeout flag. May be `false` when the selected object has `fields.*.status: "match_with_discrepancy"` under tenant comparison settings; use root-level `employmentVerification.fields` for field detail.
`verifier`	`VerifierProfile`	No	Verifier contact information

VerifierProfile Object

Field	Type	Required	Description
`firstName`	`string`	No	Verifier’s first name
`lastName`	`string`	No	Verifier’s last name
`position`	`string`	No	Verifier’s job title or role

Verification questions on completed events

EMPLOYMENT and EDUCATION searches pin a questionnaire (standard questions always; custom questions when you send verificationQuestions at order creation). On verification.completed, answers appear in:

Field	Shape	Use when
`data.verificationQuestions`	`VerificationQuestion[]`	Flat list of standard + custom answers
`data.questionnaire`	`{ schemaVersion, searchType, questions }`	Same questions plus schema metadata

Each question includes request fields plus fieldKey, origin ("standard" | "custom"), selectedAnswer, comment, and optional conditionMet. Answer shapes by type:

`type`	`selectedAnswer`
`multi_select`	`string[]` of option values, or `null`
`yes_no`	`"Yes"` \| `"No"` \| `null`
`checkbox`	`"true"` \| `"false"` \| `null`
`rating_scale` / `numeric`	Numeric string (e.g. `"4"`, `"40"`) or `null`
All other types	`string` \| `null`

Incomplete or invalid required answers on PDF/fax/voice inbound do not produce verification.completed — they escalate via verification.action_required instead (see Questionnaire-related metadata). Full authoring rules, channel selection, and request examples: Verification question.

Example: completed payload with custom question answers

{
  "event": "verification.completed",
  "occurredAt": "2025-12-02T11:45:00.000Z",
  "data": {
    "searchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "verificationId": "v1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalSearchId": "emp-cq-001",
    "searchType": "EMPLOYMENT",
    "status": "Completed",
    "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,
        "minSelections": 1,
        "maxSelections": 3,
        "options": [
          { "value": "leadership", "label": "Leadership" },
          { "value": "communication", "label": "Communication" },
          { "value": "technical", "label": "Technical" }
        ],
        "allowComment": false,
        "selectedAnswer": ["leadership", "technical"],
        "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" },
        "allowComment": false,
        "selectedAnswer": "4",
        "comment": null
      }
    ],
    "questionnaire": {
      "schemaVersion": "1",
      "searchType": "EMPLOYMENT",
      "questions": []
    }
  }
}

In a live payload, questionnaire.questions matches verificationQuestions exactly (abbreviated as [] above).

Understanding Provided vs Verified Fields

The verification system tracks two sets of data for each verification: Provided Fields (provided*):

Information submitted by the applicant or requester at order creation
Stored in the search metadata from the original request
Used as the basis for verification and comparison
Never modified during the verification process

Verified Fields (verified*):

Information confirmed through the verification process
Extracted from employer/institution responses (email, voice, fax, or structured JSON inbound)
Represents the ground truth according to the verifying organization
May differ from provided fields (discrepancies)

Discrepancy Detection: For VERIFIED outcomes, the system automatically compares key fields and sets the discrepancy boolean:

false: All key fields match between provided and verified data, or differences are treated as non-critical under tenant comparison settings (including semantic match_with_discrepancy on fields such as position or location)
true: One or more key fields differ beyond configured tolerances (e.g., date gaps outside calendar-day windows, salary beyond absolute/percent thresholds, critical title or name conflicts)

Provider payloads can contain multiple records internally. External payloads expose only the highest-confidence record as employmentVerification or educationVerification; its fields drive verificationResult.discrepancy and scalar fields in verificationResult.extractedData. The comparison uses normalized values (case-insensitive, whitespace-trimmed, date formats normalized) to avoid false positives from formatting differences. Inbound responses are also checked against the applicant and the employment or education details supplied at order creation. These checks use tenant-level comparison settings (config.comparisonConfig), including calendar-day tolerance windows per date field, semantic equivalence checks for applicant name, job title, degree, major, and location proximity, and for employment salary optional absolute and percent thresholds: when both providedSalary and the verifier-extracted salary parse, they are normalized to an estimated annual USD equivalent and a salary conflict is raised only if the difference exceeds both thresholds; unparseable salary text falls back to normalized string comparison. Date and salary mismatch explanations include the raw expected and extracted values (salary reasons also include the computed annual amounts). Default config.comparisonConfig values (used when a field is omitted or invalid on the tenant settings):

Field	Default	Meaning
`fullNameSemanticEquivalenceThreshold`	`0.9`	Similarity floor for applicant name
`organizationNameSemanticEquivalenceThreshold`	`0.9`	Similarity floor for company / school name
`organizationNameSimilarityThreshold`	`0.9`	Deterministic org-name similarity floor (accept without AI)
`organizationNameLlmFallbackSimilarityThreshold`	`0.75`	Lower bound for invoking AI org-name fallback
`jobTitleSemanticEquivalenceThreshold`	`0.9`	Similarity floor for job title / position
`locationSemanticEquivalenceThreshold`	`0.9`	Similarity floor for location proximity
`degreeSemanticEquivalenceThreshold`	`0.9`	Similarity floor for degree
`majorSemanticEquivalenceThreshold`	`0.9`	Similarity floor for major
`startDateThreshold`	`1`	Allowed calendar-day difference for start date
`endDateThreshold`	`1`	Allowed calendar-day difference for end date
`graduationDateThreshold`	`1`	Allowed calendar-day difference for graduation date
`salaryAbsoluteThreshold`	`1000`	Absolute annual-USD tolerance
`salaryPercentThreshold`	`0.03`	Relative annual-USD tolerance (3%)

{
  "comparisonConfig": {
    "fullNameSemanticEquivalenceThreshold": 0.9,
    "organizationNameSemanticEquivalenceThreshold": 0.9,
    "organizationNameSimilarityThreshold": 0.9,
    "organizationNameLlmFallbackSimilarityThreshold": 0.75,
    "jobTitleSemanticEquivalenceThreshold": 0.9,
    "locationSemanticEquivalenceThreshold": 0.9,
    "degreeSemanticEquivalenceThreshold": 0.9,
    "majorSemanticEquivalenceThreshold": 0.9,
    "startDateThreshold": 1,
    "endDateThreshold": 1,
    "graduationDateThreshold": 1,
    "salaryAbsoluteThreshold": 1000,
    "salaryPercentThreshold": 0.03
  }
}

When values are semantically similar above the configured similarity threshold, the response can still be treated as a match even if the exact strings differ (for example, equivalent degree names or job-title variants). Critical conflicts are reflected through the normal verification review and discrepancy flow; clients should rely on verificationResult.discrepancy, root-level employmentVerification.fields, and verification/action-required webhook status rather than removed applicantMismatches / applicantDiscrepancies objects. JSON channel closeout: For terminal verification.completed events where channel is JSON, verificationResult.extractedData retains best-match scalar fields and _processedFromJson / _thirdPartyProvider. Comparison for the selected highest-confidence record lives on root-level employmentVerification.fields. Duplicate verification data is removed from nested verificationResult objects. verificationResult.discrepancy is the operational closeout flag — it may be false even when the selected record includes fields.position.status: "match_with_discrepancy". verificationResult.search includes nested order/applicant context; See submit-inbound-notification for the inbound vs closeout comparison model. Why This Matters: Discrepancies may indicate:

Minor differences in how information is recorded (e.g., “Software Engineer” vs “Sr. Software Engineer”)
Applicant inaccuracies (intentional or unintentional)
Incomplete or outdated information from either source
Data entry errors on either side

Your system should review discrepancies and decide how to handle them based on your business rules.

EmploymentVerification Object

Complete employment verification data with both the canonical fields comparison object and backward-compatible flat provided* / verified* fields. Payload shape: All channels (EMAIL, FAX, VOICE, and JSON) use a fields object with per-field comparison metadata (type, status, expected, extracted, optional reason, and comparison with engine / similarity / distance). Legacy flat fields remain for existing consumers. The highest-confidence employmentVerification object appears at the data root in webhook payloads, not inside metadata.extractedData or verificationResult. Synchronous inbound API responses likewise return it at the response root.

Fields-based comparison (`fields`)

Used consistently across channels. Each key under fields compares order data (expected) to the verifier-extracted value (extracted).

Field key	`type`	Description
`companyName`	`string`	Employer name
`position`	`string`	Job title
`startDate`	`date`	Employment start date
`endDate`	`date`	Employment end date
`location`	`string`	Employer location
`applicantName`	`string`	Name on the verification record
`salary`	`number`	Compensation (when present on the provider row)
`rehire`	`boolean`	Rehire eligibility
`reasonLeft`	`string`	Reason for leaving
`contactName`	`string`	Verifier contact name
`contactNumber`	`string`	Verifier contact phone
`contactEmail`	`string`	Verifier contact email

Each field object has the following shape:

Field	Type	Required	Description
`type`	`string`, `date`, `number`, or `boolean`	Yes	Data type used to compare and interpret the field values.
`status`	`match`, `mismatch`, `match_with_discrepancy`, or `not_checked`	Yes	Result of comparing `expected` with `extracted`.
`expected`	`string`, `number`, `boolean`, or `null`	Yes	Value supplied on the order. `null` means no expected value was available.
`extracted`	`string`, `number`, `boolean`, or `null`	Yes	Value extracted from the verifier or provider response. `null` means no value was extracted.
`reason`	`string`	No	Human-readable explanation for the comparison result, especially semantic discrepancies and mismatches.
`comparison`	`object`	Yes	Comparison-engine metadata described by the fields below.
`comparison.engine`	`deterministic`, `probabilistic`, or `none`	Yes	Method used to compare values. `none` is used when the field was not checked.
`comparison.similarity`	`number`	No	String-comparison score from 0–1. Deterministic exact string matches use `1`; string mismatches use the evaluated score or `0` when no score is available.
`comparison.distance`	`number`	No	Absolute difference for date and number comparisons. Dates use calendar days; numbers use the normalized numeric difference. Exact matches use `0`. Not used for strings.
`comparison.confidence`	`number`	No	Optional confidence score from the comparison engine when one is available.

Backward-compatible flat fields

These fields mirror values in fields.*.expected and fields.*.extracted. They remain available for clients using the original verification-object contract; new comparison logic should use fields. Provided fields

Field	Type	Description
`providedCompanyName`	`string`	Claimed employer name
`providedContactName`	`string`	Contact name provided
`providedContactNumber`	`string`	Contact phone provided
`providedContactEmail`	`string`	Contact email provided
`providedLocation`	`string`	Employer location
`providedStartDate`	`string`	Claimed employment start date
`providedEndDate`	`string`	Claimed employment end date
`providedPosition`	`string`	Claimed job title
`providedSalary`	`string`	Claimed compensation
`providedApplicantName`	`string`	Applicant name on the order
`providedReasonLeft`	`string`	Claimed reason for leaving
`providedAddress1`	`string`	Employer address line 1
`providedAddress2`	`string`	Employer address line 2
`providedCity`	`string`	Employer city
`providedState`	`string`	Employer state
`providedZip`	`string`	Employer postal code

Verified and metadata fields

Field	Type	Description
`verifiedEntityId`	`string`	Internal employer entity ID
`verifiedCompanyName`	`string`	Confirmed employer name
`verifiedContactName`	`string`	Name of person who verified
`verifiedContactNumber`	`string`	Verified contact phone
`verifiedContactEmail`	`string`	Verified contact email
`verifiedLocation`	`string`	Confirmed employer location
`verifiedPosition`	`string`	Confirmed job title
`verifiedSalary`	`string`	Confirmed compensation
`verifiedContactId`	`string`	Internal contact entity ID
`verifiedStartDate`	`string`	Confirmed start date
`verifiedEndDate`	`string`	Confirmed end date
`verifiedReasonLeft`	`string`	Reason for leaving employment
`verifiedRehire`	`boolean` or `null`	Rehire eligibility
`verifiedApplicantName`	`string`	Applicant name on the provider record
`comments`	`string`	Additional verifier comments
`doNotContact`	`boolean`	Do-not-contact flag from request
`verifierFirstName`	`string`	Verifier first name
`verifierLastName`	`string`	Verifier last name
`verifierPosition`	`string`	Verifier job title
`confidence`	`number`	JSON history-row match score, sorted descending

Example: Employment Verification (Email — synchronous inbound response)

{
  "messageId": "local-inbound-comparison-test-2",
  "success": true,
  "classification": {
    "type": "VERIFICATION",
    "confidence": 0.85,
    "reasoning": "Entity verification"
  },
  "extractedData": {
    "outcome": "verified",
    "confidence": "medium",
    "company": "Pablo's Pizza",
    "verifier": {},
    "verifiedContent": {
      "positionTitle": "Senior Software Developer"
    },
    "verifiedDates": {
      "startDate": "2022-01-01",
      "endDate": "2023-01-01"
    },
    "notes": {
      "attempts": []
    },
    "already_verified_closed": false,
    "intention": "VERIFICATION",
    "extractedApplicantName": "John Smith",
    "employerName": "Pablo's Pizza",
    "jobTitle": "Senior Software Developer",
    "salary": "100000",
    "additionalNotes": "Email confirms employment at Pablo's Pizza for John Smith in the stated role and dates, with salary of 100000.",
    "startDate": "2022-01-01",
    "endDate": "2023-01-01",
    "extraction": {
      "outcome": "verified",
      "confidence": "medium",
      "company": "Pablo's Pizza",
      "verifier": {},
      "verifiedContent": {
        "positionTitle": "Senior Software Developer"
      },
      "verifiedDates": {
        "startDate": "2022-01-01",
        "endDate": "2023-01-01"
      },
      "notes": {
        "attempts": []
      },
      "already_verified_closed": false,
      "intention": "VERIFICATION",
      "extractedApplicantName": "John Smith",
      "employerName": "Pablo's Pizza",
      "jobTitle": "Senior Software Developer",
      "salary": "100000",
      "additionalNotes": "Email confirms employment at Pablo's Pizza for John Smith in the stated role and dates, with salary of 100000.",
      "startDate": "2022-01-01",
      "endDate": "2023-01-01"
    },
    "refId": "EXT-DEV-1781045734449-1",
    "searchType": "EMPLOYMENT",
    "contactType": "ENTITY",
    "attachments": []
  },
  "employmentVerification": {
    "fields": {
      "companyName": {
        "expected": "Pablo's Pizza",
        "extracted": "Pablo's Pizza",
        "reason": "exact match",
        "status": "match",
        "type": "string",
        "comparison": {
          "engine": "deterministic",
          "similarity": 1
        }
      },
      "location": {
        "expected": "Grand Junction, CO",
        "extracted": "Grand Junction, CO",
        "reason": "exact match",
        "status": "match",
        "type": "string",
        "comparison": {
          "engine": "deterministic",
          "similarity": 1
        }
      },
      "position": {
        "expected": "Senior Software Engineer",
        "extracted": "Senior Developer",
        "reason": "The titles describe the same role with a seniority difference.",
        "status": "match_with_discrepancy",
        "type": "string",
        "comparison": {
          "engine": "probabilistic",
          "similarity": 0.92
        }
      },
      "salary": {
        "expected": "100000",
        "extracted": "100000",
        "reason": "within configured salary threshold",
        "status": "match",
        "type": "number",
        "comparison": {
          "engine": "deterministic",
          "distance": 0
        }
      },
      "startDate": {
        "expected": "2022-01-01",
        "extracted": "2022-01-01",
        "reason": "exact match",
        "status": "match",
        "type": "date",
        "comparison": {
          "engine": "deterministic",
          "distance": 0
        }
      },
      "endDate": {
        "expected": "2024-06-30",
        "extracted": "2024-06-15",
        "reason": "Dates differ by 15 calendar days, exceeding the configured threshold.",
        "status": "mismatch",
        "type": "date",
        "comparison": {
          "engine": "deterministic",
          "distance": 15
        }
      },
      "reasonLeft": {
        "expected": null,
        "extracted": null,
        "status": "not_checked",
        "type": "string",
        "comparison": {
          "engine": "none"
        }
      },
      "rehire": {
        "expected": null,
        "extracted": null,
        "status": "not_checked",
        "type": "boolean",
        "comparison": {
          "engine": "none"
        }
      },
      "applicantName": {
        "expected": "John Smith",
        "extracted": "John Smith",
        "reason": "exact match",
        "status": "match",
        "type": "string",
        "comparison": {
          "engine": "deterministic",
          "similarity": 1
        }
      }
    },
    "verifiedEntityId": null,
    "verifiedContactId": null,
    "providedAddress1": null,
    "providedAddress2": null,
    "providedCity": null,
    "providedState": null,
    "providedZip": null,
    "doNotContact": false,
    "comments": "Email confirms employment at Pablo's Pizza for John Smith in the stated role and dates, with salary of 100000.",
    "verifierFirstName": null,
    "verifierLastName": null,
    "verifierPosition": null
  },
  "metadata": {
    "contactAnalysis": "ENTITY",
    "searchId": "ae98cdb9-e7b9-4a44-b4e2-d4aa565a2f66",
    "referenceNumbers": ["EXT-DEV-1781045734449-1"],
    "channel": "EMAIL"
  },
  "processedAt": "2026-06-09T23:42:32.105Z"
}

Example: Employment Verification (Voice)

{
  "event": "verification.completed",
  "occurredAt": "2025-12-02T11:45:00.000Z",
  "data": {
    "searchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "externalSearchId": "emp-verify-456",
    "searchType": "EMPLOYMENT",
    "status": "Completed",
    "channel": "VOICE",
    "verificationResult": {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "searchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "outcome": "VERIFIED",
      "submittedAt": "2025-12-02T11:45:00.000Z",
      "createdAt": "2025-12-02T11:30:00.000Z",
      "updatedAt": "2025-12-02T11:45:00.000Z",
      "channel": "VOICE",
      "additionalComments": "Verified via phone call with HR department",
      "discrepancy": true,
      "extractedData": {
        "employmentVerified": true,
        "employerName": "Tech Solutions Inc",
        "jobTitle": "Senior Developer",
        "startDate": "2019-03-01",
        "endDate": "2024-06-15",
        "confidence": 0.92
      },
      "verifier": {
        "firstName": "James",
        "lastName": "Wilson",
        "position": "HR Coordinator"
      }
    },
    "employmentVerification": {
      "fields": {
        "companyName": {
          "expected": "Tech Solutions",
          "extracted": "Tech Solutions Inc",
          "reason": "The employer names refer to the same organization.",
          "status": "match_with_discrepancy",
          "type": "string",
          "comparison": {
            "engine": "probabilistic",
            "similarity": 0.95
          }
        },
        "location": {
          "expected": "Austin, TX",
          "extracted": "Austin, TX",
          "reason": "exact match",
          "status": "match",
          "type": "string",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "position": {
          "expected": "Senior Software Engineer",
          "extracted": "Senior Developer",
          "reason": "The titles describe the same role with a seniority difference.",
          "status": "match_with_discrepancy",
          "type": "string",
          "comparison": {
            "engine": "probabilistic",
            "similarity": 0.92
          }
        },
        "salary": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "number",
          "comparison": {
            "engine": "none"
          }
        },
        "startDate": {
          "expected": "2019-03-15",
          "extracted": "2019-03-01",
          "reason": "Dates differ by 14 calendar days, exceeding the configured threshold.",
          "status": "mismatch",
          "type": "date",
          "comparison": {
            "engine": "deterministic",
            "distance": 14
          }
        },
        "endDate": {
          "expected": "2024-06-30",
          "extracted": "2024-06-15",
          "reason": "Dates differ by 15 calendar days, exceeding the configured threshold.",
          "status": "mismatch",
          "type": "date",
          "comparison": {
            "engine": "deterministic",
            "distance": 15
          }
        },
        "reasonLeft": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "rehire": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "boolean",
          "comparison": {
            "engine": "none"
          }
        },
        "applicantName": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        }
      },
      "verifiedEntityId": null,
      "verifiedContactId": null,
      "providedAddress1": null,
      "providedAddress2": null,
      "providedCity": "Austin",
      "providedState": "TX",
      "providedZip": null,
      "comments": "Title was Senior Developer, not Developer. Start date was March 1, not March 15.",
      "doNotContact": false,
      "verifierFirstName": "James",
      "verifierLastName": "Wilson",
      "verifierPosition": "HR Coordinator"
    }
  }
}

Example: Employment Verification (JSON channel)

JSON closeouts emit the highest-confidence root-level employmentVerification object with per-field comparison metadata in fields. verificationResult.extractedData retains scalar extraction for the selected record but omits duplicate verification data. verificationResult.discrepancy is the operational closeout flag; individual fields may still show match_with_discrepancy (for example fields.position) when semantic equivalence applies under tenant comparison settings. verificationResult.search includes nested order/applicant context.

{
  "event": "verification.completed",
  "occurredAt": "2026-06-09T22:54:14.053Z",
  "data": {
    "channel": "JSON",
    "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
    "searchType": "EMPLOYMENT",
    "verificationId": "649b9aaa-8881-41a4-af5a-ff68cfb58f8b",
    "externalSearchId": "EXT-DEV-1781042158637-1",
    "verificationResult": {
      "id": "649b9aaa-8881-41a4-af5a-ff68cfb58f8b",
      "search": {
        "id": "86bc0a43-6a10-4f85-a093-e4244ed78107",
        "orderId": "41cbeede-cb65-4239-acad-aa4ae931afdc",
        "metadata": {
          "searchConfig": {
            "channels": {
              "fax": true,
              "email": true,
              "voice": false
            }
          },
          "businessContext": {
            "worksiteCity": "Grand Junction",
            "worksiteState": "CO"
          },
          "historyItemIndex": 0
        },
        "createdAt": "2026-06-09T21:55:58.670Z",
        "updatedAt": "2026-06-09T21:56:31.336Z",
        "searchType": "EMPLOYMENT",
        "applicantId": "808ab489-8545-4b20-810f-59e893d44359",
        "completedAt": "2026-06-09T21:56:31.335Z",
        "displayName": null,
        "displayValue": null,
        "searchStatus": "COMPLETED",
        "externalSearchId": "EXT-DEV-1781042158637-1",
        "questionnaireUrl": null,
        "verificationOrder": {
          "id": "41cbeede-cb65-4239-acad-aa4ae931afdc",
          "applicant": {
            "id": "808ab489-8545-4b20-810f-59e893d44359",
            "ssn": "123-45-6789",
            "email": null,
            "phone": "+1-555-123-4567",
            "birthday": "1990-05-15T00:00:00.000Z",
            "lastName": "Smith",
            "createdAt": "2026-06-09T21:55:58.651Z",
            "firstName": "John",
            "updatedAt": "2026-06-09T21:55:58.651Z",
            "isRedacted": false
          },
          "createdAt": "2026-06-09T21:55:58.661Z",
          "updatedAt": "2026-06-09T22:51:45.711Z",
          "applicantId": "808ab489-8545-4b20-810f-59e893d44359",
          "orderStatus": "COMPLETED",
          "proposedSalary": 100000,
          "proposedPosition": "Senior Software Developer"
        },
        "additionalComments": null,
        "signedReleaseFileUrl": "https://example.com/signed-release.pdf",
        "questionnaireAccessCode": null
      },
      "channel": "JSON",
      "outcome": "VERIFIED",
      "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
      "createdAt": "2026-06-09T21:56:31.326Z",
      "updatedAt": "2026-06-09T22:54:14.027Z",
      "discrepancy": false,
      "submittedAt": null,
      "extractedData": {
        "notes": {
          "attempts": []
        },
        "refId": "EXT-DEV-1781042158637-1",
        "company": "Pablos Pizza",
        "endDate": "2023-01-01",
        "outcome": "verified",
        "jobTitle": "Senior Software Engineer",
        "verifier": {},
        "intention": "VERIFICATION",
        "startDate": "2022-01-01",
        "confidence": "medium",
        "extraction": {
          "notes": {
            "attempts": []
          },
          "company": "Pablos Pizza",
          "endDate": "2023-01-01",
          "outcome": "verified",
          "jobTitle": "Senior Software Engineer",
          "verifier": {},
          "intention": "VERIFICATION",
          "startDate": "2022-01-01",
          "confidence": "medium",
          "employerName": "Pablos Pizza",
          "verifiedDates": {
            "endDate": "2023-01-01",
            "startDate": "2022-01-01"
          },
          "additionalNotes": "Selected the Pablos Pizza record in Grand Junction, CO with matching applicant name, matching employment dates, and a closely aligned title. The employer name is a minor spelling variation from the provided company name, but the location and dates strongly support this as the relevant employment record.",
          "verifiedContent": {
            "positionTitle": "Senior Software Engineer"
          },
          "employerLocation": "Grand Junction, CO",
          "reasonForLeaving": "Voluntary resignation",
          "extractedApplicantName": "John Smith",
          "already_verified_closed": false
        },
        "searchType": "EMPLOYMENT",
        "employerName": "Pablos Pizza",
        "verifiedDates": {
          "endDate": "2023-01-01",
          "startDate": "2022-01-01"
        },
        "additionalNotes": "Selected the Pablos Pizza record in Grand Junction, CO with matching applicant name, matching employment dates, and a closely aligned title. The employer name is a minor spelling variation from the provided company name, but the location and dates strongly support this as the relevant employment record.",
        "verifiedContent": {
          "positionTitle": "Senior Software Engineer"
        },
        "employerLocation": "Grand Junction, CO",
        "reasonForLeaving": "Voluntary resignation",
        "_processedFromJson": true,
        "_thirdPartyProvider": "test-provider",
        "extractedApplicantName": "John Smith",
        "already_verified_closed": false
      },
      "resultDetails": "{\"extractedData\":{\"outcome\":\"verified\",\"confidence\":\"medium\",\"company\":\"Pablos Pizza\",\"employerLocation\":\"Grand Junction, CO\",\"verifier\":{},\"verifiedContent\":{\"positionTitle\":\"Senior Software Engineer\"},\"verifiedDates\":{\"startDate\":\"2022-01-01\",\"endDate\":\"2023-01-01\"},\"notes\":{\"attempts\":[]},\"already_verified_closed\":false,\"intention\":\"VERIFICATION\",\"extractedApplicantName\":\"John Smith\",\"employerName\":\"Pablos Pizza\",\"jobTitle\":\"Senior Software Engineer\",\"reasonForLeaving\":\"Voluntary resignation\",\"additionalNotes\":\"Selected the Pablos Pizza record in Grand Junction, CO with matching applicant name, matching employment dates, and a closely aligned title. The employer name is a minor spelling variation from the provided company name, but the location and dates strongly support this as the relevant employment record.\",\"startDate\":\"2022-01-01\",\"endDate\":\"2023-01-01\",\"extraction\":{\"outcome\":\"verified\",\"confidence\":\"medium\",\"company\":\"Pablos Pizza\",\"employerLocation\":\"Grand Junction, CO\",\"verifier\":{},\"verifiedContent\":{\"positionTitle\":\"Senior Software Engineer\"},\"verifiedDates\":{\"startDate\":\"2022-01-01\",\"endDate\":\"2023-01-01\"},\"notes\":{\"attempts\":[]},\"already_verified_closed\":false,\"intention\":\"VERIFICATION\",\"extractedApplicantName\":\"John Smith\",\"employerName\":\"Pablos Pizza\",\"jobTitle\":\"Senior Software Engineer\",\"reasonForLeaving\":\"Voluntary resignation\",\"additionalNotes\":\"Selected the Pablos Pizza record in Grand Junction, CO with matching applicant name, matching employment dates, and a closely aligned title. The employer name is a minor spelling variation from the provided company name, but the location and dates strongly support this as the relevant employment record.\",\"startDate\":\"2022-01-01\",\"endDate\":\"2023-01-01\"},\"refId\":\"EXT-DEV-1781042158637-1\",\"searchType\":\"EMPLOYMENT\",\"_processedFromJson\":true,\"_thirdPartyProvider\":\"test-provider\"},\"channel\":\"JSON\",\"additionalComments\":\"Selected the Pablos Pizza record in Grand Junction, CO with matching applicant name, matching employment dates, and a closely aligned title. The employer name is a minor spelling variation from the provided company name, but the location and dates strongly support this as the relevant employment record.\"}",
      "fullVerification": null,
      "additionalComments": "Selected the Pablos Pizza record in Grand Junction, CO with matching applicant name, matching employment dates, and a closely aligned title. The employer name is a minor spelling variation from the provided company name, but the location and dates strongly support this as the relevant employment record."
    },
    "employmentVerification": {
      "fields": {
        "rehire": {
          "type": "boolean",
          "status": "not_checked",
          "expected": null,
          "extracted": null,
          "comparison": {
            "engine": "none"
          }
        },
        "salary": {
          "type": "number",
          "status": "not_checked",
          "expected": null,
          "extracted": "100000",
          "comparison": {
            "engine": "none"
          }
        },
        "endDate": {
          "type": "date",
          "reason": "exact match",
          "status": "match",
          "expected": "2023-01-01",
          "extracted": "2023-01-01",
          "comparison": {
            "engine": "deterministic",
            "distance": 0
          }
        },
        "location": {
          "type": "string",
          "reason": "exact match",
          "status": "match",
          "expected": "Grand Junction, CO",
          "extracted": "Grand Junction, CO",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "position": {
          "type": "string",
          "reason": "Both titles contain the same seniority marker, \"Senior,\" so the level is aligned. The core role differs only by common synonym wording: \"Software Developer\" and \"Software Engineer\" are highly similar and typically refer to the same engineering function. Overall, the titles are highly similar.",
          "status": "match_with_discrepancy",
          "expected": "Senior Software Developer",
          "extracted": "Senior Software Engineer",
          "comparison": {
            "engine": "probabilistic",
            "similarity": 0.98
          }
        },
        "startDate": {
          "type": "date",
          "reason": "exact match",
          "status": "match",
          "expected": "2022-01-01",
          "extracted": "2022-01-01",
          "comparison": {
            "engine": "deterministic",
            "distance": 0
          }
        },
        "reasonLeft": {
          "type": "string",
          "status": "not_checked",
          "expected": "Voluntary resignation",
          "extracted": null,
          "comparison": {
            "engine": "none"
          }
        },
        "companyName": {
          "type": "string",
          "reason": "exact match",
          "status": "match",
          "expected": "Pablo's Pizza",
          "extracted": "Pablos Pizza",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "applicantName": {
          "type": "string",
          "reason": "exact match",
          "status": "match",
          "expected": "John Smith",
          "extracted": "John Smith",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        }
      },
      "comments": "Employer name in record is 'Pablos Pizza' while provided context lists 'Pablo's Pizza'; treated as the verified source value. No salary, rehire eligibility, or contact details were present in the record.",
      "confidence": 0.94,
      "providedZip": null,
      "doNotContact": false,
      "providedCity": null,
      "providedState": null,
      "providedAddress1": null,
      "providedAddress2": null,
      "verifiedEntityId": null,
      "verifierLastName": null,
      "verifierPosition": null,
      "verifiedContactId": null,
      "verifierFirstName": null
    }
  }
}

Note: Per-field outcomes for the selected highest-confidence record live on employmentVerification.fields. In this example, verificationResult.discrepancy is false while employmentVerification.fields.position.status is match_with_discrepancy — use discrepancy for the overall closeout decision and fields.* for selected-record detail. verificationResult.search may include full nested order/applicant metadata;

EducationVerification Object

Complete education verification data with both the canonical fields comparison object and backward-compatible flat provided* / verified* fields. Payload shape: All channels (EMAIL, FAX, VOICE, and JSON) use a fields object with per-field comparison metadata (type, status, expected, extracted, optional reason, and comparison with engine / similarity / distance). Legacy flat fields remain for existing consumers. The highest-confidence educationVerification object appears at the data root in webhook payloads, not inside metadata.extractedData or verificationResult. Synchronous inbound API responses likewise return it at the response root.

Fields-based comparison (`fields`)

Each key under fields compares order data (expected) to the verifier-extracted value (extracted).

Field key	`type`	Description
`schoolName`	`string`	Institution name
`location`	`string`	Institution location
`degree`	`string`	Degree or qualification
`major`	`string`	Major or field of study
`minor`	`string`	Minor
`gpa`	`number`	Grade point average
`startDate`	`date`	Attendance start date
`endDate`	`date`	Attendance end date
`graduated`	`boolean`	Whether the applicant graduated
`graduationDate`	`date`	Graduation or award date
`contactName`	`string`	Registrar or verifier contact name
`contactNumber`	`string`	Registrar or verifier contact phone
`contactEmail`	`string`	Registrar or verifier contact email
`honors`	`string`	Honors or distinctions
`applicantName`	`string`	Name on the institution record

Each field object has the following shape:

Field	Type	Required	Description
`type`	`string`, `date`, `number`, or `boolean`	Yes	Data type used to compare and interpret the field values.
`status`	`match`, `mismatch`, `match_with_discrepancy`, or `not_checked`	Yes	Result of comparing `expected` with `extracted`.
`expected`	`string`, `number`, `boolean`, or `null`	Yes	Value supplied on the order. `null` means no expected value was available.
`extracted`	`string`, `number`, `boolean`, or `null`	Yes	Value extracted from the verifier or provider response. `null` means no value was extracted.
`reason`	`string`	No	Human-readable explanation for the comparison result, especially semantic discrepancies and mismatches.
`comparison`	`object`	Yes	Comparison-engine metadata described by the fields below.
`comparison.engine`	`deterministic`, `probabilistic`, or `none`	Yes	Method used to compare values. `none` is used when the field was not checked.
`comparison.similarity`	`number`	No	String-comparison score from 0–1. Deterministic exact string matches use `1`; string mismatches use the evaluated score or `0` when no score is available.
`comparison.distance`	`number`	No	Absolute difference for date and number comparisons. Dates use calendar days; numbers use the normalized numeric difference. Exact matches use `0`. Not used for strings.
`comparison.confidence`	`number`	No	Optional confidence score from the comparison engine when one is available.

Backward-compatible flat fields

Field	Type	Description
`providedSchoolName`	`string`	Claimed institution name
`providedLocation`	`string`	Institution location
`providedAddress1`	`string`	Address line 1
`providedAddress2`	`string`	Address line 2
`providedCity`	`string`	City
`providedState`	`string`	State
`providedZip`	`string`	Postal code
`providedContactName`	`string`	Contact name
`providedContactNumber`	`string`	Contact phone
`providedContactEmail`	`string`	Contact email
`providedDegree`	`string`	Claimed degree
`providedMajor`	`string`	Claimed major
`providedMinor`	`string`	Claimed minor
`providedStartDate`	`string`	Attendance start date
`providedEndDate`	`string`	Attendance end date
`providedGraduated`	`string`	Graduation status claimed
`providedGraduationDate`	`string`	Claimed graduation date
`providedApplicantName`	`string`	Applicant name on the order

Verified and metadata fields

Field	Type	Description
`verifiedEntityId`	`string`	Internal institution entity ID
`verifiedSchoolName`	`string`	Confirmed institution name
`verifiedLocation`	`string`	Confirmed institution location
`verifiedDegree`	`string`	Confirmed degree
`verifiedMajor`	`string`	Confirmed major
`verifiedMinor`	`string`	Confirmed minor
`verifiedGpa`	`string`	Confirmed GPA
`verifiedStartDate`	`string`	Confirmed attendance start date
`verifiedEndDate`	`string`	Confirmed attendance end date
`verifiedGraduated`	`boolean` or `null`	Confirmed graduation status
`verifiedGraduationDate`	`string`	Confirmed graduation date
`verifiedContactName`	`string`	Registrar/contact name
`verifiedContactNumber`	`string`	Contact phone
`verifiedContactEmail`	`string`	Contact email
`verifiedApplicantName`	`string`	Applicant name on the provider record
`comments`	`string`	Additional comments
`verifierFirstName`	`string`	Verifier first name
`verifierLastName`	`string`	Verifier last name
`verifierPosition`	`string`	Verifier title
`confidence`	`number`	JSON history-row match score, descending

Example: Education Verification (Fax)

{
  "event": "verification.completed",
  "occurredAt": "2025-12-02T16:45:00.000Z",
  "data": {
    "searchId": "ed9a2f9e-0bf5-4aa2-ac7a-9f4c42355940",
    "verificationId": "vr_f1c64c38-6403-49c9-91af-127c7fcb8f4c",
    "externalSearchId": "edu-verify-880",
    "searchType": "EDUCATION",
    "status": "Completed",
    "channel": "FAX",
    "verificationResult": {
      "id": "vr_f1c64c38-6403-49c9-91af-127c7fcb8f4c",
      "searchId": "ed9a2f9e-0bf5-4aa2-ac7a-9f4c42355940",
      "outcome": "VERIFIED",
      "submittedAt": "2025-12-02T16:45:00.000Z",
      "createdAt": "2025-11-28T09:12:44.000Z",
      "updatedAt": "2025-12-02T16:45:00.000Z",
      "channel": "FAX",
      "additionalComments": "Sealed transcript received via fax",
      "discrepancy": true,
      "extractedData": {
        "educationVerified": true,
        "institutionName": "Stanford University",
        "qualification": "Bachelor of Science",
        "fieldOfStudy": "Computer Science",
        "graduationDate": "2022-06-12",
        "gpa": "3.84/4.0",
        "confidence": 0.97
      },
      "verifier": {
        "firstName": "Regina",
        "lastName": "Sloane",
        "position": "Registrar"
      }
    },
    "educationVerification": {
      "fields": {
        "schoolName": {
          "expected": "Stanford University",
          "extracted": "Stanford University",
          "reason": "exact match",
          "status": "match",
          "type": "string",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "location": {
          "expected": "Stanford, CA",
          "extracted": "Stanford, CA",
          "reason": "exact match",
          "status": "match",
          "type": "string",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "degree": {
          "expected": "BS Computer Science",
          "extracted": "Bachelor of Science",
          "reason": "The degree names are semantically equivalent; the provided value also includes the major.",
          "status": "match_with_discrepancy",
          "type": "string",
          "comparison": {
            "engine": "probabilistic",
            "similarity": 0.94
          }
        },
        "major": {
          "expected": "Computer Science",
          "extracted": "Computer Science",
          "reason": "exact match",
          "status": "match",
          "type": "string",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "minor": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "gpa": {
          "expected": null,
          "extracted": "3.84/4.0",
          "status": "not_checked",
          "type": "number",
          "comparison": {
            "engine": "none"
          }
        },
        "startDate": {
          "expected": "2018-09-01",
          "extracted": "2018-09-01",
          "reason": "exact match",
          "status": "match",
          "type": "date",
          "comparison": {
            "engine": "deterministic",
            "distance": 0
          }
        },
        "endDate": {
          "expected": "2022-06-15",
          "extracted": "2022-06-12",
          "reason": "Dates differ by 3 calendar days, exceeding the configured threshold.",
          "status": "mismatch",
          "type": "date",
          "comparison": {
            "engine": "deterministic",
            "distance": 3
          }
        },
        "graduated": {
          "expected": true,
          "extracted": true,
          "reason": "exact match",
          "status": "match",
          "type": "boolean",
          "comparison": {
            "engine": "deterministic"
          }
        },
        "graduationDate": {
          "expected": "2022-06-15",
          "extracted": "2022-06-12",
          "reason": "Dates differ by 3 calendar days, exceeding the configured threshold.",
          "status": "mismatch",
          "type": "date",
          "comparison": {
            "engine": "deterministic",
            "distance": 3
          }
        },
        "honors": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "applicantName": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        }
      },
      "verifiedEntityId": null,
      "providedAddress1": null,
      "providedAddress2": null,
      "providedCity": "Stanford",
      "providedState": "CA",
      "providedZip": "94305",
      "comments": "Confirmed via sealed transcript",
      "verifierFirstName": "Regina",
      "verifierLastName": "Sloane",
      "verifierPosition": "Registrar"
    },
    "accreditation": {
      "isAccredited": true,
      "statusLabel": "Accredited",
      "accreditor": "Western Association of Schools and Colleges, Senior College and University Commission",
      "checkedOn": "2025-12-02"
    }
  }
}

Example: Education Verification (No Record)

{
  "event": "verification.completed",
  "occurredAt": "2025-12-02T14:20:00.000Z",
  "data": {
    "searchId": "norecord-1234-5678-abcd-ef0123456789",
    "verificationId": "vr_norecord-9876-5432-dcba-fedcba987654",
    "externalSearchId": "edu-check-999",
    "searchType": "EDUCATION",
    "status": "Completed",
    "channel": "EMAIL",
    "verificationResult": {
      "id": "vr_norecord-9876-5432-dcba-fedcba987654",
      "searchId": "norecord-1234-5678-abcd-ef0123456789",
      "outcome": "NO_RECORD",
      "submittedAt": "2025-12-02T14:20:00.000Z",
      "createdAt": "2025-12-01T10:00:00.000Z",
      "updatedAt": "2025-12-02T14:20:00.000Z",
      "channel": "EMAIL",
      "additionalComments": "No enrollment record found for this individual",
      "discrepancy": false,
      "extractedData": {
        "educationVerified": false,
        "noRecord": true,
        "confidence": 0.95
      }
    },
    "educationVerification": {
      "fields": {
        "schoolName": {
          "expected": "State University",
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "location": {
          "expected": "Columbus, OH",
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "degree": {
          "expected": "Bachelor of Arts",
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "major": {
          "expected": "Psychology",
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "minor": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "gpa": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "number",
          "comparison": {
            "engine": "none"
          }
        },
        "startDate": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "date",
          "comparison": {
            "engine": "none"
          }
        },
        "endDate": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "date",
          "comparison": {
            "engine": "none"
          }
        },
        "graduated": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "boolean",
          "comparison": {
            "engine": "none"
          }
        },
        "graduationDate": {
          "expected": "2019-05-15",
          "extracted": null,
          "status": "not_checked",
          "type": "date",
          "comparison": {
            "engine": "none"
          }
        },
        "honors": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        },
        "applicantName": {
          "expected": null,
          "extracted": null,
          "status": "not_checked",
          "type": "string",
          "comparison": {
            "engine": "none"
          }
        }
      },
      "verifiedEntityId": null,
      "providedAddress1": null,
      "providedAddress2": null,
      "providedCity": "Columbus",
      "providedState": "OH",
      "providedZip": null,
      "comments": "Registrar confirmed no enrollment record exists for this individual"
    }
  }
}

AccreditationResult Object

Included in education verification webhooks (verification.completed and verification.action_required).

Field	Type	Description
`isAccredited`	`boolean`	Whether the institution is accredited
`statusLabel`	`string`	Human-readable accreditation status
`accreditor`	`string`	Accrediting agency name
`checkedOn`	`string`	Date of accreditation check
`note`	`string`	Present when no match found; review instructions

Event: verification.action_required

Sent when verification cannot proceed without manual intervention.

data.message is JSON-channel QA Review only. It appears on verification.action_required when channel is JSON, status is QA Review, and the inbound was processed from third-party JSON (metadata.extractedData._processedFromJson: true). EMAIL, FAX, and VOICE action-required webhooks do not include message — use metadata.summary and related context instead.For EMAIL/FAX/VOICE verified inbound with applicant or field mismatches, the typical path is verification.completed with verificationResult.discrepancy: true and per-field detail on root-level employmentVerification.fields, not verification.action_required.

Data Fields

Field	Type	Required	Description
`searchId`	`string` (UUID)	Yes	Search identifier
`verificationId`	`string` (UUID)	No	Present when verification record exists
`externalSearchId`	`string`	No	External identifier
`searchType`	`SearchType`	No	Type of verification
`reasonCode`	`ActionRequiredReasonCode`	Yes	Machine-readable reason code
`status`	`string`	No	Human-readable status
`channel`	`VerificationChannel`	No	Channel that triggered the action
`message`	`string`	No	JSON-channel QA Review only (`channel: "JSON"`, `status: "QA Review"`, `_processedFromJson: true`). Human-readable review summary for client UI; it can list all internally evaluated provider records. Omitted for EMAIL, FAX, and VOICE. Use `fields.*` on the selected verification object for structured comparison detail.
`employmentVerification`	`EmploymentVerification`	Conditional	Highest-confidence normalized employment object for employment action-required webhooks
`educationVerification`	`EducationVerification`	Conditional	Highest-confidence normalized education object for education action-required webhooks
`contact`	`ContactPayload`	No	Structured contact information
`metadata`	`object`	No	Additional context and troubleshooting data
`accreditation`	`AccreditationResult`	No	Accreditation data (education with `THIRD_PARTY_RECORD`)

ActionRequiredReasonCode Enum

Code	Description	When Triggered
`THIRD_PARTY_RECORD`	Requires third-party vendor	Research identified paywalled portal or vendor
`UPSTREAM_ISSUE`	External service failure	Fax provider outage, email throttling, API failure
`SYSTEM_FAILURE`	Internal system error	Database issue, workflow crash
`SLA_REACHED`	SLA timeout exceeded	Search exceeded SLA without result
`HUMAN_ESCALATION`	Automation exhausted	No contacts found, retry cap hit, questionnaire gates, phone-only required custom questions, or other manual review
`OTHER`	Catch-all	Cases not matching other codes

If searchConfig.thirdPartyBan contains the detected canonical vendor, THIRD_PARTY_RECORD is intentionally suppressed. Research records an audit notation and continues manual/outbound handling. Inbound third-party redirects to a banned vendor emit HUMAN_ESCALATION with metadata.escalationSubtype: "THIRD_PARTY_BAN". See Third-party ban.

When custom or standard questions drive escalation, inspect metadata.escalationSubtype (and related fields). These paths do not emit verification.completed.

`escalationSubtype`	When	Additional `metadata`
`MISSING_REQUIRED_INFORMATION`	Applicable required custom question unanswered on inbound PDF/fax/voice	`missingQuestionIds` (`number[]`), partial `verificationQuestions`, `inboundMessageContext`, `extractedData`, optional `artifactUrls` (signed PDF links)
`VERIFICATION_DATA_INVALID`	Invalid exclusive marks, out-of-option values, or `multi_select` outside min/max	`invalidFields` (`{ fieldKey, reason }[]`), partial `verificationQuestions`, `inboundMessageContext`, `extractedData`, optional `artifactUrls`
`VOICE_ONLY_NOT_SUPPORTED`	Only voice is available (email and fax are not)	Channel-selection context (emitted at outbound planning, before a form is completed)

Integration tips:

Treat MISSING_REQUIRED_INFORMATION and VERIFICATION_DATA_INVALID as form-quality failures — show ops the partial answers and signed artifactUrls when present.
VOICE_ONLY_NOT_SUPPORTED means the search has only a voice destination; provide an email or fax contact because voice outbound is not supported.
invalidFields[].reason is a human-readable string (for example fewer than minSelections (1), value "Maybe" is not a defined option, multiple exclusive selections detected).

Full request/response shapes and channel selection: Verification question.

ContactPayload Object

Structured contact information based on search type.

Field	Type	Description
`type`	`string`	Contact type: `EMPLOYMENT` or `EDUCATION`
`data`	`object`	Type-specific contact data (see payload types below)

EmploymentContactPayload

Field	Type	Description
`providedCompanyName`	`string`	Employer name
`providedContactName`	`string`	Contact name
`providedContactNumber`	`string`	Contact phone
`providedContactEmail`	`string`	Contact email
`providedLocation`	`string`	Employer location
`providedStartDate`	`string`	Employment start date
`providedEndDate`	`string`	Employment end date
`providedPosition`	`string`	Job title
`providedSalary`	`string`	Claimed compensation (free text; inbound cross-check may parse to annual USD; see Discrepancy Detection)
`providedAddress1`	`string`	Address line 1
`providedAddress2`	`string`	Address line 2
`providedCity`	`string`	City
`providedState`	`string`	State
`providedZip`	`string`	Postal code
`doNotContact`	`boolean`	Do-not-contact flag

EducationContactPayload

Field	Type	Description
`providedSchoolName`	`string`	Institution name
`providedLocation`	`string`	Institution location
`providedAddress1`	`string`	Address line 1
`providedAddress2`	`string`	Address line 2
`providedCity`	`string`	City
`providedState`	`string`	State
`providedZip`	`string`	Postal code
`providedContactName`	`string`	Contact name
`providedContactNumber`	`string`	Contact phone
`providedContactEmail`	`string`	Contact email
`providedDegree`	`string`	Degree
`providedMajor`	`string`	Major
`providedMinor`	`string`	Minor
`providedStartDate`	`string`	Attendance start
`providedEndDate`	`string`	Attendance end
`providedGraduated`	`string`	Graduation status
`providedGraduationDate`	`string`	Graduation date

Example: THIRD_PARTY_RECORD (Employment)

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T10:15:00.000Z",
  "data": {
    "searchId": "7b0463ae-a338-4b5f-bd5c-b3ef2e6e5ccc",
    "externalSearchId": "emp-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "THIRD_PARTY_RECORD",
    "status": "QA Review",
    "channel": "EMAIL",
    "metadata": {
      "source": "research",
      "contactIndex": 0,
      "vendor": "TALX_WORK_NUMBER",
      "vendorCode": "15619",
      "vendorMatched": "TWN 15619 - uses The Work Number exclusively"
    },
    "contact": {
      "type": "EMPLOYMENT",
      "data": {
        "providedCompanyName": "Major Hospital Network",
        "providedContactName": "HR Department",
        "providedPosition": "Registered Nurse",
        "providedStartDate": "2020-03-15",
        "providedEndDate": "2024-08-01",
        "doNotContact": false
      }
    }
  }
}

Example: THIRD_PARTY_RECORD (Education with Accreditation)

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T18:05:00.000Z",
  "data": {
    "searchId": "ed_7b0463ae-a338-4b5f-bd5c-b3ef2e6e5ccc",
    "externalSearchId": "edu-req-90210",
    "searchType": "EDUCATION",
    "reasonCode": "THIRD_PARTY_RECORD",
    "status": "QA Review",
    "channel": "EMAIL",
    "metadata": {
      "source": "research",
      "contactIndex": 0,
      "vendor": "PARCHMENT",
      "vendorCode": "DIST-90833",
      "vendorMatched": "Parchment portal only"
    },
    "contact": {
      "type": "EDUCATION",
      "data": {
        "providedSchoolName": "Metro High School District",
        "providedLocation": "Memphis, TN",
        "providedContactName": "Records Office",
        "providedContactEmail": "records@metrohsd.gov",
        "providedContactNumber": "+19015445566",
        "providedGraduationDate": "2018-05-25"
      }
    },
    "accreditation": {
      "isAccredited": true,
      "statusLabel": "Accredited",
      "accreditor": "SACS",
      "checkedOn": "2025-12-02"
    }
  }
}

Example: UPSTREAM_ISSUE

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T06:12:00.000Z",
  "data": {
    "searchId": "search_voice_fax_884",
    "externalSearchId": "emp-upstream-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "UPSTREAM_ISSUE",
    "status": "Outbound Retry Cap",
    "channel": "EMAIL",
    "metadata": {
      "provider": "azureEmail",
      "errorCategory": "provider_timeout",
      "message": "Microsoft Graph throttled mailbox after 5 consecutive 503 responses",
      "lastAttemptAt": "2025-12-02T05:58:00.000Z",
      "retryCount": 3
    }
  }
}

Example: SYSTEM_FAILURE

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T14:30:00.000Z",
  "data": {
    "searchId": "ed_verif_540",
    "externalSearchId": "edu-sys-001",
    "searchType": "EDUCATION",
    "reasonCode": "SYSTEM_FAILURE",
    "status": "Workflow Error",
    "channel": "FAX",
    "metadata": {
      "errorCategory": "system",
      "correlationId": "wf_education_outbound_20260115T1425",
      "retryCount": 1,
      "note": "Database write failure while persisting fax metadata"
    }
  }
}

Example: SLA_REACHED

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T18:22:00.000Z",
  "data": {
    "searchId": "ed_0f6b69ec-4de5-49a5-9aa0-3e94f3c6c4db",
    "externalSearchId": "edu-sla-001",
    "searchType": "EDUCATION",
    "reasonCode": "SLA_REACHED",
    "status": "Awaiting Response",
    "channel": "EMAIL",
    "metadata": {
      "slaHours": 24,
      "elapsedMinutes": 1560,
      "lastAttemptAt": "2025-12-02T17:55:00.000Z",
      "reassignmentWindowMinutes": 2880,
      "note": "University registrar has not responded to multiple attempts"
    },
    "contact": {
      "type": "EDUCATION",
      "data": {
        "providedSchoolName": "University of Texas at Austin",
        "providedDegree": "Bachelor of Science",
        "providedMajor": "Computer Science",
        "providedGraduationDate": "2020-05-15"
      }
    }
  }
}

Example: HUMAN_ESCALATION (EMAIL — no `message`)

Non-JSON escalations (for example SLA timeout) may use status: "QA Review" but do not include data.message. Review context lives in metadata (for example summary, contactPlan).

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T10:00:00.000Z",
  "data": {
    "searchId": "emp_7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
    "externalSearchId": "emp-escalate-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "HUMAN_ESCALATION",
    "status": "QA Review",
    "channel": "EMAIL",
    "metadata": {
      "source": "automatic_reassignment",
      "createdAt": "2025-11-30T10:00:00.000Z",
      "reassignedAt": "2025-12-02T10:00:00.000Z",
      "outboundWindowMinutes": 1440,
      "reassignmentWindowMinutes": 2880,
      "exceededSla": true,
      "reachedReassignmentWindow": true,
      "contactPlan": {
        "contactResults": [
          {
            "name": "HR Manager",
            "entityName": "Acme Corporation",
            "contactMethods": [
              {
                "email": "hr@acmecorp.com",
                "phone": "+14255551234",
                "confidence": 0.85,
                "source": "verified_contacts"
              }
            ],
            "title": "HR Manager",
            "department": "Human Resources",
            "confidence": 0.85,
            "location": "New York, NY",
            "usesThirdParty": false
          },
          {
            "name": "The Work Number",
            "entityName": "Fifth Third Bank",
            "contactMethods": [
              {
                "thirdPartyId": "1239110",
                "description": "The Work Number",
                "notes": "Imported from Work Number list 6/22/2017",
                "confidence": 1.0,
                "source": "third_party"
              }
            ],
            "confidence": 0.95,
            "location": "global",
            "usesThirdParty": true,
            "contactPreference": "The Work Number"
          }
        ],
        "requiresHumanEscalation": false
      }
    }
  }
}

Example: HUMAN_ESCALATION (JSON channel — includes `message`)

For JSON-channel QA Review (status: "QA Review"), includes a root-level message string intended for display to clients — operators, review queues, or end-user-facing UI. It is a plain-language summary of the issue and what the third-party provider returned, so reviewers do not need to parse structured JSON to understand the case. The message is auto-generated when channel is JSON, normalized verification records are present, and the inbound payload was processed from third-party JSON (metadata.extractedData._processedFromJson: true). This applies regardless of reasonCode (for example HUMAN_ESCALATION or OTHER). It contains:

Intro line — the review task (for example, choose the most relevant employment or education record and close the search using that row).
One Record N block per provider history row — extracted values such as employer/school, job title or degree, dates, location, applicant name, salary, and contact details when present.
Per-record comments — short notes on notable issues (applicant name conflicts, missing fields, location mismatches, etc.).

The message can list internally evaluated records in confidence order (highest first), while the structured root-level employmentVerification / educationVerification field contains only the highest-confidence object. Message string values are double-quoted and escaped; numeric and boolean values are unquoted. When a rendered value comes from a field whose structured comparison has status: "mismatch", the value includes a display suffix of [Mismatch]. Use message for human-readable UI copy; use employmentVerification.fields / educationVerification.fields for programmatic field comparison and metadata.extractedData for scalar extraction and escalation flags.

{
  "event": "verification.action_required",
  "occurredAt": "2026-06-09T22:00:00.000Z",
  "data": {
    "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
    "externalSearchId": "EXT-DEV-1781042158637-1",
    "searchType": "EMPLOYMENT",
    "reasonCode": "HUMAN_ESCALATION",
    "status": "QA Review",
    "channel": "JSON",
    "message": "I need help determining which job is the most relevant job given the job records below, choose the relevant one and use that to close this search out\n\nRecord 1\n\ncompany: \"SNH AI\"\nemployerName: \"SNH AI\"\njobTitle: \"Senior Testing Engineer\"\nstartDate: \"2022-01-01 [Mismatch]\"\nendDate: \"2024-01-01\"\nemployerLocation: \"Grand Junction, CO\"\nsalary: 100000\ncontactNumber: \"+1-555-200-1000\"\nfirstName: \"Patel\"\nlastName: \"Gowda\"\ncomments: \"Applicant on file is John Smith, but the third-party record identifies Patel Gowda. Employer location is Grand Junction, CO. No salary or rehire eligibility data was present in the record.\"\n\nRecord 2\n\ncompany: \"SNH AI\"\nemployerName: \"SNH AI\"\njobTitle: \"Testing Engineer\"\nstartDate: \"2021-01-15 [Mismatch]\"\nendDate: \"2024-01-01\"\nemployerLocation: \"Austin, TX [Mismatch]\"\nsalary: 100000\ncontactNumber: \"+1-555-200-1000\"\nfirstName: \"Patel\"\nlastName: \"Gowda\"\ncomments: \"Third-party record identifies employee as Patel Gowda, not John Smith. Employer located in Austin, TX. No salary, rehire eligibility, or contact details present in the source record.\"\n\nRecord 3\n\ncompany: \"Other Corp [Mismatch]\"\nemployerName: \"Other Corp [Mismatch]\"\njobTitle: \"Tester [Mismatch]\"\nstartDate: \"2019-01-01 [Mismatch]\"\nendDate: \"2020-01-01\"\nemployerLocation: \"Denver, CO\"\nsalary: 100000\ncontactNumber: \"+1-555-200-1000\"\nfirstName: \"Patel\"\nlastName: \"Gowda\"\ncomments: \"Third-party record shows a different individual than the applicant on file (John Smith) and a different employer than provided context; however, the employment facts in the JSON are internally clear for Patel Gowda at Other Corp.\"",
    "employmentVerification": {
      "confidence": 0.94,
      "fields": {
        "companyName": {
          "type": "string",
          "status": "match",
          "expected": "Pablo's Pizza",
          "extracted": "Pablos Pizza",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        },
        "position": {
          "type": "string",
          "status": "match_with_discrepancy",
          "expected": "Senior Software Developer",
          "extracted": "Senior Software Engineer",
          "comparison": { "engine": "probabilistic", "similarity": 0.98 }
        },
        "startDate": {
          "type": "date",
          "status": "mismatch",
          "expected": "2022-01-01",
          "extracted": "2021-01-01",
          "comparison": { "engine": "deterministic", "distance": 365 }
        },
        "endDate": {
          "type": "date",
          "reason": "Dates diverge by 20 days; expected \"2023-01-01\", extracted \"2023-01-21\"",
          "status": "mismatch",
          "expected": "2023-01-01",
          "extracted": "2023-01-21",
          "comparison": { "engine": "deterministic", "distance": 20 }
        },
        "location": {
          "type": "string",
          "status": "match",
          "expected": "Grand Junction, CO",
          "extracted": "Grand Junction, CO",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        },
        "applicantName": {
          "type": "string",
          "status": "match",
          "expected": "John Smith",
          "extracted": "John Smith",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        }
      }
    },
    "metadata": {
      "source": "inbound",
      "outcome": "verified",
      "channel": "JSON",
      "extractedData": {
        "outcome": "verified",
        "employerName": "Pablos Pizza",
        "jobTitle": "Senior Software Engineer",
        "startDate": "2021-01-01",
        "endDate": "2023-01-01",
        "employerLocation": "Grand Junction, CO",
        "_processedFromJson": true,
        "_thirdPartyProvider": "test-provider",
        "applicantMismatch": true,
        "_requiresManualReview": true
      }
    }
  }
}

Example: HUMAN_ESCALATION (missing required custom question)

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T11:00:00.000Z",
  "data": {
    "searchId": "emp_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "externalSearchId": "emp-cq-missing-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": "2025-12-02T10:55:00.000Z"
      },
      "extractedData": {
        "outcome": "verified",
        "intention": "VERIFICATION"
      },
      "artifactUrls": [
        {
          "name": "attachment-1",
          "url": "https://storage.example/signed/verification-form.pdf"
        }
      ],
      "channel": "FAX"
    }
  }
}

Example: HUMAN_ESCALATION (invalid custom question marks)

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T11:05:00.000Z",
  "data": {
    "searchId": "emp_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "externalSearchId": "emp-cq-invalid-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
        }
      ],
      "inboundMessageContext": {
        "from": "hr@employer.example",
        "subject": "Re: Employment verification",
        "bodyPreview": "Attached form.",
        "timestamp": "2025-12-02T11:00:00.000Z"
      },
      "channel": "EMAIL"
    }
  }
}

Example: HUMAN_ESCALATION (voice only)

Emitted when the only available channel is voice — voice outbound is not supported.

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T10:30:00.000Z",
  "data": {
    "searchId": "emp_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "externalSearchId": "emp-voice-only-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "HUMAN_ESCALATION",
    "status": "QA Review",
    "metadata": {
      "source": "outbound",
      "escalationSubtype": "VOICE_ONLY_NOT_SUPPORTED"
    }
  }
}

Example: OTHER

OTHER (JSON channel)

JSON-channel inbound responses routed with reasonCode: "OTHER" — for example when extraction yields no_record_or_not_found but the provider payload still contains employment or education history rows — include the same client-facing message field as other JSON-channel verification.action_required events. Display message in review UI so operators and end users see a plain-language summary of evaluated records and why manual review is needed; use employmentVerification.fields / educationVerification.fields for structured comparison and metadata.extractedData for scalar extraction flags.

{
  "data": {
    "status": "QA Review",
    "channel": "JSON",
    "message": "I need help determining which job is the most relevant job given the job records below, choose the relevant one and use that to close this search out\n\nRecord 1\n\ncompany: \"SNH AI\"\nemployerName: \"SNH AI\"\njobTitle: \"Senior Testing Engineer\"\nstartDate: \"2022-01-01 [Mismatch]\"\nendDate: \"2024-01-01\"\nemployerLocation: \"Grand Junction, CO\"\nsalary: 100000\ncontactNumber: \"+1-555-200-1000\"\nfirstName: \"Patel\"\nlastName: \"Gowda\"\ncomments: \"Applicant on file is John Smith, but the third-party record identifies Patel Gowda. Employer location is Grand Junction, CO. No salary or rehire eligibility data was present in the record.\"\n\nRecord 2\n\ncompany: \"SNH AI\"\nemployerName: \"SNH AI\"\njobTitle: \"Testing Engineer\"\nstartDate: \"2021-01-15 [Mismatch]\"\nendDate: \"2024-01-01\"\nemployerLocation: \"Austin, TX [Mismatch]\"\nsalary: 100000\ncontactNumber: \"+1-555-200-1000\"\nfirstName: \"Patel\"\nlastName: \"Gowda\"\ncomments: \"Third-party record identifies employee as Patel Gowda, not John Smith. Employer located in Austin, TX. No salary, rehire eligibility, or contact details present in the source record.\"\n\nRecord 3\n\ncompany: \"Other Corp [Mismatch]\"\nemployerName: \"Other Corp [Mismatch]\"\njobTitle: \"Tester [Mismatch]\"\nstartDate: \"2019-01-01 [Mismatch]\"\nendDate: \"2020-01-01\"\nemployerLocation: \"Denver, CO\"\nsalary: 100000\ncontactNumber: \"+1-555-200-1000\"\nfirstName: \"Patel\"\nlastName: \"Gowda\"\ncomments: \"Third-party record shows a different individual than the applicant on file (John Smith) and a different employer than provided context; however, the employment facts in the JSON are internally clear for Patel Gowda at Other Corp.\"",
    "metadata": {
      "source": "inbound",
      "channel": "JSON",
      "outcome": "no_record_or_not_found",
      "summary": "test-provider responded indicating they have no matching records for this individual. Please review the response and determine next steps (e.g., verify search criteria, try an alternative contact).",
      "extractedData": {
        "notes": {
          "attempts": []
        },
        "refId": "EXT-DEV-1781042158637-1",
        "company": "SNH AI",
        "endDate": "2024-01-01",
        "outcome": "no_record_or_not_found",
        "jobTitle": "Senior Testing Engineer",
        "verifier": {},
        "intention": "VERIFICATION",
        "startDate": "2022-01-01",
        "confidence": "medium",
        "extraction": {
          "notes": {
            "attempts": []
          },
          "company": "SNH AI",
          "endDate": "2024-01-01",
          "outcome": "no_record_or_not_found",
          "jobTitle": "Senior Testing Engineer",
          "verifier": {},
          "intention": "VERIFICATION",
          "startDate": "2022-01-01",
          "confidence": "medium",
          "employerName": "SNH AI",
          "verifiedDates": {
            "endDate": "2024-01-01",
            "startDate": "2022-01-01"
          },
          "additionalNotes": "No record matches the applicant and provided employment context well enough for verification. The closest available entry is the SNH AI record in Grand Junction, CO with title Senior Testing Engineer and hire date 2022-01-01, but the employee name does not match the applicant on file and the employer does not match the company on file. Another SNH AI entry in Austin, TX has a different title and dates, and the Other Corp entry also does not match the company on file.",
          "verifiedContent": {
            "positionTitle": "Senior Testing Engineer"
          },
          "employerLocation": "Grand Junction, CO",
          "reasonForLeaving": "Voluntary resignation",
          "applicantNameMismatch": true,
          "extractedApplicantName": "Patel Gowda",
          "already_verified_closed": false
        },
        "searchType": "EMPLOYMENT",
        "employerName": "SNH AI",
        "verifiedDates": {
          "endDate": "2024-01-01",
          "startDate": "2022-01-01"
        },
        "additionalNotes": "No record matches the applicant and provided employment context well enough for verification. The closest available entry is the SNH AI record in Grand Junction, CO with title Senior Testing Engineer and hire date 2022-01-01, but the employee name does not match the applicant on file and the employer does not match the company on file. Another SNH AI entry in Austin, TX has a different title and dates, and the Other Corp entry also does not match the company on file.",
        "verifiedContent": {
          "positionTitle": "Senior Testing Engineer"
        },
        "employerLocation": "Grand Junction, CO",
        "reasonForLeaving": "Voluntary resignation",
        "applicantMismatch": true,
        "_processedFromJson": true,
        "_thirdPartyProvider": "test-provider",
        "_requiresManualReview": true,
        "applicantNameMismatch": true,
        "extractedApplicantName": "Patel Gowda",
        "already_verified_closed": false
      },
      "inboundMessageContext": {
        "from": "test-provider",
        "timestamp": "2026-05-22T18:30:00.000Z",
        "bodyPreview": "{ \"employmentData\": [ { \"employer\": { \"name\": \"Other Corp\", \"address\": { \"city\": \"Denver\", \"state\": \"CO\" } }, \"employee\": { \"firstName\": \"Patel\", \"lastName\": \"Gowda\", \"positionTitle\": \"Tester\", \"mostRecentHireDate\": \"2019-01-01\", \"terminationDate\": \"2020-01-01\", \"employeeStatus\": { \"message\": \"Terminated\", \"type\": \"terminated\" } } }, { \"employer\": { \"name\": \"SNH AI\", \"address\": { \"city\": \"Austin\", \"state\": \"TX\" } }, \"employee\": { \"firstName\": \"Patel\", \"lastName\": \"Gowda\", \"positionTitle\": \"Testi"
      }
    },
    "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
    "reasonCode": "OTHER",
    "searchType": "EMPLOYMENT",
    "externalSearchId": "EXT-DEV-1781042158637-1",
    "employmentVerification": {
      "fields": {
        "rehire": {
          "type": "boolean",
          "status": "not_checked",
          "expected": null,
          "extracted": null,
          "comparison": {
            "engine": "none"
          }
        },
        "salary": {
          "type": "number",
          "status": "not_checked",
          "expected": null,
          "extracted": "100000",
          "comparison": {
            "engine": "none"
          }
        },
        "endDate": {
          "type": "date",
          "reason": "Dates diverge by 365 days; expected \"2023-01-01\", extracted \"2024-01-01\"",
          "status": "mismatch",
          "expected": "2023-01-01",
          "extracted": "2024-01-01",
          "comparison": {
            "engine": "deterministic",
            "distance": 365
          }
        },
        "location": {
          "type": "string",
          "reason": "exact match",
          "status": "match",
          "expected": "Grand Junction, CO",
          "extracted": "Grand Junction, CO",
          "comparison": {
            "engine": "deterministic",
            "similarity": 1
          }
        },
        "position": {
          "type": "string",
          "reason": "The titles are different. Both include the same seniority marker, \"Senior,\" so the level is aligned. However, the core roles differ: \"Software Developer\" is a software development role, while \"Testing Engineer\" is a quality assurance/testing role. Because the functional job family is different, the titles have low similarity overall.",
          "status": "mismatch",
          "expected": "Senior Software Developer",
          "extracted": "Senior Testing Engineer",
          "comparison": {
            "engine": "probabilistic",
            "similarity": 0.18
          }
        },
        "startDate": {
          "type": "date",
          "reason": "exact match",
          "status": "match",
          "expected": "2022-01-01",
          "extracted": "2022-01-01",
          "comparison": {
            "engine": "deterministic",
            "distance": 0
          }
        },
        "reasonLeft": {
          "type": "string",
          "status": "not_checked",
          "expected": "Voluntary resignation",
          "extracted": null,
          "comparison": {
            "engine": "none"
          }
        },
        "companyName": {
          "type": "string",
          "reason": "Not an exact match",
          "status": "mismatch",
          "expected": "Pablo's Pizza",
          "extracted": "SNH AI",
          "comparison": {
            "engine": "deterministic",
            "similarity": 0
          }
        },
        "applicantName": {
          "type": "string",
          "reason": "The names are different and show low similarity. 'John Smith' and 'Patel Gowda' do not share the same first or last name, and there are no clear variants or secondary-name differences to connect them. They appear to refer to different people.",
          "status": "mismatch",
          "expected": "John Smith",
          "extracted": "Patel Gowda",
          "comparison": {
            "engine": "probabilistic",
            "similarity": 0.02
          }
        }
      },
      "comments": "Applicant on file is John Smith, but the third-party record identifies Patel Gowda. Employer location is Grand Junction, CO. No salary or rehire eligibility data was present in the record.",
      "confidence": 0.25,
      "providedZip": null,
      "doNotContact": false,
      "providedCity": null,
      "providedState": null,
      "providedAddress1": null,
      "providedAddress2": null,
      "verifiedEntityId": null,
      "verifierLastName": null,
      "verifierPosition": null,
      "verifiedContactId": null,
      "verifierFirstName": null
    }
  },
  "event": "verification.action_required",
  "occurredAt": "2026-06-09T22:48:36.062Z"
}

OTHER (EMAIL channel)

Non-JSON OTHER webhooks omit message and typically carry review context in metadata alone. Verified EMAIL inbound with wrong applicant or title data (outcome verified with field mismatches) usually emits verification.completed with verificationResult.discrepancy: true, not verification.action_required — see Discrepancy Detection.

{
  "event": "verification.action_required",
  "occurredAt": "2025-12-02T09:15:00.000Z",
  "data": {
    "searchId": "emp_1205",
    "externalSearchId": "emp-other-001",
    "searchType": "EMPLOYMENT",
    "reasonCode": "OTHER",
    "status": "Needs Clarification",
    "channel": "EMAIL",
    "metadata": {
      "note": "Employer replied with partial data; applicant name mismatch requires confirmation",
      "requiresHumanReview": true
    }
  }
}

Event: verification.notification

Sent during intermediate stages of verification process.

Data Fields

Field	Type	Required	Description
`searchId`	`string` (UUID)	Yes	Search identifier
`externalSearchId`	`string`	No	External identifier
`verificationId`	`string` (UUID)	No	Verification record ID when linked
`searchType`	`SearchType`	No	Type of verification
`notificationType`	`VerificationNotificationType`	No	Notification category
`messageId`	`string`	No	Provider message ID
`threadId`	`string`	No	Conversation thread ID
`from`	`string`	No	Sender identity
`subject`	`string`	No	Subject/description
`classification`	`Classification`	No	Message classification
`channels`	`VerificationChannel[]`	No	Active channels
`contactPlan`	`ContactPlanEntry[]`	No	Contact plan entries for `CONTACT_PLAN` and contact mutation notifications
`outboundAttempt`	`OutboundAttempt`	No	Attempt details when `notificationType` is `OUTBOUND_ATTEMPT`
`outboundControl`	`OutboundControl`	No	Pause/resume details when `notificationType` is `OUTBOUND_PAUSED`, `OUTBOUNDS_PAUSED`, etc.
`inboundMetadata`	`InboundMetadata`	No	Inbound details when `notificationType` is `INBOUND_MESSAGE`
`metadata`	`object`	No	Additional context for `SEARCH_UPDATED`, `INBOUND_RECEIVED_DETAIL`, and contact mutation notifications
`employmentVerification`	`EmploymentVerification`	Conditional	Root-level highest-confidence employment object when present on `INBOUND_RECEIVED_DETAIL` (not nested in `metadata.extractedData`)
`educationVerification`	`EducationVerification`	Conditional	Root-level highest-confidence education object when present on `INBOUND_RECEIVED_DETAIL`

VerificationNotificationType Enum

Value	Description
`CONTACT_PLAN`	Research identified viable contacts
`CONTACT_PLAN_ADDED`	Contact added to the plan via the public contact API
`CONTACT_PLAN_UPDATED`	Contact updated via the public contact API
`CONTACT_PLAN_REMOVED`	Contact removed from the plan via the public contact API
`CONTACT_PLAN_MARKED_ACCURATE`	Contact was marked accurate through the public contact APIs
`CONTACT_PLAN_MARKED_INACCURATE`	Contact was marked inaccurate through the public contact APIs
`OUTBOUND_ATTEMPT`	Outbound communication attempt made
`OUTBOUND_PAUSED`	A single pending outbound was paused
`OUTBOUNDS_PAUSED`	All pending outbounds for the search were paused
`OUTBOUND_RESUMED`	A single paused outbound was resumed
`OUTBOUNDS_RESUMED`	All paused outbounds for the search were resumed
`INBOUND_MESSAGE`	Inbound communication received (summary notification)
`INBOUND_RECEIVED_DETAIL`	Fires for every inbound message (email, voice/fax transcription, or JSON/API submission) alongside `INBOUND_MESSAGE`, carrying fuller message context in `metadata`, full extraction at `metadata.extractedData`, and a root-level `employmentVerification` or `educationVerification` object when available.
`SEARCH_UPDATED`	Search was updated through the order-scoped PATCH search endpoint (v1: status changes)

Classification Object

Field	Type	Description
`type`	`string`	Classification label (e.g., `VERIFICATION_RESPONSE`, `CALLBACK_REQUEST`, `INFO_REQUEST`)
`confidence`	`number`	Confidence score (0-1)

ContactPlanEntry Object

CONTACT_PLAN is emitted after research discovers viable contacts. Contact changes through the public Manage Search Contacts endpoints use CONTACT_PLAN_ADDED, CONTACT_PLAN_UPDATED, or CONTACT_PLAN_REMOVED. Accuracy marks use CONTACT_PLAN_MARKED_ACCURATE or CONTACT_PLAN_MARKED_INACCURATE and include metadata.accuracyStatus plus metadata.reason.

Field	Type	Description
`name`	`string`	Contact name
`title`	`string`	Job title/role
`entityName`	`string`	Organization name
`location`	`string`	Location
`method`	`string`	Contact method: `EMAIL`, `VOICE`, `FAX`, or `THIRD_PARTY`
`destination`	`string`	Email, phone, fax number, or vendor ID
`source`	`string`	Research source (e.g., `Search history`, `Web`)
`confidence`	`number \| null`	Confidence score (0-1) for this contact, or null
`notes`	`string`	Additional context about this contact

When a contact mutation notification is emitted, metadata may include:

Field	Type	Description
`contactId`	`string`	Contact ID that was added, updated, or removed
`contactName`	`string`	Human-readable contact name when available

When a SEARCH_UPDATED notification is emitted, metadata includes:

Field	Type	Description
`updatedFields`	`string[]`	Fields updated by the endpoint. V1 always includes `searchStatus`
`previousStatus`	`string`	Search status before the update
`currentStatus`	`string`	Search status after the update
`reason`	`string`	Optional API-supplied reason
`source`	`string`	`api`
`trigger`	`string`	`search_update`

Understanding Confidence Scores: Confidence scores (0-1) indicate the system’s trust in the contact information:

0.9-1.0: High confidence - Previously verified contacts, organization preferences with strict language
0.7-0.89: Medium-high confidence - Verified contacts without strict language, internal database matches
0.5-0.69: Medium confidence - Web research results, parent organization contacts
< 0.5: Lower confidence - Uncertain matches, limited information
null: No confidence score available (third-party vendors, manual entries)

The system uses confidence scores to:

Determine outbound attempt priority (higher confidence contacts attempted first)
Apply minimum confidence thresholds per channel (configurable in organization policy)
Filter out low-quality contacts before outbound attempts

OutboundAttempt Object

Field	Type	Description
`channel`	`VerificationChannel`	Channel used
`attemptNumber`	`number`	1-based attempt index
`contactName`	`string`	Contact name
`contactTitle`	`string`	Contact title
`contactEntity`	`string`	Organization
`destination`	`string`	Email/phone/fax destination
`metadata`	`object`	Channel-specific details (e.g., `{ "callId": "..." }`)

OutboundControl Object

Used for pause/resume notification types: OUTBOUND_PAUSED, OUTBOUNDS_PAUSED, OUTBOUND_RESUMED, and OUTBOUNDS_RESUMED.

Field	Type	Description
`action`	`string`	`PAUSE_OUTBOUND` or `RESUME_OUTBOUND`
`outboundId`	`string`	Present for single-outbound pause/resume requests
`reason`	`string`	Optional reason supplied to the API
`count`	`number`	Number of jobs plus contact attempts paused or resumed
`activitiesMarked`	`number`	Number of dashboard activity records marked as paused or resumed
`trigger`	`string`	`api`
`outbounds`	`OutboundControlItem[]`	Present for bulk pause/resume requests; lists the affected outbound attempts

OutboundControlItem Object

Field	Type	Description
`id`	`string`	Outbound activity or attempt ID
`method`	`string`	Method such as `EMAIL`, `PHONE`, or `FAX`
`contactId`	`string`	Contact ID when linked
`attemptDate`	`string`	Scheduled attempt timestamp
`destination`	`string`	Email, phone number, or fax number

InboundMetadata Object

Field	Type	Description
`summary`	`string`	Content summary
`title`	`string`	Headline/title
`ticketUrl`	`string`	Link to ticket/entry
`linkLabel`	`string`	Display label for URL
`source`	`string`	Source (e.g., `MICROSOFT_GRAPH`, `FAX_WEBHOOK`)

INBOUND_RECEIVED_DETAIL metadata object

Used when notificationType is INBOUND_RECEIVED_DETAIL (all inbound channels return the highest-confidence root-level verification object).

Field	Type	Description
`source`	`string`	Always `inbound` for API-submitted notifications
`channel`	`string`	Verification channel (`JSON`, `EMAIL`, `FAX`, `VOICE`)
`timestamp`	`string`	Message timestamp from the inbound request
`to`	`string`	Recipient identity (for JSON channel, typically `"JSON"`)
`rawBody`	`string`	Raw message body (JSON string for JSON channel)
`extractedData`	`object`	Best-match scalar extraction and comparison metadata for JSON channel. Does not include duplicate `employmentVerification` / `educationVerification` objects (those are at `data` root). See submit-inbound-notification for JSON field definitions
`attachments`	`array`	Attachment processing summary
`upstreamProvider`	`string`	Provider from inbound `metadata.provider` (JSON channel)
`upstreamLink`	`string`	Optional upstream link from inbound metadata

JSON channel extractedData highlights (under metadata.extractedData; the selected verification object is at data root):

_processedFromJson, _thirdPartyProvider — processing provenance
employerName, jobTitle, startDate, endDate, employerLocation, extractedApplicantName, refId, searchType, outcome — best-match scalar extraction (same source as employmentVerification)
verifiedDates, verifiedContent, optional extraction — structured extraction mirrors for backward compatibility
applicantMismatch, _requiresManualReview — operational boolean flags when a critical mismatch on the best-match row triggers manual review

Not included: applicantMismatches and applicantDiscrepancies have been removed from webhook and inbound notification payloads. Use employmentVerification.fields / educationVerification.fields for selected-record field comparison detail. Root-level verification object (data.employmentVerification / data.educationVerification):

Normalized verification objects with per-field comparison metadata in fields (type, status, expected, extracted, comparison.engine, optional similarity or distance)
JSON channel: one element per provider history row, each with confidence, sorted descending (see the Employment Verification (JSON channel) example at confidences 0.94, 0.22, 0.05)
Fields such as salary, rehire, reasonLeft, and contactNumber may be not_checked with comparison.engine: "none" when order data has no comparable value
Omitted from metadata.extractedData to avoid duplication

Per-search policy may set notifications.includeRawInboundInWebhook: false to strip rawBody and extractedData from the delivered webhook (activity records retain full metadata).

Example: CONTACT_PLAN

{
  "event": "verification.notification",
  "occurredAt": "2025-12-02T15:30:00.000Z",
  "data": {
    "searchId": "7c7b8f66-7f6a-4b52-9e85-8b3f5b7c1111",
    "externalSearchId": "contact-plan-001",
    "searchType": "EMPLOYMENT",
    "notificationType": "CONTACT_PLAN",
    "contactPlan": [
      {
        "name": "Casey Morgan",
        "title": "HR Generalist",
        "entityName": "St. Luke Medical Center",
        "location": "Denver, CO",
        "method": "EMAIL",
        "destination": "hr@stlukemed.org",
        "source": "Search history"
      },
      {
        "name": "Nurse Staffing Desk",
        "title": null,
        "entityName": "St. Luke Medical Center",
        "location": "Denver, CO",
        "method": "VOICE",
        "destination": "+13035551234",
        "source": "Internal research"
      },
      {
        "name": null,
        "title": null,
        "entityName": "St. Luke Medical Center",
        "location": null,
        "method": "FAX",
        "destination": "+13035559876",
        "source": "Web"
      }
    ]
  }
}

Example: OUTBOUND_ATTEMPT

{
  "event": "verification.notification",
  "occurredAt": "2025-12-02T09:15:00.000Z",
  "data": {
    "searchId": "ba95128e-0e4e-4235-9b08-5554e4c95452",
    "externalSearchId": "emp-885",
    "searchType": "EMPLOYMENT",
    "notificationType": "OUTBOUND_ATTEMPT",
    "outboundAttempt": {
      "attemptNumber": 2,
      "channel": "VOICE",
      "contactName": "Patrice Wynn",
      "contactTitle": "HR Coordinator",
      "contactEntity": "Green Valley Rehab",
      "destination": "+17025559876",
      "metadata": {
        "callId": "call_23cb8da5",
        "callDurationSeconds": 145
      }
    }
  }
}

Example: INBOUND_MESSAGE (Email)

{
  "event": "verification.notification",
  "occurredAt": "2025-12-02T20:00:00.000Z",
  "data": {
    "searchId": "550e8400-e29b-41d4-a716-446655440000",
    "externalSearchId": "candidate-789",
    "verificationId": "660e8400-e29b-41d4-a716-446655440000",
    "searchType": "EMPLOYMENT",
    "notificationType": "INBOUND_MESSAGE",
    "messageId": "msg_abc123",
    "threadId": "thread_xyz789",
    "from": "hr@acme.com",
    "subject": "RE: Employment Verification Request",
    "classification": {
      "type": "VERIFICATION_RESPONSE",
      "confidence": 0.95
    },
    "channels": ["EMAIL"],
    "inboundMetadata": {
      "summary": "HR confirmed employment dates and job title",
      "source": "MICROSOFT_GRAPH"
    }
  }
}

Example: INBOUND_MESSAGE (Voice)

{
  "event": "verification.notification",
  "occurredAt": "2025-12-02T14:05:00.000Z",
  "data": {
    "searchId": "search_9c1d6a41-5ef1-4c80-9520-8456682e1d9f",
    "externalSearchId": "emp-voice-303",
    "verificationId": "vr_240d4e6a-abc9-4d0d-9e8f-5af18bb8acaf",
    "searchType": "EMPLOYMENT",
    "notificationType": "INBOUND_MESSAGE",
    "messageId": "msg_voice_456",
    "threadId": "thread_aggregate_123",
    "from": "+14255550123",
    "subject": "Voicemail transcription available",
    "classification": {
      "type": "CALLBACK_REQUEST",
      "confidence": 0.81
    },
    "channels": ["VOICE", "EMAIL"],
    "inboundMetadata": {
      "summary": "Caller requested callback to verify employment details",
      "source": "VOICEMAIL_TRANSCRIPTION"
    }
  }
}

Example: INBOUND_MESSAGE (Urgent)

{
  "event": "verification.notification",
  "occurredAt": "2025-12-02T18:04:00.000Z",
  "data": {
    "searchId": "search_04c7821e-8be3-4b4f-82b4-2a32b51e7f10",
    "externalSearchId": "emp-urgent-12",
    "verificationId": "vr_34d4d6e7-0bb1-46da-999b-d3625ddd7a54",
    "searchType": "EMPLOYMENT",
    "notificationType": "INBOUND_MESSAGE",
    "messageId": "msg_8891",
    "threadId": "thread_552",
    "from": "records@oakridgeclinic.com",
    "subject": "RE: Verification needs signed release",
    "classification": {
      "type": "INFO_REQUEST",
      "confidence": 0.9
    },
    "channels": ["EMAIL"],
    "inboundMetadata": {
      "summary": "Clinic requires signed authorization before release",
      "title": "Authorization Required",
      "ticketUrl": "https://desk.example.com/tickets/1442",
      "linkLabel": "View Ticket",
      "source": "MICROSOFT_GRAPH"
    }
  }
}

Example: INBOUND_RECEIVED_DETAIL (JSON channel)

Emitted after a successful channel: "JSON" inbound notification when the best-match history row aligns with applicant-provided fields under tenant comparison settings. Top-level applicantMismatch is omitted; eventual verification.completed closeout may still set discrepancy: false when only non-critical field-level differences remain (for example fields.position.status: "match_with_discrepancy"). Normalized rows appear at data.employmentVerification, not inside metadata.extractedData.

{
  "event": "verification.notification",
  "occurredAt": "2026-06-09T22:00:00.000Z",
  "data": {
    "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
    "externalSearchId": "EXT-DEV-1781042158637-1",
    "searchType": "EMPLOYMENT",
    "notificationType": "INBOUND_RECEIVED_DETAIL",
    "from": "test-provider",
    "classification": {
      "type": "VERIFICATION",
      "confidence": 0.94
    },
    "employmentVerification": {
      "confidence": 0.94,
      "fields": {
        "companyName": {
          "type": "string",
          "status": "match",
          "expected": "Pablo's Pizza",
          "extracted": "Pablos Pizza",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        },
        "position": {
          "type": "string",
          "status": "match_with_discrepancy",
          "expected": "Senior Software Developer",
          "extracted": "Senior Software Engineer",
          "comparison": { "engine": "probabilistic", "similarity": 0.98 }
        },
        "startDate": {
          "type": "date",
          "status": "match",
          "expected": "2022-01-01",
          "extracted": "2022-01-01",
          "comparison": { "engine": "deterministic", "distance": 0 }
        },
        "endDate": {
          "type": "date",
          "reason": "Dates diverge by 20 days; expected \"2023-01-01\", extracted \"2023-01-21\"",
          "status": "mismatch",
          "expected": "2023-01-01",
          "extracted": "2023-01-21",
          "comparison": { "engine": "deterministic", "distance": 20 }
        },
        "location": {
          "type": "string",
          "status": "match",
          "expected": "Grand Junction, CO",
          "extracted": "Grand Junction, CO",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        },
        "applicantName": {
          "type": "string",
          "status": "match",
          "expected": "John Smith",
          "extracted": "John Smith",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        }
      }
    },
    "metadata": {
      "source": "inbound",
      "channel": "JSON",
      "timestamp": "2026-06-09T22:00:00.000Z",
      "to": "JSON",
      "upstreamProvider": "test-provider",
      "extractedData": {
        "outcome": "verified",
        "refId": "EXT-DEV-1781042158637-1",
        "searchType": "EMPLOYMENT",
        "employerName": "Pablos Pizza",
        "jobTitle": "Senior Software Engineer",
        "startDate": "2022-01-01",
        "endDate": "2023-01-01",
        "employerLocation": "Grand Junction, CO",
        "extractedApplicantName": "John Smith",
        "_processedFromJson": true,
        "_thirdPartyProvider": "test-provider"
      }
    }
  }
}

Example: INBOUND_RECEIVED_DETAIL (JSON channel — discrepancies only)

Same webhook shape and search as above. The non-critical title difference appears on employmentVerification.fields.position (status: "match_with_discrepancy") without applicantMismatch in metadata.extractedData. applicantDiscrepancies is not returned — use fields.* instead.

{
  "event": "verification.notification",
  "occurredAt": "2026-06-09T22:00:00.000Z",
  "data": {
    "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
    "externalSearchId": "EXT-DEV-1781042158637-1",
    "searchType": "EMPLOYMENT",
    "notificationType": "INBOUND_RECEIVED_DETAIL",
    "from": "test-provider",
    "classification": { "type": "VERIFICATION", "confidence": 0.94 },
    "employmentVerification": {
      "confidence": 0.94,
      "fields": {
        "companyName": {
          "type": "string",
          "status": "match",
          "expected": "Pablo's Pizza",
          "extracted": "Pablos Pizza",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        },
        "position": {
          "type": "string",
          "status": "match_with_discrepancy",
          "expected": "Senior Software Developer",
          "extracted": "Senior Software Engineer",
          "comparison": { "engine": "probabilistic", "similarity": 0.98 }
        },
        "startDate": {
          "type": "date",
          "status": "match",
          "expected": "2022-01-01",
          "extracted": "2022-01-01",
          "comparison": { "engine": "deterministic", "distance": 0 }
        },
        "endDate": {
          "type": "date",
          "reason": "Dates diverge by 9 days; expected \"2023-01-01\", extracted \"2023-01-10\"",
          "status": "mismatch",
          "expected": "2023-01-01",
          "extracted": "2023-01-10",
          "comparison": { "engine": "deterministic", "distance": 9 }
        },
        "location": {
          "type": "string",
          "status": "match",
          "expected": "Grand Junction, CO",
          "extracted": "Grand Junction, CO",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        }
      }
    },
    "metadata": {
      "source": "inbound",
      "channel": "JSON",
      "timestamp": "2026-06-09T22:00:00.000Z",
      "to": "JSON",
      "upstreamProvider": "test-provider",
      "extractedData": {
        "outcome": "verified",
        "employerName": "Pablos Pizza",
        "jobTitle": "Senior Software Engineer",
        "startDate": "2022-01-01",
        "endDate": "2023-01-01",
        "employerLocation": "Grand Junction, CO",
        "_processedFromJson": true,
        "_thirdPartyProvider": "test-provider"
      }
    }
  }
}

Example: INBOUND_RECEIVED_DETAIL (JSON channel — critical mismatch)

Emitted after a successful channel: "JSON" inbound notification. When a critical mismatch triggers escalation, metadata.extractedData may include applicantMismatch: true and _requiresManualReview: true. Field-level detail is on employmentVerification.fields — applicantMismatches and applicantDiscrepancies are not returned.

{
  "event": "verification.notification",
  "occurredAt": "2026-06-09T22:00:00.000Z",
  "data": {
    "searchId": "86bc0a43-6a10-4f85-a093-e4244ed78107",
    "externalSearchId": "EXT-DEV-1781042158637-1",
    "searchType": "EMPLOYMENT",
    "notificationType": "INBOUND_RECEIVED_DETAIL",
    "from": "test-provider",
    "classification": {
      "type": "VERIFICATION",
      "confidence": 0.94
    },
    "employmentVerification": {
      "confidence": 0.94,
      "fields": {
        "companyName": {
          "type": "string",
          "status": "match",
          "expected": "Pablo's Pizza",
          "extracted": "Pablos Pizza",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        },
        "position": {
          "type": "string",
          "status": "match_with_discrepancy",
          "expected": "Senior Software Developer",
          "extracted": "Senior Software Engineer",
          "comparison": { "engine": "probabilistic", "similarity": 0.98 }
        },
        "startDate": {
          "type": "date",
          "status": "mismatch",
          "expected": "2022-01-01",
          "extracted": "2021-01-01",
          "comparison": { "engine": "deterministic", "distance": 365 }
        },
        "endDate": {
          "type": "date",
          "status": "match",
          "expected": "2023-01-01",
          "extracted": "2023-01-01",
          "comparison": { "engine": "deterministic", "distance": 0 }
        },
        "location": {
          "type": "string",
          "status": "match",
          "expected": "Grand Junction, CO",
          "extracted": "Grand Junction, CO",
          "comparison": { "engine": "deterministic", "similarity": 1 }
        }
      }
    },
    "metadata": {
      "source": "inbound",
      "channel": "JSON",
      "timestamp": "2026-06-09T22:00:00.000Z",
      "to": "JSON",
      "upstreamProvider": "test-provider",
      "extractedData": {
        "outcome": "verified",
        "employerName": "Pablos Pizza",
        "jobTitle": "Senior Software Engineer",
        "startDate": "2021-01-01",
        "endDate": "2023-01-01",
        "employerLocation": "Grand Junction, CO",
        "_processedFromJson": true,
        "_thirdPartyProvider": "test-provider",
        "applicantMismatch": true,
        "_requiresManualReview": true
      }
    }
  }
}

Third-Party Vendor Reference

When reasonCode is THIRD_PARTY_RECORD, the metadata object includes vendor information. These same canonical vendor codes are accepted by searchConfig.thirdPartyBan for per-search third-party suppression; UNKNOWN is not accepted in the ban list. See Third-party ban for client-facing examples.

Employment Vendors

Standardized Name	Source Keywords / Aliases
`TALX_WORK_NUMBER`	TALX, The Work Number, INVerify, WNFE, Equifax
`THOMAS_AND_COMPANY`	Thomas and Company, Thomas & Co
`PRECHECK`	PreCheck, EmpCheck, EmployCheck
`VERIFYTODAY`	VerifyToday, Verify Today System
`CCCVERIFY`	CCC Verify, CCCVerify
`EXPERIAN`	Experian Verify, uConfirm
`QUICKCONFIRM`	QuickConfirm
`ACT1`	ACT 1, ActOne
`CERTREE_EMP`	Certree (employment searches)
`DELTAT`	Delta-T Group
`DRIVERIQ`	Driver IQ
`EMERALD_HEALTH_SERVICES`	Emerald Health Services
`EMPINFO`	EmpInfo
`EVADVANTAGE`	EvAdvantage
`GROUPONE`	GroupOne
`TENSTREET`	Tenstreet
`TRUECONFIRM`	TrueConfirm
`TRUEWORK`	Truework, True Work
`TRUV`	Truv
`VAULT_VERIFY`	Vault Verify
`VERIFENT`	Verifent
`VERIFY_FAST`	Verify Fast, VerifyFast
`VERIFY_ADVANTAGE`	VerifyAdvantage, VerifyDirect
`VERISAFE_JOBS`	VeriSafe Jobs
`VERIFICATION_MANAGER`	Verification Manager
`JOBTRAX`	JobTrax

Education Vendors

Standardized Name	Source Keywords / Aliases
`NSCH`	National Student Clearinghouse, NSC, NSCH, DegreeVerify, DiplomaVerify
`NEED_MY_TRANSCRIPT`	Need My Transcript, NeedMyTranscript
`PARCHMENT`	Parchment
`SCRIBORDER`	ScribOrder, scriborder.com
`AURADATA`	AuraData, auradata.com
`DIPLOMA_SENDER`	Diploma Sender, diplomasender.com
`CERTREE_EDU`	Certree EDU
`CHICAGO_PUBLIC_SCHOOLS`	Chicago Public Schools records portal
`GRAMARCY`	Gramarcy / Gramercy
`IEC`	IEC Corporation
`INDIANA_ARCHIVES`	Indiana Archives
`MERIDIAN_INSTITUTE`	Meridian Institute
`OTTAWA_UNIVERSITY`	Ottawa University
`TCSG`	Technical College System of Georgia (TCSG)
`VERIF_Y_INC`	Verif-Y Inc.
`UNKNOWN`	Unrecognized vendor

Delivery, retries, and testing

Retry policy, signature verification handlers, idempotency, and local testing tools (ngrok, webhook.site) are documented once in Webhook Integration. Organization-level webhook defaults: Webhook Integration — Organization-level configuration. SLA and escalation behavior: SLA and escalation.

“Theary” is the product/platform name reflected in this wire-level identifier. It refers to the same product as “SNH AI,” the company name used elsewhere in these docs. ↩

​Webhook Events

​Payload Structure

​Top-Level Fields

​Payload Enrichment

​WebhookEventType Enum

​HTTP Headers

​Signature Verification

​Common Enums

​SearchType

​VerificationChannel

​StandardOutcomeCode

​Event: verification.completed

​Data Fields

​VerificationResult Object

​VerifierProfile Object

​Verification questions on completed events

​Example: completed payload with custom question answers

​Understanding Provided vs Verified Fields

​EmploymentVerification Object

​Fields-based comparison (fields)

​Backward-compatible flat fields

​Example: Employment Verification (Email — synchronous inbound response)

​Example: Employment Verification (Voice)

​Example: Employment Verification (JSON channel)

​EducationVerification Object

​Fields-based comparison (fields)

​Backward-compatible flat fields

​Example: Education Verification (Fax)

​Example: Education Verification (No Record)

​AccreditationResult Object

​Event: verification.action_required

​Data Fields

​ActionRequiredReasonCode Enum

​Questionnaire-related metadata (HUMAN_ESCALATION)

​ContactPayload Object

​EmploymentContactPayload

​EducationContactPayload

​Example: THIRD_PARTY_RECORD (Employment)

​Example: THIRD_PARTY_RECORD (Education with Accreditation)

​Example: UPSTREAM_ISSUE

​Example: SYSTEM_FAILURE

​Example: SLA_REACHED

​Example: HUMAN_ESCALATION (EMAIL — no message)

​Example: HUMAN_ESCALATION (JSON channel — includes message)

​Example: HUMAN_ESCALATION (missing required custom question)

​Example: HUMAN_ESCALATION (invalid custom question marks)

​Example: HUMAN_ESCALATION (voice only)

​Example: OTHER

​OTHER (JSON channel)

​OTHER (EMAIL channel)

​Event: verification.notification

​Data Fields

​VerificationNotificationType Enum

​Classification Object

​ContactPlanEntry Object

​OutboundAttempt Object

​OutboundControl Object

​OutboundControlItem Object

​InboundMetadata Object

​INBOUND_RECEIVED_DETAIL metadata object

​Example: CONTACT_PLAN

​Example: OUTBOUND_ATTEMPT

​Example: INBOUND_MESSAGE (Email)

​Example: INBOUND_MESSAGE (Voice)

​Example: INBOUND_MESSAGE (Urgent)

​Example: INBOUND_RECEIVED_DETAIL (JSON channel)

​Example: INBOUND_RECEIVED_DETAIL (JSON channel — discrepancies only)

​Example: INBOUND_RECEIVED_DETAIL (JSON channel — critical mismatch)

​Third-Party Vendor Reference

​Employment Vendors

​Education Vendors

​Delivery, retries, and testing

Footnotes

Webhook Events

Payload Structure

Top-Level Fields

Payload Enrichment

WebhookEventType Enum

HTTP Headers

Signature Verification

Common Enums

SearchType

VerificationChannel

StandardOutcomeCode

Event: verification.completed

Data Fields

VerificationResult Object

VerifierProfile Object

Verification questions on completed events

Example: completed payload with custom question answers

Understanding Provided vs Verified Fields

EmploymentVerification Object

Fields-based comparison (`fields`)

Backward-compatible flat fields

Example: Employment Verification (Email — synchronous inbound response)

Example: Employment Verification (Voice)

Example: Employment Verification (JSON channel)

EducationVerification Object

Fields-based comparison (`fields`)

Backward-compatible flat fields

Example: Education Verification (Fax)

Example: Education Verification (No Record)

AccreditationResult Object

Event: verification.action_required

Data Fields

ActionRequiredReasonCode Enum

Questionnaire-related `metadata` (HUMAN_ESCALATION)

ContactPayload Object

EmploymentContactPayload

EducationContactPayload

Example: THIRD_PARTY_RECORD (Employment)

Example: THIRD_PARTY_RECORD (Education with Accreditation)

Example: UPSTREAM_ISSUE

Example: SYSTEM_FAILURE

Example: SLA_REACHED

Example: HUMAN_ESCALATION (EMAIL — no `message`)

Example: HUMAN_ESCALATION (JSON channel — includes `message`)

Example: HUMAN_ESCALATION (missing required custom question)

Example: HUMAN_ESCALATION (invalid custom question marks)

Example: HUMAN_ESCALATION (voice only)

Example: OTHER

OTHER (JSON channel)

OTHER (EMAIL channel)

Event: verification.notification

Data Fields

VerificationNotificationType Enum

Classification Object

ContactPlanEntry Object

OutboundAttempt Object

OutboundControl Object

OutboundControlItem Object

InboundMetadata Object

INBOUND_RECEIVED_DETAIL metadata object

Example: CONTACT_PLAN

Example: OUTBOUND_ATTEMPT

Example: INBOUND_MESSAGE (Email)

Example: INBOUND_MESSAGE (Voice)

Example: INBOUND_MESSAGE (Urgent)

Example: INBOUND_RECEIVED_DETAIL (JSON channel)

Example: INBOUND_RECEIVED_DETAIL (JSON channel — discrepancies only)

Example: INBOUND_RECEIVED_DETAIL (JSON channel — critical mismatch)

Third-Party Vendor Reference

Employment Vendors

Education Vendors

Delivery, retries, and testing