Documentation

Find a person by email or phone

Last updated: 26 October 2026

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.

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 returns, each with its id.

Exact match only. The whole email address ([email protected]), 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; for the full profile, to GET /v1/profiles/{id}.

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

Request

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

{ "email": "[email protected]" }

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

Example

curl -X POST "https://search-api.xverum.com/v1/lookup" \
  -H "x-api-key: XVERUM-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

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 or `GET /v1/profiles/{id}`
`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

{
  "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

{
  "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):

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
`502`	`upstream_unavailable`	The contact store failed — nothing charged, retry shortly
`503`	`search_unavailable`	Temporarily unavailable, or the lookup took too long — retry shortly