> ## 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.

# API recipes: common B2B data workflows

> Step-by-step API example: search for a person by job title with Person Role Search, then look up their phone number.

![B2B data workflow: role search returns a person ID, then a phone number lookup returns contact details](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/b2b-data-workflows-search-then-lookup.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=177911b730d08ae674f0f8b9505002da)

This section provides step-by-step API usage examples. Below, you'll learn how to **search for a person by job title**, extract their `id` from the response, and use that ID to **perform a phone number lookup**.

***

## Search for a Person by Job Title

Use the **Person Role Search API** to find a person by job title. The request below searches for **"Software Engineer"**.

### Request

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_role_search/" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: $FORAGER_API_KEY" \
     -d '{
           "role_title": "Software Engineer",
           "role_is_current": true
         }'
```

### Sample Response

```json Sample response (illustrative values, trimmed) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "search_results": [
    {
      "id": 123456,
      "person": {
        "id": 123,
        "full_name": "John Doe",
        "location": {
          "id": 1,
          "name": "San Francisco, California, United States",
          "osm_locations": []
        }
      },
      "role_title": "Software Engineer",
      "organization": {
        "name": "Tech Corp"
      }
    }
  ],
  "total_search_results": 1
}
```

Extract the `person.id` value (123 in this case) for the next step.

## Look Up a Person's Phone Number

Once you have the `person.id`, use the Person Phone Number Lookup API to retrieve phone number details.

### Request

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

### Sample Response

```json Sample response (illustrative values) theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "phone_number": "+14155552671"
  }
]
```


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