<!-- @generated by `npm run docs:gen` from src/content/docs/ — DO NOT EDIT. -->

# Find a person by email or phone

Find the person behind a work email address or a phone number. 1 credit per person found — nothing when there is no match.

`POST /v1/lookup`

Authenticated with your `x-api-key`. See [Authentication](https://ask.xverum.com/docs/authentication.md).

## How it works

Send a whole work email address **or** a whole phone number, and get back the people who hold it — the same profile summaries a [search](https://ask.xverum.com/docs/search.md) returns, each with its `id`.

**Exact match only.** The whole email address (`jane.doe@acme.com`), and the whole phone number **with its country code** (`+972 50 254 4777` or `00972502544777`; spaces, dashes and brackets are fine). A number without its country code is refused with a `422` saying so: the same digits are a different number in each country, so we never guess one.

**The person, not their contact data.** A lookup tells you who holds the email or number. To get that person's email addresses or phone numbers, pass the `id` to [Email and phone](https://ask.xverum.com/docs/contacts.md); for the full profile, to [`GET /v1/profiles/{id}`](https://ask.xverum.com/docs/profiles.md).

**You pay only for people found.** No match returns a `200` with `results: []` and is charged **`0`**.

## Request

```http
POST /v1/lookup
Host: search-api.xverum.com
x-api-key: XVERUM-API-KEY
Content-Type: application/json
```

### Body

Send **exactly one** of `email` or `phone`.

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| `email` | string | one of | 3–320 chars | A whole work email address, matched exactly |
| `phone` | string | one of | 4–40 chars, must start with `+` or `00` | A whole phone number with its country code, matched exactly |

### Example body

```json
{ "email": "jane.doe@example.com" }
```

```json
{ "phone": "+1 202 555 0123" }
```

## Example

```bash
curl -X POST "https://search-api.xverum.com/v1/lookup" \
  -H "x-api-key: XVERUM-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@example.com"}'
```

```bash
curl -X POST "https://search-api.xverum.com/v1/lookup" \
  -H "x-api-key: XVERUM-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1 202 555 0123"}'
```

## Response — 200 OK

| Field | Type | Description |
| --- | --- | --- |
| `results` | object[] | The people who hold this email or number, at most 10; `[]` when there is no match |
| `results[].id` | string | Opaque profile id — pass it to [Email and phone](https://ask.xverum.com/docs/contacts.md) or [`GET /v1/profiles/{id}`](https://ask.xverum.com/docs/profiles.md) |
| `results[].full_name` | string | Full name |
| `results[].headline` | string \| null | Profile headline |
| `results[].location` | string \| null | Location |
| `results[].company_name` | string \| null | Current company |
| `results[].position` | string \| null | Current position |
| `results[].industry` | string \| null | Industry |
| `results[].social_url` | string \| null | Public profile URL |
| `results[].evidence_summary` | string | How recently the profile was verified |
| `more` | boolean | `true` when more people hold this value than were returned (a shared address such as `info@…`, or a switchboard number). There is no paging |
| `credits_used` | integer | Credits deducted — `1` per person returned, `0` when there is no match |
| `credits_remaining` | integer | Balance left after this call |
| `request_id` | string | Correlation id — also returned in the `X-Request-Id` header |
| `message` | string | Only when no one is shown — no match, or `more` with none that can be shown: guidance to show the user. Do not parse it |

```json
{
  "results": [
    {
      "id": "a1b2c3d4",
      "full_name": "Jane Doe",
      "headline": "VP Sales at Acme",
      "location": "Washington, DC, United States",
      "company_name": "Acme",
      "position": "VP Sales",
      "industry": "Software Development",
      "social_url": "https://www.linkedin.com/in/jane-doe",
      "evidence_summary": "Verified last 30 days"
    }
  ],
  "more": false,
  "credits_used": 1,
  "credits_remaining": 4999,
  "request_id": "1a2b3c4d5e6f7081"
}
```

### Example response — no match

```json
{
  "results": [],
  "more": false,
  "credits_used": 0,
  "credits_remaining": 5000,
  "request_id": "1a2b3c4d5e6f7081",
  "message": "No one found for that email address or phone number."
}
```

## Billing

**1 credit per person returned**, echoed as `credits_used`. No match is **free**. A lookup is not deduped: repeating it is charged again.

If your balance is smaller than the number of people found, the list is cut to what you can pay for and `more` is `true`. With less than 1 credit the call is refused with `402` before anything is looked up.

## Errors

All `/v1` errors use the structured envelope (see [Authentication](https://ask.xverum.com/docs/authentication.md)):

| Status | `error.code` | Condition |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing or invalid API key |
| `402` | `out_of_credits` | Out of credits — the envelope carries an `upgrade_url` to top up |
| `403` | `account_not_authorized` | Account not authorized |
| `422` | `validation_error` | Not exactly one of `email` / `phone`, not a whole email address, or a number without its country code — the message says which |
| `429` | `rate_limited` | Rate limit exceeded — retry after `Retry-After`. See [Rate limits](https://ask.xverum.com/docs/rate-limits.md) |
| `502` | `upstream_unavailable` | The contact store failed — nothing charged, retry shortly |
| `503` | `search_unavailable` | Temporarily unavailable, or the lookup took too long — retry shortly |