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

# Agent Lookup

> Email lookup designed for AI agents. Returns full, human-readable field names and supports selective field retrieval.

## Authentication

Requires a Bearer token in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="email" type="string" required>
  The email address to look up. The legacy key `e` is still accepted.
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated list of fields to return. Omit to return all fields.

  Available fields: `name`, `email`, `company`, `role`, `industry`, `location`, `birthplace`, `current_location`, `bio`, `age`, `gender`, `education`, `phone`, `photo`, `validity`, `socials`, `breach`, `registered_services`, `news`, `publications`
</ParamField>

### Field reference

| Key                   | Description                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| `name`                | Full name                                                               |
| `email`               | Email                                                                   |
| `company`             | Company                                                                 |
| `role`                | Job role                                                                |
| `industry`            | Industry                                                                |
| `location`            | Location (city, country)                                                |
| `birthplace`          | Birthplace                                                              |
| `current_location`    | Current/company location                                                |
| `bio`                 | Biography                                                               |
| `age`                 | Age                                                                     |
| `gender`              | Gender                                                                  |
| `education`           | Education (level + university + field)                                  |
| `phone`               | Company phone                                                           |
| `photo`               | Photo URL                                                               |
| `validity`            | Email validity (`valid`, `invalid`, `disposable`, `unknown`)            |
| `socials`             | Social links (`linkedin`, `twitter`, `instagram`, `facebook`, `github`) |
| `breach`              | Breach info (`count`, `services`, `exposed_data`)                       |
| `registered_services` | Registered services (`count`, `services`)                               |
| `news`                | News mentions (`title`, `url`, `date`, `source`)                        |
| `publications`        | Publications (`title`, `url`, `year`, `cited_by`)                       |

### Example request

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST "https://encrata.com/api/agent/lookup?fields=name,company,role,socials" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "satya@microsoft.com"}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://encrata.com/api/agent/lookup",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"email": "satya@microsoft.com"},
      params={"fields": "name,company,role,socials"},
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch(
    "https://encrata.com/api/agent/lookup?fields=name,company,role,socials",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email: "satya@microsoft.com" }),
    }
  );
  const data = await resp.json();
  ```
</CodeGroup>

## Response

<ResponseField name="name" type="string">
  Full name (first + middle + last).
</ResponseField>

<ResponseField name="email" type="string">
  Email address.
</ResponseField>

<ResponseField name="company" type="string">
  Company name.
</ResponseField>

<ResponseField name="role" type="string">
  Job role / title.
</ResponseField>

<ResponseField name="industry" type="string">
  Industry.
</ResponseField>

<ResponseField name="location" type="string">
  Location as "city, country".
</ResponseField>

<ResponseField name="birthplace" type="string">
  Birthplace (parsed from knowledge graph).
</ResponseField>

<ResponseField name="current_location" type="string">
  Current/company location.
</ResponseField>

<ResponseField name="bio" type="string">
  Short biography.
</ResponseField>

<ResponseField name="age" type="string">
  Age.
</ResponseField>

<ResponseField name="gender" type="string">
  Gender.
</ResponseField>

<ResponseField name="education" type="string">
  Education summary (level, university, field).
</ResponseField>

<ResponseField name="phone" type="string">
  Company phone.
</ResponseField>

<ResponseField name="photo" type="string">
  Profile photo URL.
</ResponseField>

<ResponseField name="validity" type="string">
  Email validity: `valid`, `invalid`, `disposable`, or `unknown`.
</ResponseField>

<ResponseField name="socials" type="object">
  Social media links.

  <Expandable title="Social fields">
    <ResponseField name="linkedin" type="string">LinkedIn URL</ResponseField>
    <ResponseField name="twitter" type="string">Twitter/X URL</ResponseField>
    <ResponseField name="instagram" type="string">Instagram URL</ResponseField>
    <ResponseField name="facebook" type="string">Facebook URL</ResponseField>
    <ResponseField name="github" type="string">GitHub URL</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="breach" type="object">
  Data breach exposure.

  <Expandable title="Breach fields">
    <ResponseField name="count" type="integer">Number of breaches</ResponseField>
    <ResponseField name="services" type="string[]">Breached service names</ResponseField>
    <ResponseField name="exposed_data" type="string[]">Exposed data types</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="registered_services" type="object">
  Registered services (from account-discovery probes).

  <Expandable title="Registered fields">
    <ResponseField name="count" type="integer">Number of registered services</ResponseField>
    <ResponseField name="services" type="string[]">Service names</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="news" type="array">
  News mentions.

  <Expandable title="News item">
    <ResponseField name="title" type="string">Title</ResponseField>
    <ResponseField name="url" type="string">URL</ResponseField>
    <ResponseField name="date" type="string">Date</ResponseField>
    <ResponseField name="source" type="string">Source</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="publications" type="array">
  Academic publications.

  <Expandable title="Publication item">
    <ResponseField name="title" type="string">Title</ResponseField>
    <ResponseField name="url" type="string">URL</ResponseField>
    <ResponseField name="year" type="integer">Year</ResponseField>
    <ResponseField name="cited_by" type="integer">Cited by count</ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={"dark"}
{
  "name": "Satya Nadella",
  "company": "Microsoft",
  "role": "CEO",
  "birthplace": "Hyderabad, India",
  "current_location": "Redmond, Washington, US",
  "validity": "valid",
  "socials": {
    "linkedin": "https://linkedin.com/in/satyanadella"
  },
  "breach": {
    "count": 12,
    "services": ["Adobe", "LinkedIn"]
  },
  "registered_services": {
    "count": 3,
    "services": ["Twitter", "Spotify", "GitHub"]
  }
}
```

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "name": "Satya Nadella",
    "email": "satya@microsoft.com",
    "company": "Microsoft",
    "role": "CEO",
    "industry": "Technology",
    "location": "Redmond, US",
    "birthplace": "Hyderabad, India",
    "current_location": "Redmond, Washington, US",
    "validity": "valid",
    "socials": {
      "linkedin": "https://linkedin.com/in/satyanadella"
    },
    "breach": {
      "count": 12,
      "services": ["Adobe", "LinkedIn"]
    },
    "registered_services": {
      "count": 3,
      "services": ["Twitter", "Spotify", "GitHub"]
    }
  }
  ```

  ```json 400 theme={"dark"}
  {
    "c": 400,
    "m": "bad email"
  }
  ```

  ```json 401 theme={"dark"}
  {
    "c": 401,
    "m": "bad key"
  }
  ```

  ```json 405 theme={"dark"}
  {
    "c": 405,
    "m": "POST only"
  }
  ```
</ResponseExample>