Email Find API

Find a person’s work email address from their first name, last name, and company domain. DiscoLike enumerates candidate patterns for the domain and SMTP-verifies them, returning the proven address plus the pattern it matched.

Jobs run asynchronously: submit returns immediately with a job or batch id, then poll for results. Submit one person per call, or up to 500 per batch.

Only proven addresses (status found) are billed, as records at your plan’s per-1K rate, deduplicated per account for 90 days. Catch-all results, pattern guesses, and failed lookups are free.

POST https://api.discolike.com/v1/email/find
POST https://api.discolike.com/v1/email/find/batch
GET  https://api.discolike.com/v1/email/jobs/{job_id}
GET  https://api.discolike.com/v1/email/batch/{batch_id}/results

Parameters

Single find (POST /email/find):

Parameter	Type	Description
first_name	String	First name of the person (required)
last_name	String	Last name of the person (required)
domain	String	Target email domain, e.g. acmecorp.com (required)
known_pattern	String	Known email local-part pattern for this domain (optional)

Batch find (POST /email/find/batch):

Parameter	Type	Description
requests	Array	List of single-find objects as above (required, 1-500 items)

Examples

Request

curl -X POST "https://api.discolike.com/v1/email/find/batch" \
  -H "x-discolike-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"first_name": "Jane", "last_name": "Doe", "domain": "acmecorp.com"},
      {"first_name": "John", "last_name": "Smith", "domain": "techstartup.io"}
    ]
  }'

Initial Response

Single find returns a job id; batch find returns a batch id plus the job ids it created:

{
  "batch_id": "7f6f0a4e-52f7-4f3e-9c2d-0b8d3f1c9a11",
  "job_ids": ["e362cb75-35e2-4006-a239-3d87a7472872", "b91d2c40-8f1e-47f5-a6c3-2d7e9c0f4b22"],
  "total": 2
}

Poll Results

curl "https://api.discolike.com/v1/email/batch/{batch_id}/results" \
  -H "x-discolike-key: API_KEY"

Keep polling until completed + failed equals total. Single jobs are polled at /email/jobs/{job_id} and carry the same per-job shape as the batch results items.

Final Response

{
  "batch_id": "7f6f0a4e-52f7-4f3e-9c2d-0b8d3f1c9a11",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "results": [
    {
      "job_id": "e362cb75-35e2-4006-a239-3d87a7472872",
      "status": "completed",
      "kind": "find",
      "result": {
        "first_name": "Jane",
        "last_name": "Doe",
        "domain": "acmecorp.com",
        "status": "found",
        "result": {
          "email": "jane.doe@acmecorp.com",
          "pattern": "first.last",
          "tier": 1,
          "smtp_code": 250,
          "valid": true
        },
        "is_catch_all": false,
        "provider": "google",
        "attempts": 3,
        "duration_ms": 2140
      }
    },
    {
      "job_id": "b91d2c40-8f1e-47f5-a6c3-2d7e9c0f4b22",
      "status": "completed",
      "kind": "find",
      "result": {
        "first_name": "John",
        "last_name": "Smith",
        "domain": "techstartup.io",
        "status": "catch_all",
        "result": null,
        "is_catch_all": true,
        "provider": null,
        "attempts": 5,
        "duration_ms": 4890
      }
    }
  ]
}

Response Fields

Each job entry carries job_id, its lifecycle status (queued, processing, completed, failed), and kind, either find or verify, identifying which result shape the job produces. kind is present on newer API versions; treat it as optional.

Per-job result object:

Field	Type	Description
status	String	Enumeration outcome: found, not_found, catch_all, catch_all_pattern, undeliverable, error, timeout, greylisted, rate_limited
result	Object	Matched address details when found: email, pattern, tier, smtp_code, valid. null otherwise
is_catch_all	Boolean	Whether the domain accepts mail for any address, making per-address verification inconclusive
provider	String	Detected mail provider for the domain, when known
attempts	Integer	SMTP verification attempts made
duration_ms	Integer	Processing time for the job

Only jobs whose status is found are billed. A catch_all or catch_all_pattern outcome means the address could not be proven; any pattern returned there is a guess and is not billed.

The Python SDK exposes this as client.email.find(...) and client.email.find_batch(...) - see the Python SDK reference.