> ## Documentation Index
> Fetch the complete documentation index at: https://docs.companyenrich.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse Email Lookup API

> Turn a work email address into the person behind it: name, job title, seniority, LinkedIn profile, work history, and employer. Covers how the match works, the request, expansions, pricing, and limits.

The Reverse Email Lookup API takes a work email address and returns the person behind it as a full [person record](https://docs.companyenrich.com/docs/person-schema.md): name, current position, seniority, department, LinkedIn URL, and work history. Send the address to [`POST /v2/people/enrich`](https://docs.companyenrich.com/api-reference/v2/post-people-enrich).

A lookup costs 5 credits when a person is returned, and nothing when there is no match.

> [card] [Examples](https://docs.companyenrich.com/docs/reverse-email-lookup-api-examples.md)
>
> Lookups in cURL, four SDKs, and the CLI.

> [card] [Person schema](https://docs.companyenrich.com/docs/person-schema.md)
>
> Every field in the record you get back.

## Look up an email

This request finds the person behind an email address. The address shown is a placeholder on a reserved domain, so replace it with a real work email address. You need an API key, which you can create at [app.companyenrich.com/access-keys](https://app.companyenrich.com/access-keys).

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/people/enrich \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme-analytics.example"
  }'
```

```javascript JavaScript theme={null}
import { CompanyEnrich } from '@companyenrich/sdk';

const client = new CompanyEnrich(); // reads COMPANYENRICH_API_KEY

const person = await client.people.enrich({
  email: 'jane.doe@acme-analytics.example',
});

console.log(person.name, person.position);
console.log(person.socials.linkedinUrl);
```

```python Python theme={null}
from companyenrich import CompanyEnrich

client = CompanyEnrich()  # reads COMPANYENRICH_API_KEY

person = client.people.enrich("jane.doe@acme-analytics.example")

print(person.get("name"), person.get("position"))
print(person["socials"].get("linkedinUrl"))
```

```ruby Ruby theme={null}
require "companyenrich"

client = CompanyEnrich::Client.new # reads COMPANYENRICH_API_KEY

person = client.people.enrich("jane.doe@acme-analytics.example")

puts person["name"], person["position"]
puts person.dig("socials", "linkedinUrl")
```

```php PHP theme={null}
<?php

require 'vendor/autoload.php';

use CompanyEnrich\Client;

$client = new Client(); // reads COMPANYENRICH_API_KEY

$person = $client->people->enrich('jane.doe@acme-analytics.example');

echo $person['name'] ?? '', ' ', $person['position'] ?? '', PHP_EOL;
echo $person['socials']['linkedinUrl'] ?? '', PHP_EOL;
```

```bash CLI theme={null}
companyenrich people enrich jane.doe@acme-analytics.example
```

The response is one person record. This example is shortened and shows a fictional person. See the [person schema](https://docs.companyenrich.com/docs/person-schema.md) for every field.

```json theme={null}
{
  "id": 9000000000001,
  "name": "Jane Doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "position": "VP of Sales",
  "seniority": "vp",
  "department": "sales",
  "location": {
    "country": { "code": "US", "name": "United States" }
  },
  "socials": {
    "linkedinUrl": "https://www.linkedin.com/in/janedoe-example"
  },
  "experiences": [
    {
      "startDate": "2021-03-01",
      "isCurrent": true,
      "isMatched": true,
      "position": "VP of Sales",
      "company": {
        "id": "3f2b8c1e-6a4d-4f7a-9b21-0c5d8e7f1a23",
        "name": "Acme Analytics",
        "domain": "acme-analytics.example"
      }
    }
  ]
}
```

## How the match works

A lookup has two steps:

1. The API resolves the company from the domain of the email address.
2. It matches a person at that company using common email address patterns, such as `first.last` or `flast`.

The response is the best match. The job at the email's company is marked with `isMatched` set to `true` in `experiences`, so you can tell which employer the address belongs to.

Because the lookup starts from the company behind the domain, it is built for work email addresses.

## Request fields

| Field | Value | Description |
| - | - | - |
| `email` | string, required | The email address to look up. Up to 320 characters. |
| `expand` | array of strings | Paid data to add to the person: `education`, `company`, or both. |

## Add the employer's profile or education

| Expansion | Adds | Extra credits |
| - | - | - |
| `company` | The standard company profile for each employer in `experiences`, in place of the short summary. | 1 per unique company expanded |
| `education` | The person's education history: schools, degrees, and years. | 1 |

The `company` expansion covers every employer in the person's work history, current and past, so it can add several credits to one lookup. A lookup can expand at most 500 unique companies.

Without the expansion, each experience still names the employer with a short summary: `id`, `name`, `domain`, `logoUrl`, and `industry`.

## When there is no match

The API returns `404` when no person matches the email address. A `404` costs nothing.

The SDKs raise a not-found error for this response. See [Handle an email with no match](https://docs.companyenrich.com/docs/reverse-email-lookup-api-examples.md#handle-an-email-with-no-match).

## Look up many emails

The lookup takes one email address per request. To process a list, send one request per address, and count on some of them returning `404`. The CLI accepts several addresses at once, or a file with one address per line.

See [Look up a list of emails](https://docs.companyenrich.com/docs/reverse-email-lookup-api-examples.md#look-up-a-list-of-emails).

## What a lookup costs

* 5 credits when a person is returned.
* 1 more for `education`, and 1 for each unique company expanded with `company`.
* Nothing when no person matches.

See [Credits](https://docs.companyenrich.com/docs/credits.md) for every price.

## Related lookups

| You have | You want | Use |
| - | - | - |
| An email address | The person behind it | This API |
| A person from a search | Their work email address | [`GET /v2/people/{personId}/email`](https://docs.companyenrich.com/api-reference/v2/get-people-personid-email) |
| A domain | The company | [Company Enrichment API](https://docs.companyenrich.com/docs/company-enrichment-api.md) |
| A role, employer, or description | The people who match | [People Search API](https://docs.companyenrich.com/docs/people-search-api.md) |

## Limits

| Limit | Value |
| - | - |
| Email addresses per request | 1 |
| Email address length | 320 characters |
| Companies expanded with `company` | 500 unique companies |

## Coming from the V1 lookup endpoint

| | V1 | V2 |
| - | - | - |
| Endpoint | [`POST /people/lookup`](https://docs.companyenrich.com/api-reference/v1/post-people-lookup) | `POST /v2/people/enrich` |
| Email | `email` in the request body | `email` in the request body |
| Expansions | `expand=education` in the query string | `expand` in the request body, with `education`, `company`, or both |
| Field names | snake\_case, such as `first_name` | camelCase, such as `firstName` |
| Price | 5 credits per successful call | 5 credits when a person is returned |

## Common questions

### Am I charged when no person is found?

No. A lookup with no match returns `404` and costs nothing.

### Can I get the company without the person?

If you only need the company, enrich the email's domain with the [Company Enrichment API](https://docs.companyenrich.com/docs/company-enrichment-api.md), which costs 1 credit. To get the person and the full company profile together, add the `company` expansion to the lookup.

### How do I know which employer the email belongs to?

Find the entry in `experiences` where `isMatched` is `true`. That is the job at the company behind the email's domain.

### How sure is the match?

The API returns the best match for the address at that company, based on common email address patterns. Check the name and the matched job against what you already know before you rely on it.

### Can I look up several emails in one request?

No. Send one request per email address. The CLI accepts a list and sends the requests for you.

### Can I go the other way, from a person to their email?

Yes. Use the work email lookup, [`GET /v2/people/{personId}/email`](https://docs.companyenrich.com/api-reference/v2/get-people-personid-email). See [Get a work email for a person you found](https://docs.companyenrich.com/docs/people-search-api-examples.md#get-a-work-email-for-a-person-you-found).

## Related pages

> [card] [Reverse Email Lookup API examples](https://docs.companyenrich.com/docs/reverse-email-lookup-api-examples.md)
>
> Ready-to-run lookups.

> [card] [Person schema](https://docs.companyenrich.com/docs/person-schema.md)
>
> Every field in a person record.

> [card] [People Search API](https://docs.companyenrich.com/docs/people-search-api.md)
>
> Find people by role, employer, or description.

> [card] [API reference](https://docs.companyenrich.com/api-reference/v2/post-people-enrich.md)
>
> The full request and response specification, with a playground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.