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

# Email Lookup API

> Look up a professional and their company from one email address.

## Look up an email

```http theme={null}
POST https://api.superdata.so/v1/email/lookup
```

Send one email address in a JSON body with a [Bearer API key](/reference/authentication). The key needs `people:read` or `mcp:use` scope. Email Lookup returns a person only when the source includes the supplied address exactly. It includes company details only when the person's current employer is supported by the source record. A matching email domain alone does not establish employment.

## Request

| Field | Type | Description |
| - | - | - |
| `email` | string | One valid email address, up to 254 characters. |

```bash theme={null}
curl --request POST \
  --url 'https://api.superdata.so/v1/email/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"email":"alex@example.com"}'
```

The address above is illustrative. Place the email in the request body, not in the URL. Do not include additional fields.

## Response

```json theme={null}
{
  "request_id": "req_01J...",
  "data": {
    "email": "alex@example.com",
    "match_status": "matched",
    "person": {
      "id": "123",
      "full_name": "Alex Example",
      "job_title": "Engineer",
      "location": null,
      "profile_url": "https://linkedin.com/in/alex-example",
      "headline": "Engineer at Example Corp",
      "current_positions": [
        {
          "title": "Engineer",
          "company_name": "Example Corp",
          "company_linkedin_url": "https://linkedin.com/company/example-corp"
        }
      ]
    },
    "company": {
      "id": "456",
      "name": "Example Corp",
      "domain": "example.com",
      "website": "https://example.com",
      "linkedin_url": "https://linkedin.com/company/example-corp",
      "industry": null,
      "employee_count": null
    }
  },
  "meta": {
    "credits_used": 3,
    "person_source": "professional_data",
    "company_source": "professional_data"
  }
}
```

The example is illustrative. Fields may be `null` if the source does not supply them. `current_positions` lists positions marked current by the provider and can contain more than one company. LinkedIn profile and company URLs are provider-supplied; the endpoint does not independently verify LinkedIn ownership or fetch a separate LinkedIn profile. `match_status` tells you what was established:

| Status | Meaning |
| - | - |
| `matched` | The source includes the exact email, and a current position supports the returned company. |
| `person_only` | An exact person match was found, without a supported current employer. |
| `company_only` | No person match was found; the business email domain resolved to a company. This does not establish employment. |
| `not_found` | Neither person nor company was established. |

Valid no-match requests return HTTP `200` with `person: null` and `company: null`. Role addresses such as `support@` do not resolve to a person. Consumer email domains do not produce a company-only match.

## Credits and errors

The endpoint makes up to three metered provider lookups. `meta.credits_used` reports the actual charge for the completed request: up to three credits. A completed provider lookup with no match may still consume a credit. Authentication, validation, and rate-limit rejections before provider work consume zero credits. If a later provider call fails, earlier completed lookups may remain charged.

Errors use the [REST error envelope](/reference/rest-api#responses) and include `X-Request-Id`. The endpoint can return `400` for invalid input, `401` for an invalid key, `403` for insufficient scope, `429` for rate or credit limits, `500` for an internal error, or `502` for a provider failure. Use `Idempotency-Key` to guard against repeated billing when retrying a request; a repeated key may receive `DUPLICATE_REQUEST` while the first execution is pending or completed.


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