Phonebook

Phonebook takes a domain, an email address or a URL, and lists the selectors the archive has seen around it: email addresses, domains and subdomains, or URLs, each with the date it was found. You choose which kind you get back with type. Use it to map an organisation from its domain. To find the records that mention one selector, use Intelligence Search instead.

When to use it

You have a company’s domain and want the email addresses the archive knows at it.
You want the subdomains of a domain, or the URLs seen on it.
You want new selectors to search next, with Intelligence Search or the OSINT modules.

Request

POST /v1/search/phonebook, with a JSON body.

Parameter	Type	Required	What it does
`query`	string	Yes	The domain, email address or URL to look up. 200 characters at most.
`type`	string	Yes	What you want back: `email`, `domain` or `url`. Case does not matter.

Any other field is refused with 400 invalid_request, and nothing is charged. type is the kind of selector you want back, not the kind of query you send:

You want	`query`	`type`
Email addresses at a domain	`@example.com`	`email`
Subdomains of a domain	`example.com`	`domain`
URLs on a domain	`example.com`	`url`

To list the email addresses of a domain, the archive needs the domain with a leading @. With type: "email" and a bare domain such as example.com, the API adds the @ for you. A full address, a URL or a path is sent as it is.

curl https://api.orelys.io/v1/search/phonebook \
  -H "Authorization: Bearer $ORELYS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "@example.com", "type": "email" }' \
  --max-time 120

const response = await fetch("https://api.orelys.io/v1/search/phonebook", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORELYS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "@example.com", type: "email" }),
  signal: AbortSignal.timeout(120_000),
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

for (const item of data.results) console.log(item.selector, item.date);
console.log(`${data.count} selectors, charged: ${data.charged}`);

import os
import requests

response = requests.post(
    "https://api.orelys.io/v1/search/phonebook",
    headers={"Authorization": f"Bearer {os.environ['ORELYS_API_KEY']}"},
    json={"query": "@example.com", "type": "email"},
    timeout=120,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")

addresses = sorted({item["selector"] for item in data["results"] if item.get("selector")})
print("\n".join(addresses))
print("Requests left today:", data["quota"]["remaining"])

Like every list mode, the search service has 85 seconds to start answering; past that, the API answers 504 source_timeout, which costs nothing. Set your HTTP client’s timeout to at least 100 seconds — 120 seconds, as above, is a safe value.

What you get back

{
  "mode": "phonebook",
  "request": { "query": "@example.com", "type": "email" },
  "count": 2,
  "results": [
    { "selector": "contact@example.com", "date": "2022-11-03T00:00:00Z" },
    { "selector": "jobs@example.com", "date": "2021-04-19T00:00:00Z" }
  ],
  "charged": true,
  "quota": { "limit": 500, "used": 14, "remaining": 486, "resets_at": "2026-09-26T00:00:00.000Z" }
}

Field	What it is
`mode`	`phonebook`.
`request`	Your search as sent to the archive, with `type` in lower case and the `@` added when the API added it.
`count`	Number of items in `results`.
`results`	The selectors found. `[]` when there are none.
`charged`	Whether the search took a request. Also in the `X-Request-Charged` header.
`quota`	Your quota after this search.
`redacted`	Only there when selectors were left out because they mention a removed selector.
`source`	Only there when the archive sent other facts with the list, such as a `total`, passed on as they are.

Each item of results has a selector (the email address, domain or URL found) and the date it was found. Any field can be missing, and other fields can appear.

Selectors come from leaked data. Show them as text, never as HTML, and do not follow the URLs automatically.

Cost and limits

Case	Requests
A search that returns selectors	1, from your daily quota.
A search that completes with an empty list	1, as in the dashboard.
The archive answers “no results”, or refuses the search (`400 rejected`)	0, within a daily allowance (your daily quota, at least 10). Past it, 1.
Connection closed after the search was sent	0, within the same daily allowance.
A search for a removed selector	0: an empty result, and the archive is not asked.
Invalid input, a limit reached, the search service down, busy or too slow	0.

Plans: Professional (500 requests a day) and Enterprise (1,500). Both include Phonebook.
Per account: 60 searches a minute and 3 at the same time on Professional, 120 and 5 on Enterprise, shared with all your other searches.
Per address: 120 calls a minute, whatever the plan.

See Limits for the details.

Errors

Status	Code	When
`400`	`invalid_request`	`query` or `type` is missing, or `type` is not `email`, `domain` or `url`. `details` lists each problem.
`400`	`rejected`	The search service refused the search. Check the values.
`401`	`missing_api_key`, `invalid_api_key`	No key was sent, or it is not a valid one.
`403`	`plan_required`, `account_blocked`	The account is not on Professional or Enterprise, or it is blocked.
`429`	`rate_limited`, `concurrency_limited`, `ip_rate_limited`, `quota_exceeded`	A limit is reached. Wait `Retry-After` seconds.
`502`	`source_error`, `source_unreachable`, `response_too_large`	The search service failed, or the answer is too large. Try again later.
`503`	`service_unavailable`, `source_busy`	Search is down or busy for a moment.
`503`	`module_maintenance`, `module_offline`	The Orelys team has paused this mode, or all of Intelligence X. Nothing is charged. Under maintenance, wait `Retry-After` seconds.
`504`	`source_timeout`	The search service did not start answering within 85 seconds.

Errors use the usual envelope: { "error": { "code": "…", "message": "…" } }.

Tips

Pick type for what you want back. Searching a domain with type: "email" is right: it lists the addresses at that domain.
One search per kind. A search returns one kind of selector. For the addresses, the subdomains and the URLs of a domain, send three searches, each one a request.
There is no max_results. The answer holds every selector the search service returns. Sort and deduplicate on your side.
Send each selector on. An email address can go to Intelligence Search for the records that mention it, or to the OSINT Email search for the identity behind it.
date is when the selector was found in the archive, not when it was created.

Reference

Request and response schemas, every error, and a playground to try it.

Get started

Essentials

Intelligence X

OSINT

Data breaches

Privacy

Phonebook

When to use it

Request

What you get back

Cost and limits

Errors

Tips

Reference

Phonebook

​When to use it

​Request

​What you get back

​Cost and limits

​Errors

​Tips

​Reference

Phonebook

When to use it

Request

What you get back

Cost and limits

Errors

Tips

Reference