Single lookup

API referenceEmail Finder

From the Email Finder API reference. Requests use the base URL https://app.warmerly.com/api/v1 and an API key, see Authentication.

text

POST /email-finder/lookup

Submit one lookup. Provide at least one of domain, website, or name, add person to narrow the search to a specific individual at that domain/company.

Field	Type	Description
`domain`	string	Company domain, e.g. `"acme.com"`.
`website`	string	Full website URL; the domain is extracted from it.
`name`	string	Business name, used when no `domain` or `website` is given. If `domain` is also sent, `domain` is used.
`location`	string	Optional location hint to disambiguate a business name.
`person.firstName`	string	Optional first name to target a specific person.
`person.lastName`	string	Optional last name to target a specific person.

person is used with a business name lookup. If none of domain, website or name gives a usable value the request returns 400 bad_request (provide a valid domain, website, or business name). If you are out of lookup quota it returns 402 quota_exhausted (see Quota).

bash

curl https://app.warmerly.com/api/v1/email-finder/lookup \
  -X POST \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Project-Id: 8f14e45f-ceea-4c6a-8c8d-6b1a5b5c9c1a" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com",
    "person": { "firstName": "Jane", "lastName": "Doe" }
  }'

If the answer for that domain is already cached, the lookup completes synchronously and returns 200 with the result inline (result is null if the cache holds no email for the domain):

json

{
  "status": "done",
  "jobId": "3f9a2e2a-1c4b-4a2e-9b1e-2f6c8a7d5e10",
  "job": {
    "id": "3f9a2e2a-1c4b-4a2e-9b1e-2f6c8a7d5e10",
    "status": "done",
    "confidence": 92,
    "error": null,
    "createdAt": "2026-07-02T09:14:03.000Z",
    "completedAt": "2026-07-02T09:14:03.000Z"
  },
  "result": {
    "email": "jane.doe@acme.com",
    "confidence": 92,
    "verifyStatus": "verified",
    "source": "pattern_guess",
    "isCatchAll": false,
    "mxHost": "aspmx.l.google.com",
    "evidenceUrl": "https://acme.com/team",
    "providerName": "Google Workspace"
  }
}

Otherwise it enqueues a job and returns 202 with a pollUrl:

json

{
  "status": "pending",
  "jobId": "3f9a2e2a-1c4b-4a2e-9b1e-2f6c8a7d5e10",
  "pollUrl": "https://app.warmerly.com/api/v1/email-finder/jobs/3f9a2e2a-1c4b-4a2e-9b1e-2f6c8a7d5e10"
}

Poll the job (see below) until status is "done" or "failed".

Was this page helpful?

Single lookup

More from Email Finder