Verification Pipeline — Technical Documentation

Last updated: February 2026

---

Table of Contents

1. Overview
2. Architecture
3. Repository Map
4. Core Flows
5. Entities & Data Model
6. API Endpoints
7. Services & Business Logic
8. Configuration
9. Integration Points

---

1. Overview

The Verification Pipeline handles bulk email verification — batch processing of prospect email addresses to check deliverability. Jobs are managed via Hangfire background processing, with results aggregated and exposed through the Data API. The system lives primarily in sopromasterdata (backend API + Hangfire services) and data-admin (frontend UI for job management and verification search).

---

2. Architecture

---

3. Repository Map

Repository	Layer	Key Files
sopromasterdata	Controller	API/SoProMasterDBAPI/Controllers/VerificationController.cs
sopromasterdata	Service	VerificationServices/VerificationService.cs
sopromasterdata	Hangfire	HangfireServices/VerificationHangfireService.cs
sopromasterdata	Repository	Repository/Verification/VerificationRepository.cs
sopromasterdata	Entities	VerificationEntities/VerificationJob.cs, VerificationResult.cs
data-admin	Pages	src/pages/verifications/
data-admin	Search Page	src/pages/verification-search/
data-admin	API Hooks	src/api/verifications.queries.ts
data-admin	Types	src/types/verifications/

---

4. Core Flows

4.1 Create & Process Verification Job

4.2 Verification Check Pipeline

4.3 Verification Search (Person Lookup)

---

5. Entities & Data Model

VerificationJob

Column	Type	Description
Id	int (PK)	Job identifier
Name	nvarchar(255)	Job description
Status	int (enum)	Pending=0, Processing=1, Complete=2, Failed=3
TotalCount	int	Total emails to verify
ProcessedCount	int	Emails processed so far
ValidCount	int	Valid emails found
InvalidCount	int	Invalid emails found
RiskyCount	int	Risky (catch-all) emails
UnknownCount	int	Unknown status emails
CreatedAt	datetime	Job creation timestamp
StartedAt	datetime?	Processing start time
CompletedAt	datetime?	Processing end time
CreatedBy	nvarchar(100)	User who created the job

VerificationResult

Column	Type	Description
Id	long (PK)	Result identifier
JobId	int (FK)	Parent verification job
Email	nvarchar(255)	Email address verified
ProspectId	long? (FK)	Linked prospect
Status	int (enum)	Valid=0, Invalid=1, Risky=2, Unknown=3
Reason	nvarchar(500)	Why the email was given this status
IsCatchAll	bit	Whether the domain is catch-all
VerifiedAt	datetime	When verification was performed

Status Enums

public enum VerificationJobStatus
{
    Pending = 0,
    Processing = 1,
    Complete = 2,
    Failed = 3
}

public enum VerificationResultStatus
{
    Valid = 0,
    Invalid = 1,
    Risky = 2,
    Unknown = 3
}

---

6. API Endpoints

Data API (/api/Verifications)

Method	Endpoint	Description
GET	/api/Verifications/GetJobs	List verification jobs with pagination
GET	/api/Verifications/GetJobById/{id}	Get job details with result summary
GET	/api/Verifications/GetJobResults/{id}	Get individual results for a job
GET	/api/Verifications/Person	Search verification history by email
POST	/api/Verifications/CreateJob	Create a new verification job
POST	/api/Verifications/RetryJob/{id}	Retry a failed job

Frontend API Hooks

// src/api/verifications.queries.ts
useGetVerificationJobs(page, pageSize);
useGetVerificationJobById(id);
useGetVerificationResults(jobId, page, pageSize);
useGetVerificationsForPerson(email);
useCreateVerificationJob();

---

7. Services & Business Logic

VerificationService

Location: VerificationServices/VerificationService.cs
Interface: IVerificationService
DI: AddScoped<IVerificationService, VerificationService>() in ApiServiceExtensions.cs

Method	Description
CreateJobAsync()	Creates job + items, enqueues Hangfire job
GetJobByIdAsync()	Returns job with aggregated statistics
GetJobResultsAsync()	Paginated results for a job
GetVerificationsForPersonAsync()	Verification history for an email

VerificationHangfireService

Location: HangfireServices/VerificationHangfireService.cs
Interface: IVerificationHangfireService
DI: AddTransient<IVerificationHangfireService, VerificationHangfireService>()

Method	Description
RunVerificationJobAsync()	Processes all emails in a job through the verification pipeline
VerifyBatchAsync()	Verifies a batch of emails (format → DNS → MX → SMTP)
UpdateProgressAsync()	Updates job progress counters
AggregateResultsAsync()	Final statistics calculation after job completes

VerificationRepository

Location: Repository/Verification/VerificationRepository.cs
Interface: IVerificationRepository

Method	Description
GetJobsPagedAsync()	Paginated job listing
GetResultsByJobAsync()	Results for a specific job
GetHistoryByEmailAsync()	All verifications for an email address
InsertResultsBatchAsync()	Bulk insert verification results

---

8. Configuration

DI Registration

DataApi: API/SoProMasterDBAPI/Extensions/ApiServiceExtensions.cs

services.AddScoped<IVerificationService, VerificationService>();
services.AddScoped<IVerificationRepository, VerificationRepository>();
services.AddTransient<IVerificationHangfireService, VerificationHangfireService>();

Hangfire Configuration

Verification jobs use Hangfire with [AutomaticRetry] for resilience:

[AutomaticRetry(Attempts = 3)]
public async Task RunVerificationJobAsync(int jobId) { ... }

Frontend Configuration

Endpoints: src/api/endpoints.ts

verifications: {
    getVerificationsForPerson: "/verifications/person",
    getJobs: "/verifications/jobs",
    // ...
}

---

9. Integration Points

Upstream (data flows in)

Source	Data	Mechanism
Audience Management	Prospect emails to verify	Job creation via API
Email Finding	Newly found emails to verify	Trigger from email finding pipeline
Data Admin UI	Manual job creation	POST to API endpoint

Downstream (data flows out)

Target	Data	Mechanism
Prospect Records	Verification status updated	Database update
Audience Statistics	Valid/invalid counts affect stats	Statistics recalculation
Email Sending	Only verified emails are used for delivery	Status check before send
Data Admin UI	Job status, results, search results	REST API → React Query

Cross-Feature Dependencies

Feature	Relationship
Email Finding	Found emails are verified before use
Email Sending	Only verified-valid emails are delivered
Audience Management	Verification status affects audience statistics
Campaign Management	Campaigns may trigger bulk re-verification