AI Enrichment API

The AI Enrichment API uses a sophisticated multi-agent system to automatically enrich email lists with detailed company information, contact profiles, and custom data extraction. Perfect for sales prospecting, lead qualification, and B2B data enrichment.

Authentication

Authorization

string

required

Bearer token using your API key: Bearer YOUR_API_KEY

Request Body

data

array

required

Array of records to enrich. Each record must contain at least an email address.

Show data structure

data[].email

string

required

Email address to enrich (e.g., [email protected])

data[].additionalFields

object

Optional additional fields to include in output

fields

array

required

Array of field definitions for data extraction

Show field properties

fields[].name

string

required

Unique name for this field (e.g., company_name, industry)

fields[].prompt

string

required

AI prompt describing what to extract (max 500 chars)Example: “Extract the company’s industry sector”

fields[].type

string

default:"text"

Expected data type: text, number, boolean, or json

options

object

Configuration options for enrichment behavior

Show options properties

options.concurrency

number

default:"5"

Number of concurrent enrichments (1-20)Higher values = faster processing but higher cost

options.includeDiscovery

boolean

default:"true"

Extract domain from email (free, always recommended)

options.includeProfile

boolean

default:"true"

Scrape company website for profile data (1-3 credits per row)

options.timeout

number

default:"30000"

Maximum processing time per row in milliseconds (10000-120000)

options.skipInvalidEmails

boolean

default:"true"

Skip rows with invalid email formats

Response

success

boolean

Indicates if enrichment job was created successfully

data

object

Job information for tracking enrichment progress

Show data properties

data.jobId

string

Unique job identifier for tracking

data.status

string

Current job status: queued, processing, completed, failed

data.totalRows

number

Total number of rows to process

data.estimatedCredits

number

Estimated credit cost for completion

data.estimatedTime

number

Estimated completion time in seconds

Example: Basic Lead Enrichment

curl -X POST "https://api.whizo.ai/v1/ai-enrichment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "email": "[email protected]" },
      { "email": "[email protected]" }
    ],
    "fields": [
      {
        "name": "company_name",
        "prompt": "Extract the full company name",
        "type": "text"
      },
      {
        "name": "industry",
        "prompt": "Identify the company'\''s industry sector",
        "type": "text"
      },
      {
        "name": "employee_count",
        "prompt": "Estimate the number of employees",
        "type": "number"
      }
    ],
    "options": {
      "concurrency": 3,
      "includeDiscovery": true,
      "includeProfile": true
    }
  }'

{
  "success": true,
  "data": {
    "jobId": "enr_abc123xyz789",
    "status": "queued",
    "totalRows": 2,
    "estimatedCredits": 6,
    "estimatedTime": 45,
    "createdAt": "2025-01-06T10:30:00Z"
  }
}

Monitoring Job Progress

Get Job Status

curl "https://api.whizo.ai/v1/ai-enrichment/{jobId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "enr_abc123xyz789",
    "status": "processing",
    "totalRows": 100,
    "rowsProcessed": 45,
    "rowsSucceeded": 43,
    "rowsFailed": 2,
    "creditsUsed": 129,
    "progress": 45,
    "estimatedTimeRemaining": 120,
    "createdAt": "2025-01-06T10:30:00Z",
    "startedAt": "2025-01-06T10:30:05Z"
  }
}

Real-Time Progress with SSE

Stream real-time progress updates using Server-Sent Events (SSE):

const eventSource = new EventSource(
  `https://api.whizo.ai/v1/ai-enrichment/${jobId}/stream`,
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.progress}% - ${data.rowsProcessed}/${data.totalRows}`);

  if (data.status === 'completed') {
    eventSource.close();
    console.log('Enrichment completed!');
  }
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};

Downloading Results

Once the job status is completed, download enriched data:

curl "https://api.whizo.ai/v1/ai-enrichment/{jobId}/results?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o enriched-data.json

[
  {
    "email": "[email protected]",
    "domain": "acmecorp.com",
    "company_name": "Acme Corporation",
    "industry": "Manufacturing & Industrial Equipment",
    "employee_count": 5000,
    "enrichment_status": "success",
    "credits_used": 3,
    "processing_time_ms": 4523
  },
  {
    "email": "[email protected]",
    "domain": "techstartup.io",
    "company_name": "TechStartup Inc.",
    "industry": "Software & Technology",
    "employee_count": 25,
    "enrichment_status": "success",
    "credits_used": 3,
    "processing_time_ms": 3891
  }
]

Multi-Agent Enrichment System

The AI Enrichment API uses a sophisticated multi-agent architecture:

Discovery Agent (Free)

Extracts domain from email address
Validates email format
Performs DNS lookups
Cost: 0 credits

Profile Agent (1-3 credits)

Scrapes company website
Extracts structured company data
Analyzes website content
Cost: 1-3 credits per row (based on website complexity)

General Agent (configurable)

Processes custom field prompts
Applies AI extraction to company data
Returns structured responses based on field type
Cost: Included in Profile Agent cost

Credit Costs & Pricing

Component	Cost (Credits)	Notes
Discovery Agent	0	Always free
Profile Agent	1-3	Per successful row
Failed Enrichment	0	No charge for failed rows
Batch Processing	No extra fee	Same per-row cost

Estimated Costs:

100 rows with basic enrichment: ~150-300 credits
1000 rows with advanced fields: ~1500-3000 credits

Optimization Tips:

Set skipInvalidEmails: true to avoid processing bad data
Use lower concurrency for better accuracy vs. speed trade-off
Test with small batches before processing large datasets

Field Design Best Practices

Effective Prompt Writing

Good Prompts:

✅ “Extract the company’s primary industry sector”
✅ “Identify if the company is B2B or B2C focused”
✅ “Estimate annual revenue range in millions USD”
✅ “List the company’s main product categories”

Poor Prompts:

❌ “Tell me everything about the company” (too broad)
❌ “Get info” (vague)
❌ “Company” (unclear)

Field Type Selection

Type	Use Case	Example
`text`	Names, descriptions, addresses	Company name, industry
`number`	Counts, measurements, estimates	Employee count, revenue
`boolean`	Yes/no questions	Is B2B?, Has API?
`json`	Complex structured data	Product list, locations array

Error Handling

Status Code	Error Code	Description
400	`INVALID_EMAIL_FORMAT`	Email addresses don’t match required format
400	`MISSING_FIELDS`	Required fields array is empty
400	`INVALID_FIELD_TYPE`	Field type not supported
401	`UNAUTHORIZED`	Invalid or missing API key
402	`INSUFFICIENT_CREDITS`	Not enough credits for estimated job
429	`RATE_LIMIT_EXCEEDED`	Too many concurrent enrichment jobs
500	`ENRICHMENT_ERROR`	Internal enrichment processing error

{
  "success": false,
  "error": "INSUFFICIENT_CREDITS",
  "message": "Not enough credits. Required: 300, Available: 150",
  "data": {
    "required": 300,
    "available": 150,
    "shortfall": 150
  }
}

Rate Limits

Plan	Concurrent Jobs	Max Rows per Job	Rate Limit
Free	1	100	5 jobs/hour
Starter	3	500	20 jobs/hour
Pro	10	5000	100 jobs/hour
Enterprise	50	50000	Unlimited

Job Cancellation

Cancel a running enrichment job to stop processing and avoid further credits:

curl -X POST "https://api.whizo.ai/v1/ai-enrichment/{jobId}/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Note: Already processed rows will still be charged. In-progress rows may complete before cancellation.

Use Cases

Sales Lead Qualification

Enrich prospect lists with company data to prioritize high-value leads:

Extract company size and industry
Identify decision-maker roles
Assess technology stack
Estimate budget/revenue range

Account-Based Marketing (ABM)

Build comprehensive account profiles for targeted campaigns:

Company firmographics
Product/service offerings
Recent news and updates
Organizational structure

Investor Due Diligence

Research portfolio companies and investment opportunities:

Market positioning
Competitive landscape
Growth indicators
Technology adoption

Recruitment Intelligence

Enhance candidate profiles with employer information:

Company culture indicators
Industry trends
Career growth potential
Compensation benchmarks

Extract API - AI extraction for single pages
Jobs API - Monitor all job types
Billing API - Check credit balance

Support

Questions about AI Enrichment? Contact [email protected] or visit our documentation.

Core APIs

Job Management

User Management

Advanced Features

Authentication

Request Body

Response

Example: Basic Lead Enrichment

Monitoring Job Progress

Get Job Status

Real-Time Progress with SSE

Downloading Results

Multi-Agent Enrichment System

Discovery Agent (Free)

Profile Agent (1-3 credits)

General Agent (configurable)

Credit Costs & Pricing

Field Design Best Practices

Effective Prompt Writing

Field Type Selection

Error Handling

Rate Limits

Job Cancellation

Use Cases

Support

Core APIs

Job Management

User Management

Advanced Features

​Authentication

​Request Body

​Response

​Example: Basic Lead Enrichment

​Monitoring Job Progress

​Get Job Status

​Real-Time Progress with SSE

​Downloading Results

​Multi-Agent Enrichment System

​Discovery Agent (Free)

​Profile Agent (1-3 credits)

​General Agent (configurable)

​Credit Costs & Pricing

​Field Design Best Practices

​Effective Prompt Writing

​Field Type Selection

​Error Handling

​Rate Limits

​Job Cancellation

​Use Cases

​Related Endpoints

​Support

Authentication

Request Body

Response

Example: Basic Lead Enrichment

Monitoring Job Progress

Get Job Status

Real-Time Progress with SSE

Downloading Results

Multi-Agent Enrichment System

Discovery Agent (Free)

Profile Agent (1-3 credits)

General Agent (configurable)

Credit Costs & Pricing

Field Design Best Practices

Effective Prompt Writing

Field Type Selection

Error Handling

Rate Limits

Job Cancellation

Use Cases

Related Endpoints

Support