Find Email

Introduction

The Find Email endpoint discovers professional email addresses for a person. You can identify the person with a LinkedIn profile URL, or with their full name and company domain. Processing is asynchronous: the API acknowledges the request with a webhookId, then sends the result to your webhook callback.

Use this endpoint when you need an email address for outreach or CRM enrichment. Configure a workspace webhook URL in Settings > Webhooks, or provide webhookUrl in the request.

Authorization

apikey string required

Your API key from the developer dashboard. Pass it in the Authorization: Bearer YOUR_API_KEY header.

Request body

Choose one lookup strategy. Use either a LinkedIn profile URL, or a full name with a company domain. The split firstName + lastName form is also accepted.

url string conditional

Public LinkedIn profile URL, such as https://www.linkedin.com/in/janedoe. Use this for the URL strategy.

fullName string conditional

Person’s full name, such as Jane Doe. Use this with companyDomain.

firstName string conditional

Person’s first name. Use this with lastName and companyDomain instead of fullName.

lastName string conditional

Person’s last name. Use this with firstName and companyDomain instead of fullName.

companyDomain string conditional

Company domain, such as acme.com. Required for the name-based strategies.

webhookUrl string

HTTPS URL that receives the callback. Omit this only when a workspace webhook URL is configured.

Note

The request must contain url, or fullName + companyDomain, or firstName + lastName + companyDomain. The endpoint returns an acknowledgement immediately and delivers the email array later through the webhook callback.

Response structure

The initial response confirms that the asynchronous job was created. Save data.webhookId and use it to correlate the callback with the request that created it.

success boolean

true when the job was created successfully

dataobject

Show child attributesHide child attributes

status string

Job status, always "created" in the initial response

webhookId string

Unique job identifier. Store it to correlate the incoming webhook callback.

error null

null when the job is created

quotasobject

Show child attributesHide child attributes

creditsConsumed number

Credits reserved for the lookup

metadataobject

Show child attributesHide child attributes

requestId string

Unique identifier for this request

executionTimeMs number

Time spent creating the job in milliseconds

Webhook callback

When the lookup completes, ReverseContact sends a JSON POST request to your webhookUrl. The callback is not wrapped in the V2 response envelope. It always includes the webhookId from the initial acknowledgement and a data value.

Successful callback

When an email is found, data is an array of email objects:

{
  "webhookId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8091a2b3c4",
  "data": [
    {
      "value": "[email protected]",
      "type": "professional"
    }
  ]
}

value string

The discovered email address

type string

Email category, typically professional

Error callback

When the lookup cannot return an email, data contains an errorCode instead of an email array:

{
  "webhookId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8091a2b3c4",
  "data": {
    "errorCode": "email-not-found"
  }
}

The callback error codes are:

Code	Billed	Description
`email-not-found`	No	No email address was discovered for the person
`person-not-found`	No	No matching person was found for the supplied identifiers
`invalid-request`	No	The lookup input is malformed or does not match an accepted form
`fetch-data-error`	No	The lookup failed while fetching data; safe to retry
`webhook-url-invalid`	Yes	The callback URL returned a 4xx response
`webhook-url-errored`	Yes	The callback URL returned a 5xx response or a network error
`webhook-url-timeout`	Yes	The callback URL did not respond in time
`webhook-url-unreachable`	Yes	The callback URL could not be reached

Note

The lookup costs 3 credits only when an email is found. A lookup that returns email-not-found, person-not-found, invalid-request, or fetch-data-error costs 0 credits. A delivery failure remains billed when the email was successfully found.