API Reference

Base URL:

https://dev.enrich.so

All endpoints require an API key via x-api-key header or Authorization: Bearer sk_*. See Authentication.

Response format

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "creditsUsed": 10,
    "creditsRemaining": 990
  }
}

Error (RFC 9457 Problem Details)

{
  "type": "https://dev.enrich.so/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Human-readable explanation",
  "instance": "/requests/req_abc123"
}

Email Validation

Validate single email

Checks if an email address is deliverable.

POST /api/v3/email-validation

Credits: 1

Request body:

Field	Type	Required	Description
`email`	string	Yes	Email address to validate

Response:

{
  "success": true,
  "data": {
    "email": "jane@example.com",
    "status": "valid",
    "subStatus": "",
    "freeEmail": false,
    "disposable": false,
    "catchAll": false
  },
  "meta": {
    "requestId": "req_abc123",
    "creditsUsed": 1,
    "creditsRemaining": 999
  }
}

Submit batch validation

Submit up to 500,000 emails for async validation. Credits are reserved upfront and settled when you fetch results.

POST /api/v3/email-validation/batch

Credits: 1 per email (reserved on submit, settled on results)

Request body:

Field	Type	Required	Description
`emails`	string[]	Yes	Array of emails (1–500,000)
`webhookUrl`	string	No	URL to notify when batch completes

Response:

{
  "success": true,
  "data": {
    "batchId": "batch_abc123",
    "status": "queued",
    "itemCount": 2
  },
  "meta": {
    "requestId": "req_def456",
    "creditsReserved": 2,
    "creditsPerItem": 1
  }
}

Get batch status

Poll for batch processing status. Free — no credits consumed.

GET /api/v3/email-validation/batch/:batchId

Response:

{
  "success": true,
  "data": {
    "batchId": "batch_abc123",
    "status": "processing",
    "totalItems": 2,
    "processedItems": 1,
    "progress": 50
  }
}

Get batch results

Retrieve results with pagination. Credits are settled on the first call when the batch reaches a terminal status (completed, failed).

GET /api/v3/email-validation/batch/:batchId/results

Query parameters:

Param	Type	Default	Description
`page`	number	1	Page number (1-based)
`limit`	number	100	Results per page (1–1000)

Response:

{
  "success": true,
  "data": {
    "batchId": "batch_abc123",
    "status": "completed",
    "totalItems": 2,
    "processedItems": 2,
    "results": [
      {
        "email": "a@example.com",
        "status": "valid"
      },
      {
        "email": "b@example.com",
        "status": "invalid"
      }
    ]
  },
  "meta": {
    "creditsUsed": 2,
    "creditsRemaining": 997
  }
}

Email Finder

Find email by name and domain

Find someone's professional email address from their name and company domain.

POST /api/v3/email-finder

Credits: 10

Request body:

Field	Type	Required	Description
`firstName`	string	Yes	Person's first name
`lastName`	string	Yes	Person's last name
`domain`	string	Yes	Company domain

Response:

{
  "success": true,
  "data": {
    "email": "jane.doe@example.com",
    "confidence": "high",
    "firstName": "Jane",
    "lastName": "Doe",
    "domain": "example.com"
  },
  "meta": {
    "requestId": "req_abc123",
    "creditsUsed": 10,
    "creditsRemaining": 990
  }
}

Submit batch email finder

Submit up to 500,000 leads for async email finding.

POST /api/v3/email-finder/batch

Credits: 10 per lead (reserved on submit, settled on results)

Request body:

Field	Type	Required	Description
`leads`	Lead[]	Yes	Array of leads (1–500,000)
`webhookUrl`	string	No	URL to notify when batch completes

Each Lead object:

Field	Type	Required
`firstName`	string	Yes
`lastName`	string	Yes
`domain`	string	Yes

Response:

{
  "success": true,
  "data": {
    "batchId": "batch_abc123",
    "status": "queued",
    "itemCount": 2
  },
  "meta": {
    "creditsReserved": 20,
    "creditsPerItem": 10
  }
}

Get batch status

GET /api/v3/email-finder/batch/:batchId

Same response format as Email Validation batch status.

Get batch results

GET /api/v3/email-finder/batch/:batchId/results

Query parameters: page (default 1), limit (default 100, max 1000)

Credits settled on first call when batch is complete — 10 credits per successfully found email.

Reverse Email Lookup

Look up professional profile by email

Retrieve professional profile information for a single email address. Results are cached for 7 days.

POST /api/v3/reverse-lookup/lookup

Credits: 10 (refunded if no profile found)

Request body:

Field	Type	Required	Description
`email`	string	Yes	Email address to look up

Response:

{
  "success": true,
  "data": {
    "found": true,
    "email": "jane@example.com",
    "linkedinUrl": "https://example.com/in/janedoe",
    "firstName": "Jane",
    "lastName": "Doe",
    "title": "VP of Engineering",
    "company": "Example Inc"
  },
  "meta": {
    "requestId": "req_abc123",
    "creditsUsed": 10,
    "creditsRemaining": 990
  }
}

If no profile is found, data.found is false and credits are refunded.

Submit bulk email lookup

Submit up to 100,000 emails for async professional profile lookup.

POST /api/v3/reverse-lookup/bulk-lookup

Credits: 10 per email (reserved on submit, settled on results)

Request body:

Field	Type	Required	Description
`emails`	string[]	Yes	Array of emails (1–100,000)
`webhookUrl`	string	No	URL to notify when batch completes

Response:

{
  "success": true,
  "data": {
    "batchId": "batch_abc123",
    "status": "queued",
    "itemCount": 2
  },
  "meta": {
    "creditsReserved": 20,
    "creditsPerItem": 10
  }
}

Get bulk lookup status

GET /api/v3/reverse-lookup/bulk-lookup/:batchId

Free — no credits consumed.

Get bulk lookup results

GET /api/v3/reverse-lookup/bulk-lookup/:batchId/results

Query parameters: page (default 1), limit (default 100, max 1000)

Credits settled on first call when batch reaches terminal status — 10 credits per processed email.

Phone Finder

Look up phone numbers

Retrieve phone numbers associated with an email address or profile URL.

GET /api/v3/reverse-lookup/phones

Credits: 500 (refunded if no phone found)

Query parameters:

Param	Type	Required	Description
`email`	string	No*	Email address to look up
`linkedin`	string	No*	Profile URL

*At least one of email or linkedin is required.

Response:

{
  "success": true,
  "data": {
    "found": true,
    "phones": [
      {
        "number": "+14155551234",
        "type": "mobile"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "creditsUsed": 500,
    "creditsRemaining": 500
  }
}

Submit bulk phone lookup

Submit up to 500,000 email addresses and/or profile URLs for async phone lookup.

POST /api/v3/reverse-lookup/phones/bulk

Credits: 500 per item (reserved on submit, settled on results)

Request body:

Field	Type	Required	Description
`emails`	string[]	No*	Email addresses (up to 500,000)
`linkedins`	string[]	No*	Profile URLs (up to 500,000)
`webhookUrl`	string	No	URL to notify when job completes

*Total of emails + linkedins must be between 1 and 500,000.

Response:

{
  "success": true,
  "data": {
    "batchId": "abc123def456abc123def456",
    "status": "queued",
    "itemCount": 2
  },
  "meta": {
    "creditsReserved": 1000,
    "creditsPerItem": 500
  }
}

Get bulk phone lookup status

GET /api/v3/reverse-lookup/phones/bulk/:jobId

The jobId is a 24-character hex string. Free — no credits consumed.

Response:

{
  "success": true,
  "data": {
    "batchId": "abc123def456abc123def456",
    "status": "processing",
    "totalItems": 2,
    "processedItems": 1,
    "progress": 50
  }
}

Get bulk phone lookup results

GET /api/v3/reverse-lookup/phones/bulk/:jobId/results

Query parameters: page (default 1), limit (default 100, max 1000)

Credits settled on first call when job reaches terminal status — 500 credits per item with results.

Wallet

Get balance

Check your organization's credit balance.

GET /api/v3/wallets/balance

Response:

{
  "success": true,
  "data": {
    "balance": 10000
  }
}

Get transactions

View paginated transaction history for your organization.

GET /api/v3/wallets/transactions

Query parameters:

Param	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page
`type`	string	—	Filter by transaction type

Error types

Status	Type	Description
400	`validation-error`	Invalid request body or parameters
401	`unauthorized`	Missing or invalid API key
402	`insufficient-credits`	Not enough credits for the operation
403	`forbidden`	Account suspended or org not found
404	`not-found`	Resource not found
429	`rate-limit-exceeded`	Too many requests
502	`upstream-failure`	Communication failure
503	`service-unavailable`	Service temporarily unavailable
504	`timeout`	Request timed out
500	`internal-error`	Unexpected server error

All error responses follow RFC 9457 Problem Details format with type, title, status, and detail fields.

Response format#

Success#

Error (RFC 9457 Problem Details)#

Email Validation#

Validate single email#

Submit batch validation#

Get batch status#

Get batch results#

Email Finder#

Find email by name and domain#

Submit batch email finder#

Get batch status#

Get batch results#

Reverse Email Lookup#

Look up professional profile by email#

Submit bulk email lookup#

Get bulk lookup status#

Get bulk lookup results#

Phone Finder#

Look up phone numbers#

Submit bulk phone lookup#

Get bulk phone lookup status#

Get bulk phone lookup results#

Wallet#

Get balance#

Get transactions#

Error types#

Response format

Success

Error (RFC 9457 Problem Details)

Email Validation

Validate single email

Submit batch validation

Get batch status

Get batch results

Email Finder

Find email by name and domain

Submit batch email finder

Get batch status

Get batch results

Reverse Email Lookup

Look up professional profile by email

Submit bulk email lookup

Get bulk lookup status

Get bulk lookup results

Phone Finder

Look up phone numbers

Submit bulk phone lookup

Get bulk phone lookup status

Get bulk phone lookup results

Wallet

Get balance

Get transactions

Error types