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

{
  "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)

{
  "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)

{
  "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)

{
  "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)

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

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.

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)

{
  "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": {
      "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

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

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

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

{
  "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"
    }
  }
}

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 Integration

​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

​ResearchDecisionLog Object

​ResearchDecision Object

​Research Stages

​Example: Research Decision Log

​Understanding Provided vs Verified Fields

​EmploymentVerification Object

​Provided Fields (from applicant/requester)

​Verified Fields (from verification)

​Example: Employment Verification (Email)

​Example: Employment Verification (Voice)

​EducationVerification Object

​Provided Fields

​Verified Fields

​Example: Education Verification (Fax)

​Example: Education Verification (No Record)

​AccreditationResult Object

​AccreditationReference Object

​AccreditationMatch Object

​CampusSummary Object

​AccreditationEvaluation Object

​AccreditationMetadata Object

​AccreditationStatus Enum

​Event: verification.action_required

​Data Fields

​ActionRequiredReasonCode Enum

​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

​Example: OTHER

​Event: verification.notification

​Data Fields

​VerificationNotificationType Enum

​Classification Object

​ContactPlanEntry Object

​OutboundAttempt Object

​InboundMetadata Object

​Example: CONTACT_PLAN

​Example: OUTBOUND_ATTEMPT

​Example: INBOUND_MESSAGE (Email)

​Example: INBOUND_MESSAGE (Voice)

​Example: INBOUND_MESSAGE (Urgent)

​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

ResearchDecisionLog Object

ResearchDecision Object

Research Stages

Example: Research Decision Log

Understanding Provided vs Verified Fields

EmploymentVerification Object

Provided Fields (from applicant/requester)

Verified Fields (from verification)

Example: Employment Verification (Email)

Example: Employment Verification (Voice)

EducationVerification Object

Provided Fields

Verified Fields

Example: Education Verification (Fax)

Example: Education Verification (No Record)

AccreditationResult Object

AccreditationReference Object

AccreditationMatch Object

CampusSummary Object

AccreditationEvaluation Object

AccreditationMetadata Object

AccreditationStatus Enum

Event: verification.action_required

Data Fields

ActionRequiredReasonCode Enum

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

Example: OTHER

Event: verification.notification

Data Fields

VerificationNotificationType Enum

Classification Object

ContactPlanEntry Object

OutboundAttempt Object

InboundMetadata Object

Example: CONTACT_PLAN

Example: OUTBOUND_ATTEMPT

Example: INBOUND_MESSAGE (Email)

Example: INBOUND_MESSAGE (Voice)

Example: INBOUND_MESSAGE (Urgent)

Third-Party Vendor Reference

Employment Vendors

Education Vendors

Delivery, retries, and testing