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

# Webhook Events

> Complete reference for webhook payload structures, event types, and integration patterns

# 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:

```json theme={null}
{
  "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
* `researchDecisionLog`: Audit trail of contact discovery and research decisions

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

* `channel`: Single terminal channel used (EMAIL, VOICE, or FAX)
* Full verification object with provided vs verified fields
* `discrepancy`: Boolean flag for VERIFIED outcomes when provided data differs from verified data

**For EDUCATION searches:**

* `accreditation`: Institutional accreditation status from DAPIP database
* Includes campus details, accreditor information, and historical timeline

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

***

## 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`[^1]                     |
| `Authorization`        | `string`           | Basic auth header when configured (format: `Basic <base64>`) |
| `X-Webhook-Signature`  | `string`           | HMAC-SHA256 signature when secret is configured              |

[^1]: "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.

***

## 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](/webhooks/integration#security-signature-verification).

***

## 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`  | Generic JSON/API-submitted inbound record. |

### 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                    |
| `accreditation`       | `AccreditationResult` | No       | Accreditation data (education searches only)           |
| `researchDecisionLog` | `ResearchDecisionLog` | No       | Audit trail of research decisions and sources searched |

### 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                           |
| `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          | True if verified data differs from provided data |
| `employmentVerification` | `EmploymentVerification` | Conditional | Present for `EMPLOYMENT` searches                |
| `educationVerification`  | `EducationVerification`  | Conditional | Present for `EDUCATION` searches                 |
| `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 |

### ResearchDecisionLog Object

Audit trail of research decisions made during contact discovery. Provides transparency into which sources were searched, why certain decisions were made, and the reasoning behind the final contact plan.

| Field              | Type                 | Required | Description                                          |
| ------------------ | -------------------- | -------- | ---------------------------------------------------- |
| `timestamp`        | `string` (ISO 8601)  | Yes      | When research was initiated                          |
| `organizationName` | `string`             | Yes      | Organization that was researched                     |
| `location`         | `string`             | No       | Organization location (City, State format)           |
| `decisions`        | `ResearchDecision[]` | Yes      | Ordered list of research decisions and their results |

#### ResearchDecision Object

| Field        | Type                | Required | Description                                                  |
| ------------ | ------------------- | -------- | ------------------------------------------------------------ |
| `stage`      | `string`            | Yes      | Research stage (e.g., `ORG_PREFERENCE_SEARCH`, `WEB_SEARCH`) |
| `decision`   | `string`            | Yes      | Decision outcome: `PROCEED`, `SKIP`, `HALT`, `ESCALATE`      |
| `reasoning`  | `string`            | Yes      | Detailed explanation of why this decision was made           |
| `confidence` | `number` (0-1)      | No       | Confidence score for this decision                           |
| `context`    | `object`            | No       | Additional context data specific to this stage               |
| `timestamp`  | `string` (ISO 8601) | Yes      | When this decision was made                                  |

#### Research Stages

| Stage                      | Description                                                   |
| -------------------------- | ------------------------------------------------------------- |
| `ORG_PREFERENCE_SEARCH`    | Checked organization preferences from notes/comments          |
| `VERIFIED_CONTACTS_SEARCH` | Searched verified contacts from past successful verifications |
| `INTERNAL_SEARCH`          | Searched internal knowledge base                              |
| `PARENT_ORG_SEARCH`        | Searched parent organization records                          |
| `WEB_SEARCH`               | Searched web via OpenAI web research for contact information  |
| `CHANNEL_POLICY_CHECK`     | Validated channel policies and constraints                    |
| `FINAL_RESULT`             | Final research outcome and contact count                      |

#### Example: Research Decision Log

```json theme={null}
{
  "timestamp": "2025-12-09T10:30:00Z",
  "organizationName": "Acme Corporation",
  "location": "San Francisco, CA",
  "decisions": [
    {
      "stage": "ORG_PREFERENCE_SEARCH",
      "decision": "PROCEED",
      "reasoning": "Found 2 contacts from organization preference table with STRICT LANGUAGE. Research will STOP here and use only these approved contacts.",
      "context": {
        "contactsFound": 2,
        "strictLanguage": true,
        "stoppedDueToStrictLanguage": true
      },
      "timestamp": "2025-12-09T10:30:01Z"
    },
    {
      "stage": "FINAL_RESULT",
      "decision": "PROCEED",
      "reasoning": "Research completed with 2 contacts from organization preferences. Research was STOPPED due to strict language.",
      "context": {
        "finalContactsCount": 2,
        "strictLanguage": true,
        "researchStopped": true
      },
      "timestamp": "2025-12-09T10:30:02Z"
    }
  ]
}
```

***

## 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)
* 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
* `true`: One or more key fields differ (e.g., different job title, dates, location)

The comparison uses normalized values (case-insensitive, whitespace-trimmed, date formats normalized) to avoid false positives from formatting differences.

**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 provided (claimed) and verified fields.

#### Provided Fields (from applicant/requester)

| 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` (YYYY-MM-DD) | Claimed employment start date |
| `providedEndDate`       | `string` (YYYY-MM-DD) | Claimed employment end date   |
| `providedPosition`      | `string`              | Claimed job title             |
| `providedSalary`        | `string`              | Claimed compensation          |
| `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 Fields (from verification)

| 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` (YYYY-MM-DD) | Confirmed start date             |
| `verifiedEndDate`       | `string` (YYYY-MM-DD) | Confirmed end date               |
| `verifiedReasonLeft`    | `string`              | Reason for leaving employment    |
| `verifiedRehire`        | `boolean` or `null`   | Rehire eligibility               |
| `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               |

#### Example: Employment Verification (Email)

```json theme={null}
{
  "event": "verification.completed",
  "occurredAt": "2025-12-02T15:30:00.000Z",
  "data": {
    "searchId": "550e8400-e29b-41d4-a716-446655440000",
    "verificationId": "660e8400-e29b-41d4-a716-446655440000",
    "externalSearchId": "candidate-123",
    "searchType": "EMPLOYMENT",
    "status": "Completed",
    "channel": "EMAIL",
    "verificationResult": {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "searchId": "550e8400-e29b-41d4-a716-446655440000",
      "outcome": "VERIFIED",
      "submittedAt": "2025-12-02T15:30:00.000Z",
      "createdAt": "2025-12-02T14:00:00.000Z",
      "updatedAt": "2025-12-02T15:30:00.000Z",
      "channel": "EMAIL",
      "additionalComments": "Verification completed via email response",
      "discrepancy": false,
      "extractedData": {
        "employmentVerified": true,
        "employerName": "Acme Corporation",
        "jobTitle": "Software Engineer",
        "startDate": "2020-01-15",
        "endDate": "2023-12-31",
        "rehireEligibility": "Yes, eligible for rehire",
        "reasonForLeaving": "Accepted position at another company",
        "confidence": 0.95
      },
      "employmentVerification": {
        "providedCompanyName": "Acme Corporation",
        "providedPosition": "Software Engineer",
        "providedStartDate": "2020-01-15",
        "providedEndDate": "2023-12-31",
        "providedContactName": null,
        "providedContactNumber": null,
        "providedContactEmail": null,
        "providedLocation": "San Francisco, CA",
        "providedSalary": null,
        "providedAddress1": null,
        "providedAddress2": null,
        "providedCity": "San Francisco",
        "providedState": "CA",
        "providedZip": null,
        "verifiedEntityId": null,
        "verifiedCompanyName": "Acme Corporation",
        "verifiedContactName": "Marcia Harris",
        "verifiedContactNumber": "+14155551234",
        "verifiedContactEmail": "mharris@acme.com",
        "verifiedLocation": "San Francisco, CA",
        "verifiedPosition": "Software Engineer",
        "verifiedSalary": "$145,000/year",
        "verifiedContactId": null,
        "verifiedStartDate": "2020-01-15",
        "verifiedEndDate": "2023-12-31",
        "verifiedReasonLeft": "Accepted position at another company",
        "verifiedRehire": true,
        "comments": "Employee left in good standing",
        "doNotContact": false,
        "verifierFirstName": "Marcia",
        "verifierLastName": "Harris",
        "verifierPosition": "HR Manager"
      },
      "verifier": {
        "firstName": "Marcia",
        "lastName": "Harris",
        "position": "HR Manager"
      }
    }
  }
}
```

#### Example: Employment Verification (Voice)

```json theme={null}
{
  "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
      },
      "employmentVerification": {
        "providedCompanyName": "Tech Solutions",
        "providedPosition": "Developer",
        "providedStartDate": "2019-03-15",
        "providedEndDate": "2024-06-30",
        "providedContactName": null,
        "providedContactNumber": "+18005551234",
        "providedContactEmail": null,
        "providedLocation": "Austin, TX",
        "providedSalary": null,
        "providedAddress1": null,
        "providedAddress2": null,
        "providedCity": "Austin",
        "providedState": "TX",
        "providedZip": null,
        "verifiedEntityId": null,
        "verifiedCompanyName": "Tech Solutions Inc",
        "verifiedContactName": "James Wilson",
        "verifiedContactNumber": "+15125559876",
        "verifiedContactEmail": null,
        "verifiedLocation": "Austin, TX",
        "verifiedPosition": "Senior Developer",
        "verifiedSalary": null,
        "verifiedContactId": null,
        "verifiedStartDate": "2019-03-01",
        "verifiedEndDate": "2024-06-15",
        "verifiedReasonLeft": null,
        "verifiedRehire": 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"
      },
      "verifier": {
        "firstName": "James",
        "lastName": "Wilson",
        "position": "HR Coordinator"
      }
    }
  }
}
```

***

### EducationVerification Object

Complete education verification data with provided and verified fields.

#### Provided 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` (YYYY-MM-DD) | Attendance start date     |
| `providedEndDate`        | `string` (YYYY-MM-DD) | Attendance end date       |
| `providedGraduated`      | `string`              | Graduation status claimed |
| `providedGraduationDate` | `string` (YYYY-MM-DD) | Claimed graduation date   |

#### Verified Fields

| Field                    | Type                  | Description                    |
| ------------------------ | --------------------- | ------------------------------ |
| `verifiedEntityId`       | `string`              | Internal institution entity ID |
| `verifiedSchoolName`     | `string`              | Confirmed institution name     |
| `verifiedLocation`       | `string`              | Confirmed location             |
| `verifiedDegree`         | `string`              | Confirmed degree               |
| `verifiedMajor`          | `string`              | Confirmed major                |
| `verifiedMinor`          | `string`              | Confirmed minor                |
| `verifiedGpa`            | `string`              | Confirmed GPA                  |
| `verifiedStartDate`      | `string` (YYYY-MM-DD) | Confirmed start date           |
| `verifiedEndDate`        | `string` (YYYY-MM-DD) | Confirmed end date             |
| `verifiedGraduated`      | `string`              | Confirmed graduation status    |
| `verifiedGraduationDate` | `string` (YYYY-MM-DD) | Confirmed graduation date      |
| `verifiedContactName`    | `string`              | Registrar/contact name         |
| `verifiedContactNumber`  | `string`              | Contact phone                  |
| `verifiedContactEmail`   | `string`              | Contact email                  |
| `comments`               | `string`              | Additional comments            |
| `verifierFirstName`      | `string`              | Verifier first name            |
| `verifierLastName`       | `string`              | Verifier last name             |
| `verifierPosition`       | `string`              | Verifier title                 |

#### Example: Education Verification (Fax)

```json theme={null}
{
  "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": false,
      "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
      },
      "educationVerification": {
        "providedSchoolName": "Stanford University",
        "providedLocation": "Stanford, CA",
        "providedAddress1": null,
        "providedAddress2": null,
        "providedCity": "Stanford",
        "providedState": "CA",
        "providedZip": "94305",
        "providedContactName": null,
        "providedContactNumber": null,
        "providedContactEmail": null,
        "providedDegree": "BS Computer Science",
        "providedMajor": "Computer Science",
        "providedMinor": null,
        "providedStartDate": "2018-09-01",
        "providedEndDate": "2022-06-15",
        "providedGraduated": "Yes",
        "providedGraduationDate": "2022-06-15",
        "verifiedEntityId": null,
        "verifiedSchoolName": "Stanford University",
        "verifiedLocation": "Stanford, CA",
        "verifiedDegree": "Bachelor of Science",
        "verifiedMajor": "Computer Science",
        "verifiedMinor": null,
        "verifiedGpa": "3.84/4.0",
        "verifiedStartDate": "2018-09-01",
        "verifiedEndDate": "2022-06-12",
        "verifiedGraduated": "Yes",
        "verifiedGraduationDate": "2022-06-12",
        "verifiedContactName": "Registrar Services",
        "verifiedContactNumber": "+16507232300",
        "verifiedContactEmail": "registrar@stanford.edu",
        "comments": "Confirmed via sealed transcript",
        "verifierFirstName": "Regina",
        "verifierLastName": "Sloane",
        "verifierPosition": "Registrar"
      },
      "verifier": {
        "firstName": "Regina",
        "lastName": "Sloane",
        "position": "Registrar"
      }
    },
    "accreditation": {
      "reference": {
        "name": "Stanford University",
        "date": "2022-06-12",
        "city": "Stanford",
        "state": "CA"
      },
      "matches": [
        {
          "campus": {
            "dapipId": "243744",
            "locationName": "Stanford University",
            "parentInstitution": null,
            "locationType": "Institution",
            "city": "Stanford",
            "state": "CA",
            "address": "450 Serra Mall, Stanford, CA 94305",
            "url": "https://www.stanford.edu"
          },
          "accreditation": {
            "statusLabel": "Accredited",
            "isAccredited": true,
            "accreditor": "Western Association of Schools and Colleges, Senior College and University Commission",
            "programName": "Institutional Accreditation",
            "validFrom": "1949-01-01",
            "validThrough": null,
            "reason": "Accredited by WASC Senior College and University Commission from 1949-01-01 through present",
            "latestAction": {
              "date": "2024-05-15",
              "description": "Renewal of Accreditation",
              "justification": "In compliance with all accreditation standards",
              "agencyName": "WASC Senior College and University Commission"
            },
            "recordTimeline": [
              {
                "status": "Accredited",
                "accreditor": "WASC Senior College and University Commission",
                "programName": "Institutional Accreditation",
                "startDate": "1949-01-01",
                "endDate": null
              }
            ]
          }
        }
      ],
      "suggestions": [],
      "metadata": {
        "campusesConsidered": 1,
        "checkedOn": "2025-12-02",
        "dataSource": "GCS verifications-api-dataset-2026 (accreditation: InstitutionCampus, AccreditationRecords, AccreditationActions)",
        "accreditationStatus": "accredited"
      }
    }
  }
}
```

#### Example: Education Verification (No Record)

```json theme={null}
{
  "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": {
        "providedSchoolName": "State University",
        "providedLocation": "Columbus, OH",
        "providedDegree": "Bachelor of Arts",
        "providedMajor": "Psychology",
        "providedGraduationDate": "2019-05-15",
        "verifiedSchoolName": "State University",
        "verifiedDegree": null,
        "verifiedMajor": null,
        "verifiedGraduationDate": 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                                        |
| ------------- | ------------------------ | -------------------------------------------------- |
| `reference`   | `AccreditationReference` | Input parameters used for lookup                   |
| `matches`     | `AccreditationMatch[]`   | Exact campus/institution matches                   |
| `suggestions` | `CampusSummary[]`        | Alternate campuses when no exact match             |
| `metadata`    | `AccreditationMetadata`  | Lookup metadata and status                         |
| `note`        | `string`                 | Present when matches is empty; review instructions |

#### AccreditationReference Object

| Field   | Type     | Description                            |
| ------- | -------- | -------------------------------------- |
| `name`  | `string` | Institution name used for lookup       |
| `date`  | `string` | Reference date (graduation/attendance) |
| `city`  | `string` | City filter                            |
| `state` | `string` | State filter                           |

#### AccreditationMatch Object

| Field           | Type                      | Description                  |
| --------------- | ------------------------- | ---------------------------- |
| `campus`        | `CampusSummary`           | Campus/institution details   |
| `accreditation` | `AccreditationEvaluation` | Accreditation status details |

#### CampusSummary Object

| Field               | Type     | Description                                          |
| ------------------- | -------- | ---------------------------------------------------- |
| `dapipId`           | `string` | Database of Accredited Postsecondary Institutions ID |
| `locationName`      | `string` | Campus name                                          |
| `parentInstitution` | `string` | Parent institution name                              |
| `locationType`      | `string` | Type: `Institution`, `Branch`, etc.                  |
| `city`              | `string` | City                                                 |
| `state`             | `string` | State                                                |
| `address`           | `string` | Full address                                         |
| `url`               | `string` | Institution website                                  |

#### AccreditationEvaluation Object

| Field            | Type                          | Description                              |
| ---------------- | ----------------------------- | ---------------------------------------- |
| `statusLabel`    | `string`                      | Human-readable status                    |
| `isAccredited`   | `boolean`                     | Accreditation status                     |
| `accreditor`     | `string`                      | Accrediting agency name                  |
| `programName`    | `string`                      | Accreditation program                    |
| `validFrom`      | `string`                      | Accreditation start date                 |
| `validThrough`   | `string`                      | Accreditation end date (null if ongoing) |
| `reason`         | `string`                      | Explanation of accreditation status      |
| `latestAction`   | `AccreditationAction`         | Most recent accreditation action         |
| `recordTimeline` | `AccreditationTimelineItem[]` | Historical accreditation records         |

#### AccreditationMetadata Object

| Field                 | Type                  | Description                  |
| --------------------- | --------------------- | ---------------------------- |
| `campusesConsidered`  | `number`              | Number of campuses evaluated |
| `checkedOn`           | `string`              | Date of accreditation check  |
| `dataSource`          | `string`              | Data source identifier       |
| `accreditationStatus` | `AccreditationStatus` | Aggregated status            |

#### AccreditationStatus Enum

| Value            | Description                                  |
| ---------------- | -------------------------------------------- |
| `accredited`     | Institution is currently accredited          |
| `not_accredited` | Institution is not accredited                |
| `unknown`        | Accreditation status could not be determined |
| `not_found`      | No matching institution found                |

***

## Event: verification.action\_required

Sent when verification cannot proceed without manual intervention.

### 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                        |
| `contact`             | `ContactPayload`           | No       | Structured contact information                           |
| `metadata`            | `object`                   | No       | Additional context and troubleshooting data              |
| `accreditation`       | `AccreditationResult`      | No       | Accreditation data (education with `THIRD_PARTY_RECORD`) |
| `researchDecisionLog` | `ResearchDecisionLog`      | No       | Audit trail of research decisions and sources searched   |

### ActionRequiredReasonCode Enum

| Code                      | Description                                           | When Triggered                                                                                                                                                                                                  |
| ------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `THIRD_PARTY_RECORD`      | Requires third-party vendor                           | Research identified paywalled portal or vendor                                                                                                                                                                  |
| `INTERNATIONAL_EDUCATION` | Third-party detection at an international institution | EDUCATION search where research detected a third-party vendor at a postsecondary/international institution and accreditation checking was skipped for that reason; replaces `THIRD_PARTY_RECORD` in these cases |
| `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, manual review needed                                                                                                                                                          |
| `OTHER`                   | Catch-all                                             | Cases not matching other codes                                                                                                                                                                                  |

<Info>
  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](/guides/third-party-ban).
</Info>

***

### 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`  | Compensation          |
| `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)

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

```json theme={null}
{
  "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": {
      "reference": {
        "name": "Metro High School District",
        "date": "2018-05-25",
        "city": "Memphis",
        "state": "TN"
      },
      "matches": [
        {
          "campus": {
            "dapipId": "123456",
            "locationName": "Metro High School District",
            "city": "Memphis",
            "state": "TN",
            "url": "https://www.metrohsd.gov"
          },
          "accreditation": {
            "statusLabel": "Accredited",
            "isAccredited": true,
            "accreditor": "SACS",
            "reason": "Accredited by Southern Association of Colleges and Schools"
          }
        }
      ],
      "metadata": {
        "accreditationStatus": "accredited",
        "campusesConsidered": 1,
        "dataSource": "GCS verifications-api-dataset-2026 (accreditation CSVs)",
        "checkedOn": "2025-12-02"
      }
    }
  }
}
```

### Example: UPSTREAM\_ISSUE

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

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

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

```json theme={null}
{
  "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": "internal:EMPLOYER_CONTACT"
              }
            ],
            "title": "HR Manager",
            "department": "Human Resources",
            "confidence": 0.85,
            "location": "New York, NY",
            "usesThirdParty": false,
            "metadata": {
              "internalSourcesUsed": true,
              "parentOrgResearchUsed": false,
              "webSearchUsed": false,
              "totalSourcesChecked": 1
            }
          },
          {
            "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": "internal:THIRD_PARTY"
              }
            ],
            "confidence": 0.95,
            "location": "global",
            "usesThirdParty": true,
            "contactPreference": "The Work Number",
            "metadata": {
              "internalSourcesUsed": true,
              "parentOrgResearchUsed": false,
              "webSearchUsed": false,
              "totalSourcesChecked": 1
            }
          }
        ],
        "requiresHumanEscalation": false,
        "decisionLog": {
          "timestamp": "2025-12-02T10:00:00.000Z",
          "organizationName": "Acme Corporation",
          "location": "New York, NY",
          "decisions": [
            {
              "stage": "FINAL_RESULT",
              "decision": "PROCEED",
              "reasoning": "Research completed successfully with 2 contacts found",
              "confidence": 0.9,
              "timestamp": "2025-12-02T10:00:00.000Z"
            }
          ]
        }
      }
    }
  }
}
```

### Example: OTHER

```json theme={null}
{
  "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 (when `notificationType` is `CONTACT_PLAN`)        |
| `outboundAttempt`  | `OutboundAttempt`              | No       | Attempt details (when `notificationType` is `OUTBOUND_ATTEMPT`) |
| `inboundMetadata`  | `InboundMetadata`              | No       | Inbound details (when `notificationType` is `INBOUND_MESSAGE`)  |

### VerificationNotificationType Enum

| Value                     | Description                                                                                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTACT_PLAN`            | Research identified viable contacts                                                                                                                                                                                                    |
| `OUTBOUND_ATTEMPT`        | Outbound communication attempt made                                                                                                                                                                                                    |
| `INBOUND_MESSAGE`         | Inbound communication received                                                                                                                                                                                                         |
| `INBOUND_RECEIVED_DETAIL` | Fires for every inbound message (email, voice/fax transcription, or JSON/API submission) alongside `INBOUND_MESSAGE`, carrying the fuller message context — raw body, classification, and attachment processing status — in `metadata` |

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

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

**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": "..." }`) |

### 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`) |

***

### Example: CONTACT\_PLAN

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

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

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

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

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

***

## 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](/guides/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](/webhooks/integration).

Organization-level webhook defaults: [Webhook Integration — Organization-level configuration](/webhooks/integration#organization-level-configuration). SLA and escalation behavior: [SLA and escalation](/guides/sla-and-escalation).