> ## Documentation Index > Fetch the complete documentation index at: https://docs.findly.icu/llms.txt > Use this file to discover all available pages before exploring further. # Phonebook > Lists every known selector for a domain: email addresses (`type: email`), subdomains (`type: domain`) or URLs (`type: url`). Up to 5,000 selectors per response, or a plain text list with `?format=txt`. ## OpenAPI ````yaml /openapi.json post /api/v1/search/phonebook openapi: 3.1.0 info: title: Find.ly API version: 1.0.0 description: >- Search leak and OSINT data from your own code with the same five modules, quota and limits as the Find.ly dashboard. API access comes with the Professional and Enterprise plans. Every search is `POST /api/v1/search/{module}`, where `{module}` is one of `intelligence-search`, `phonebook`, `identity-portal`, `system-id`, `storage-id`. Each module has its own reference page below because each takes a different body. servers: - url: https://findly.icu description: Production security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Account description: 'Plan and quota. Free: never billed.' - name: Search description: One request per served search. paths: /api/v1/search/phonebook: post: tags: - Search summary: Phonebook description: >- Lists every known selector for a domain: email addresses (`type: email`), subdomains (`type: domain`) or URLs (`type: url`). Up to 5,000 selectors per response, or a plain text list with `?format=txt`. operationId: search_phonebook parameters: - name: format in: query required: false description: >- `json` (default) or `txt`. Same search, same price, different output. schema: type: string enum: - json - txt default: json requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PhonebookRequest' examples: request: value: type: email query: '@example.com' responses: '200': description: >- Search served (billed). JSON by default; with `?format=txt`, a `text/plain` attachment named `phonebook-{type}-{query}.txt`, one selector per line, with `X-Results-Total` and `X-Results-Truncated`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' Content-Disposition: $ref: '#/components/headers/ContentDisposition' X-Results-Total: $ref: '#/components/headers/XResultsTotal' X-Results-Truncated: $ref: '#/components/headers/XResultsTruncated' content: application/json: schema: $ref: '#/components/schemas/SelectorsResponse' examples: results: value: module: phonebook query: '@example.com' type: email total: 2 returned: 2 truncated: false results: - selector: john.doe@example.com date: '2023-11-02T00:00:00.000Z' date_raw: '2023-11-02' - selector: jane@example.com date: null date_raw: null billed: true usage: plan: Professional plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 500 used: 13 remaining: 487 resets_at: '2026-09-17T00:00:00.000Z' empty: value: module: phonebook query: '@example.com' type: email total: 0 returned: 0 truncated: false results: [] billed: true usage: plan: Professional plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 500 used: 13 remaining: 487 resets_at: '2026-09-17T00:00:00.000Z' text/plain: schema: type: string examples: text: value: | john.doe@example.com jane@example.com '204': description: >- Only with `?format=txt`: the search succeeded but returned nothing. No body; `X-Request-Billed` says whether it was billed. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' '400': description: Bad request. `api_key_in_url`, `unsupported_format`, `invalid_json`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: api_key_in_url: value: error: code: api_key_in_url message: >- Send your API key in the Authorization header, never in the URL. If it was logged somewhere, regenerate it from your dashboard. billed: false unsupported_format: value: error: code: unsupported_format message: >- format must be json or txt for Phonebook. No request was used. billed: false invalid_json: value: error: code: invalid_json message: >- Send a JSON object in the request body, with Content-Type: application/json. billed: false '401': description: Missing or invalid API key. `missing_api_key`, `invalid_api_key`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' WWW-Authenticate: $ref: '#/components/headers/WWWAuthenticate' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: value: error: code: missing_api_key message: >- Send your API key in the Authorization header: "Authorization: Bearer fly_live_…". billed: false invalid_api_key: value: error: code: invalid_api_key message: >- This API key is not valid. Copy it again from the API page of your dashboard. billed: false '403': description: >- `account_suspended`, `plan_required`, or `module_locked` (the plan does not include this module; carries `required_plan`). `module_locked` only happens if the plan expires during the call. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: account_suspended: value: error: code: account_suspended message: >- This account is suspended. If you think this is a mistake, contact us. billed: false plan_required: value: error: code: plan_required message: >- Your Starter plan doesn’t include API access. It comes with the Professional and Enterprise plans. plan: Starter billed: false usage: plan: Starter plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 100 used: 0 remaining: 100 resets_at: '2026-09-17T00:00:00.000Z' module_locked: value: error: code: module_locked message: Phonebook requires the Professional plan. required_plan: Professional billed: false usage: plan: Professional plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 500 used: 13 remaining: 487 resets_at: '2026-09-17T00:00:00.000Z' '413': description: Request body over 16 KB. `body_too_large`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: body_too_large: value: error: code: body_too_large message: The request body must be 16 KB or less. billed: false '422': description: >- Invalid input, not billed. `invalid_input` with one message per field in `error.fields`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_input: value: error: code: invalid_input message: Some fields are invalid. No request was used. fields: query: >- For emails, enter a domain starting with @ — for example @openai.com. billed: false '429': description: >- `too_many_requests` (per IP), `quota_exceeded` (daily quota; carries `usage`), `rate_limited` (per account; `reason` is `concurrent` or `per-minute`). Always sends `Retry-After`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: too_many_requests: value: error: code: too_many_requests message: >- Too many API calls from this address. Slow down and try again. billed: false quota_exceeded: value: error: code: quota_exceeded message: >- You’ve used all of today’s requests. Your quota resets at 02:00 Paris time. billed: false usage: plan: Professional plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 500 used: 500 remaining: 0 resets_at: '2026-09-17T00:00:00.000Z' rate_limited_concurrent: value: error: code: rate_limited message: >- Two searches are already running on this account. Try again when one finishes. reason: concurrent billed: false rate_limited_per_minute: value: error: code: rate_limited message: Too many searches in the last minute. Try again shortly. reason: per-minute billed: false '500': description: Unexpected server error. `internal_error`. No request was used. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: value: error: code: internal_error message: Something went wrong on our side. No request was used. billed: false '502': description: >- The search service failed. `upstream_error`. The request is refunded (`billed: false`). headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: upstream_error: value: error: code: upstream_error message: >- Search is unavailable on our side right now. It’s not your plan or your quota. upstream_status: null billed: false usage: plan: Professional plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 500 used: 13 remaining: 487 resets_at: '2026-09-17T00:00:00.000Z' components: schemas: PhonebookRequest: type: object required: - type - query additionalProperties: false properties: type: type: string enum: - email - domain - url description: >- What you want back: email addresses, domains (subdomains) or URLs. Case-insensitive. query: type: string maxLength: 200 description: >- Its shape depends on `type`: `@example.com` for `email`, `example.com` for `domain`, `https://example.com` for `url` (http or https, a real domain name, no credentials). Sent lowercased. examples: - '@example.com' SelectorsResponse: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: - module - query - type - results properties: module: type: string const: phonebook query: type: string description: The query as searched (trimmed, lowercased). type: type: string enum: - email - domain - url results: type: array items: $ref: '#/components/schemas/Selector' ErrorResponse: type: object required: - error - billed properties: error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable. It can change: branch on `code`, not on `message`. fields: type: object additionalProperties: type: string description: '`invalid_input` only. One message per invalid or unknown field.' plan: type: string description: '`plan_required` only. The current plan.' required_plan: type: string description: '`module_locked` only. Cheapest plan that includes the module.' reason: type: string enum: - concurrent - per-minute description: '`rate_limited` only. Which account limit was hit.' upstream_status: type: - integer - 'null' description: >- `upstream_error` only. HTTP status returned by the search service when it sent one (400 or above), otherwise `null`. billed: type: boolean description: Errors are never billed. usage: $ref: '#/components/schemas/Usage' ListMeta: type: object required: - total - returned - truncated - billed - usage properties: total: type: integer description: Results found. returned: type: integer description: Results in `results` (5,000 max). truncated: type: boolean description: '`true` if `total` is greater than `returned`.' billed: type: boolean usage: $ref: '#/components/schemas/Usage' Selector: type: object required: - selector - date - date_raw properties: selector: type: string description: Email, domain or URL (up to 500 characters). date: type: - string - 'null' format: date-time date_raw: type: - string - 'null' ErrorCode: type: string description: >- Stable, machine-readable error code: - `api_key_in_url`: 400 — an API key was sent in the query string (`key`, `api_key`, `apikey`, `token` or `access_token`). - `invalid_json`: 400 — the body is missing, is not valid UTF-8 JSON, or is not a JSON object. - `unsupported_format`: 400 — `format` is not `json`, or `txt` was asked for a module that has no text output. - `missing_api_key`: 401 — neither `Authorization` nor `X-API-Key` was sent. - `invalid_api_key`: 401 — the key is malformed, unknown, regenerated, or belongs to a deleted account. - `account_suspended`: 403 — the account that owns the key is suspended. - `plan_required`: 403 — the account plan does not include API access (Professional and Enterprise only). - `module_locked`: 403 — the account plan does not include this module. - `unknown_module`: 404 — `{module}` is not one of the five module slugs. - `not_found`: 404 — no API endpoint at this path. - `body_too_large`: 413 — the request body is over 16 KB. - `invalid_input`: 422 — a field is unknown, has the wrong type, or has an invalid value. See `error.fields`. - `too_many_requests`: 429 — more than 60 API calls in one minute from the same IP address. - `quota_exceeded`: 429 — the account has used all of today's requests. - `rate_limited`: 429 — two searches already running, or 20 searches in the last minute, on this account. - `internal_error`: 500 — unexpected server error. No request was used. - `upstream_error`: 502 — the search service failed, timed out, or sent an unreadable or oversized response. The request is refunded. enum: - api_key_in_url - invalid_json - unsupported_format - missing_api_key - invalid_api_key - account_suspended - plan_required - module_locked - unknown_module - not_found - body_too_large - invalid_input - too_many_requests - quota_exceeded - rate_limited - internal_error - upstream_error Usage: type: object description: Quota of the account, after the call. required: - plan - plan_expires_at - daily_quota - used - remaining - resets_at properties: plan: type: string enum: - Free - Starter - Professional - Enterprise plan_expires_at: type: - string - 'null' format: date-time description: End of the paid plan. `null` on Free. daily_quota: type: integer description: 'Requests per day: 500 on Professional, 1,500 on Enterprise.' used: type: integer description: Requests used today, dashboard and API combined. remaining: type: integer description: Requests left today. resets_at: type: string format: date-time description: Next reset, 02:00 Europe/Paris. headers: CacheControl: description: Always `no-store`. schema: type: string const: no-store XRequestBilled: description: >- `true` if this call used one request from the daily quota, otherwise `false`. schema: type: string enum: - 'true' - 'false' XQuotaLimit: description: >- Daily quota of the plan. Sent whenever the account quota is known (not on authentication or IP-limit errors). schema: type: string examples: - '500' XQuotaRemaining: description: Requests left today, after this call. schema: type: string examples: - '487' XQuotaReset: description: ISO 8601 time of the next reset (02:00 Europe/Paris). schema: type: string format: date-time ContentDisposition: description: >- `attachment; filename="…"`. The file name only contains `A-Z a-z 0-9 . _ -`. schema: type: string XResultsTotal: description: Selectors found, before the 5,000 cap. schema: type: string XResultsTruncated: description: '`true` if the list was cut at 5,000 selectors.' schema: type: string enum: - 'true' - 'false' WWWAuthenticate: description: >- `Bearer realm="Find.ly API"`, with `error="invalid_token"` for `invalid_api_key`. schema: type: string RetryAfter: description: Seconds to wait before retrying (at least 1). schema: type: string examples: - '3' securitySchemes: bearerAuth: type: http scheme: bearer description: >- `Authorization: Bearer fly_live_…`. Takes precedence when both headers are sent. apiKeyHeader: type: apiKey in: header name: X-API-Key description: >- `X-API-Key: fly_live_…`. Used only when no `Authorization` header is sent. ````