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

> ## Agent Instructions
> Forager is a REST API for B2B people, company and job post data: contact lookups (phone numbers, personal emails, work emails), person, company and job post search, and bulk data feeds.
> Server: https://api-v2.forager.ai. Send the API key in the X-API-KEY header. Most paths include {account_id}. Read FORAGER_API_KEY and FORAGER_ACCOUNT_ID from the environment; never put the key in client-side code, logs or prompts.
> To add Forager to a project, follow https://www.forager.ai/docs/guides/agent-quickstart.md. To pick an endpoint, read https://www.forager.ai/docs/guides/choose-an-endpoint.md. For end-to-end builds, see https://www.forager.ai/docs/recipes/overview.md.
> Most requests spend credits. Do not guess costs; use https://www.forager.ai/docs/api-overview/credit-pricing.md and ask the user before spending credits.
> Use only endpoints and fields defined in https://www.forager.ai/docs/openapi.yaml. Forager has no MCP server for the API yet; the /mcp endpoint on this site searches the documentation only.

# CRM data enrichment from an email

> Find the person behind an email with reverse lookup, then add their personal email and phone number to the CRM record.

```text Recipe prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Implement this recipe in my project: https://www.forager.ai/docs/recipes/crm-enrich-from-email.md

Build a function that takes a contact's personal email from our CRM (the Forager reverse lookup by email is documented for personal email addresses, so skip work emails), calls the Forager reverse lookup by email to get the person, then calls the personal email and phone number lookups with the returned person id. Write the results back to the contact record. Handle no match, empty contact lists, a 403 from a bad key, and a 429 with backoff, and skip contacts that were already enriched. Keep the API key server-side in FORAGER_API_KEY with FORAGER_ACCOUNT_ID. Add tests that stub the HTTP calls.
```

![CRM data enrichment flow: reverse email lookup finds the person behind an email, then adds contact details](https://mintcdn.com/forager/OnhSHNo_LBQ7yKjR/images/recipes/crm-data-enrichment-reverse-email-lookup.svg?fit=max\&auto=format\&n=OnhSHNo_LBQ7yKjR\&q=85\&s=276de6eb8fc1175577c969fa362e0c1f)

## What you'll build

A job that fills gaps on a CRM contact. It starts with the contact's personal email address (the reverse lookup is documented for personal emails, not work emails), resolves it to a Forager person, and then asks for a personal email and a phone number for that person.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  A[CRM contact email] --> B[Reverse lookup by email]
  B --> C[person id]
  C --> D[Personal email lookup]
  C --> E[Phone lookup]
  D --> F[Update CRM]
  E --> F
```

## Steps

**1. Resolve the email to a person**

Send a `POST` to [Person detail lookup by email](https://www.forager.ai/docs/openapi/people/datastorage_person_detail_reverse_lookup_by_email_create.md) with `email`. The response is a person record. Keep its `id`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_detail_reverse_lookup/by_email/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@gmail.com"}'
```

```python Python (requests) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os, requests

BASE = f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage"
HEADERS = {"X-API-KEY": os.environ["FORAGER_API_KEY"]}

r = requests.post(
    f"{BASE}/person_detail_reverse_lookup/by_email/",
    headers=HEADERS,
    json={"email": "jane.doe@gmail.com"},
    timeout=30,
)
r.raise_for_status()
person_id = r.json()["id"]
```

```javascript JavaScript (fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
const BASE = `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage`;
const headers = {
  "X-API-KEY": process.env.FORAGER_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(`${BASE}/person_detail_reverse_lookup/by_email/`, {
  method: "POST",
  headers,
  body: JSON.stringify({ email: "jane.doe@gmail.com" }),
});
if (!res.ok) throw new Error(`Forager ${res.status}`);
const personId = (await res.json()).id;
```

**Example response (illustrative values, trimmed)**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "id": 123, "full_name": "Jane Doe", "first_name": "Jane", "headline": "Example title at Example Corp" }
```

**2. Look up the personal email and phone number**

Call [Personal emails lookup](https://www.forager.ai/docs/openapi/personal-emails/datastorage_person_contacts_lookup_personal_emails_create.md) and [Phone numbers lookup](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md) with `person_id`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
for path in personal_emails phone_numbers; do
  curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_contacts_lookup/$path/" \
    -H "X-API-KEY: $FORAGER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"person_id": 123}'
done
```

```python Python (requests) theme={"theme":{"light":"github-light","dark":"github-dark"}}
contacts = {}
for path in ("personal_emails", "phone_numbers"):
    r = requests.post(
        f"{BASE}/person_contacts_lookup/{path}/",
        headers=HEADERS,
        json={"person_id": person_id},
        timeout=30,
    )
    r.raise_for_status()
    contacts[path] = r.json() if r.content else []
```

```javascript JavaScript (fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
const contacts = {};
for (const path of ["personal_emails", "phone_numbers"]) {
  const r = await fetch(`${BASE}/person_contacts_lookup/${path}/`, {
    method: "POST",
    headers,
    body: JSON.stringify({ person_id: personId }),
  });
  if (!r.ok) throw new Error(`Forager ${r.status}`);
  const text = await r.text();
  contacts[path] = text ? JSON.parse(text) : [];
}
```

Personal email results are objects with `email`, `email_type` and `validation_status` (`valid`, `risky`, `invalid` or `unknown`). Phone results have `phone_number`.

**3. Write back to the CRM**

Store only addresses you want to keep. For example, skip a personal email whose `validation_status` is `invalid`. Save the Forager `id` on the contact so you never resolve the same email twice.

## Handle the edge cases

* **Not found.** If the reverse lookup finds no person, stop and mark the contact "no match".
* **Empty contact lists.** The personal emails lookup returns `200` with an empty body when nothing is left after filtering, which is why the code checks for an empty body. It returns only free webmail addresses, not company domains.
* **Matching.** The reverse lookup's `email` is documented as the person's personal email address.
* **403.** The key is missing or invalid. Fix the credentials; do not retry.
* **429.** Back off and retry. See [errors and rate limits](https://www.forager.ai/docs/errors-and-rate-limits.md).
* **Credits.** Reverse lookup by email costs 5 credits. Personal email lookup costs 5, and is not charged when no address is returned. Phone number lookup costs 15 credits per lookup. See [credit pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md).

## Related

> [card] [Enrich a contact](https://www.forager.ai/docs/guides/enrich-a-contact.md)
>
> Reverse lookups and the full person record.

> [card] [Find phone numbers](https://www.forager.ai/docs/guides/find-phone-numbers.md)
>
> Phone lookup details.

> [card] [Personal emails lookup](https://www.forager.ai/docs/openapi/personal-emails/datastorage_person_contacts_lookup_personal_emails_create.md)
>
> Request and response reference.


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