---
title: "Find Email"
method: POST
path: "/functions/v1/api/v2/find-email"
---

# Find Email

`POST /functions/v1/api/v2/find-email`

## Request

- Base URL: `https://api.signaliz.com`
- URL: `https://api.signaliz.com/functions/v1/api/v2/find-email`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- union: For a fresh single lookup, provide an HTTPS LinkedIn person profile URL (/in/<slug>) alone or a person name with company_domain.
  - object
    - `company_domain` string
    - `full_name` string
    - `first_name` string
    - `last_name` string
    - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path. May be provided as the sole identity input.
    - `company_name` string
    - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
    - `wait_for_result` boolean: Set false to receive the durable run ID immediately, then resume with run_id without duplicate work or spend.
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `job_id` string: Resume a recoverable Find Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `page` integer
    - `page_size` integer
    - `requests` FindEmailBatchRequest[]: Up to 25 requests run synchronously. Larger batches use one recoverable email-finding job.
      - union: One Find Email batch row. Provide run_id to resume existing work, an HTTPS LinkedIn person profile URL (/in/<slug>) alone, or company_domain with a supported name shape.
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string, required
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
    - `concurrency` integer
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
  - object
    - `company_domain` string, required
    - `full_name` string, required
    - `first_name` string
    - `last_name` string
    - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path. May be provided as the sole identity input.
    - `company_name` string
    - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
    - `wait_for_result` boolean: Set false to receive the durable run ID immediately, then resume with run_id without duplicate work or spend.
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `job_id` string: Resume a recoverable Find Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `page` integer
    - `page_size` integer
    - `requests` FindEmailBatchRequest[]: Up to 25 requests run synchronously. Larger batches use one recoverable email-finding job.
      - union: One Find Email batch row. Provide run_id to resume existing work, an HTTPS LinkedIn person profile URL (/in/<slug>) alone, or company_domain with a supported name shape.
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string, required
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
    - `concurrency` integer
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
  - object
    - `company_domain` string, required
    - `full_name` string
    - `first_name` string, required
    - `last_name` string, required
    - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path. May be provided as the sole identity input.
    - `company_name` string
    - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
    - `wait_for_result` boolean: Set false to receive the durable run ID immediately, then resume with run_id without duplicate work or spend.
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `job_id` string: Resume a recoverable Find Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `page` integer
    - `page_size` integer
    - `requests` FindEmailBatchRequest[]: Up to 25 requests run synchronously. Larger batches use one recoverable email-finding job.
      - union: One Find Email batch row. Provide run_id to resume existing work, an HTTPS LinkedIn person profile URL (/in/<slug>) alone, or company_domain with a supported name shape.
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string, required
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
    - `concurrency` integer
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
  - object
    - `company_domain` string
    - `full_name` string
    - `first_name` string
    - `last_name` string
    - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path. May be provided as the sole identity input.
    - `company_name` string
    - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
    - `wait_for_result` boolean: Set false to receive the durable run ID immediately, then resume with run_id without duplicate work or spend.
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `job_id` string: Resume a recoverable Find Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `page` integer
    - `page_size` integer
    - `requests` FindEmailBatchRequest[], required: Up to 25 requests run synchronously. Larger batches use one recoverable email-finding job.
      - union: One Find Email batch row. Provide run_id to resume existing work, an HTTPS LinkedIn person profile URL (/in/<slug>) alone, or company_domain with a supported name shape.
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string, required
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
    - `concurrency` integer
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
  - object
    - `company_domain` string
    - `full_name` string
    - `first_name` string
    - `last_name` string
    - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path. May be provided as the sole identity input.
    - `company_name` string
    - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
    - `wait_for_result` boolean: Set false to receive the durable run ID immediately, then resume with run_id without duplicate work or spend.
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `job_id` string, required: Resume a recoverable Find Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `page` integer
    - `page_size` integer
    - `requests` FindEmailBatchRequest[]: Up to 25 requests run synchronously. Larger batches use one recoverable email-finding job.
      - union: One Find Email batch row. Provide run_id to resume existing work, an HTTPS LinkedIn person profile URL (/in/<slug>) alone, or company_domain with a supported name shape.
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string, required
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
    - `concurrency` integer
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
  - object
    - `company_domain` string
    - `full_name` string
    - `first_name` string
    - `last_name` string
    - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path. May be provided as the sole identity input.
    - `company_name` string
    - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
    - `wait_for_result` boolean: Set false to receive the durable run ID immediately, then resume with run_id without duplicate work or spend.
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `job_id` string: Resume a recoverable Find Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `page` integer
    - `page_size` integer
    - `requests` FindEmailBatchRequest[]: Up to 25 requests run synchronously. Larger batches use one recoverable email-finding job.
      - union: One Find Email batch row. Provide run_id to resume existing work, an HTTPS LinkedIn person profile URL (/in/<slug>) alone, or company_domain with a supported name shape.
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri, required: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string, required
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
        - object
          - `run_id` string, required: Resume one workspace-owned Find Email run without dispatching a new finder
          - `company_domain` string
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `linkedin_url` string, uri: HTTPS LinkedIn person profile URL with an /in/<slug> path.
          - `company_name` string
          - `idempotency_key` string
    - `concurrency` integer
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.

## Response `200`

Email lookup result

- FindEmailResult
  - `success` boolean
  - `index` integer
  - `duplicate_of` integer: Stable input index containing the full result for this exact duplicate.
  - `dry_run` true
  - `input_count` integer
  - `fresh_input_count` integer
  - `unique_fresh_input_count` integer
  - `recovery_read_count` integer
  - `unique_recovery_read_count` integer
  - `plan` object
  - `estimate` object
  - `estimated_credits` object
  - `credits_charged` 0
  - `side_effects` unknown[]
    - unknown
  - `email` string, email, nullable
  - `checked_email` string, email, nullable: The mailbox actually checked, including non-send-safe candidates.
  - `candidate_source` string
  - `primary_verifier` 'million_verifier'
  - `primary_verdict` string
  - `terminal_verifier` 'bounceban'
  - `terminal_verdict` string
  - `terminal_result` string
  - `terminal_is_catch_all` boolean, nullable
  - `terminal_is_accept_all` boolean, nullable
  - `bounceban_id` string, nullable
  - `status` string
  - `is_valid` boolean
  - `credits_used` number
  - `verification_status` string
  - `deliverability_status` string
  - `verification_verdict` string
  - `verified_for_sending` boolean
  - `is_deliverable` boolean
  - `email_is_catch_all` boolean
  - `is_catch_all` boolean
  - `verification_source` string
  - `verification_observed_at` string, date-time: Provider observation time used to arbitrate the winning terminal verdict.
  - `failure_reason` string
  - `billing_replayed` boolean
  - `run_id` string: Durable Find Email run ID used for polling or completion provenance
  - `next_poll_after_seconds` number
  - `suggested_action` string
  - `retry_eligible` boolean
  - `retry_strategy` 'same_run_recovery'
  - `do_not_auto_resubmit` boolean
  - `recovery_mode` 'same_run'
  - `recovery_status` 'pending' | 'completed'
  - `job_id` string
  - `job_capability` string
  - `idempotency_replayed` boolean
  - `idempotency_key` string
  - `page` integer
  - `page_size` integer
  - `total_results` integer
  - `total_pages` integer
  - `has_more` boolean
  - `total` integer
  - `succeeded` integer
  - `processing` integer
  - `failed` integer
  - `input_duplicates_suppressed` integer
  - `unique_tasks_dispatched` integer
  - `results` union[]
    - union
      - FindEmailResult (recursive)
      - CoreProductBatchError
        - `success` false, required
        - `error` string, required
        - `error_code` string, required: Stable machine code. PAYLOAD_TOO_LARGE means a durable Company Signal or Signal Copy request exceeded a per-field UTF-8 bound or the 8 MiB encoded request ceiling. BATCH_RESULTS_EXPIRED and RESULT_INTEGRITY_001 are nonretryable retained-result failures. PROVIDER_001 is a provider configuration or policy failure; PROVIDER_002 is provider noncompletion.
        - `message` string, required
        - `retry_eligible` boolean, required
        - `retry_after` integer
        - `retry_after_seconds` integer
        - `retry_strategy` 'new_idempotency_key' | 'same_run_recovery': new_idempotency_key permits an explicit fresh request only with zero-credit proof. same_run_recovery requires reading the returned run ID and forbids resubmitting the original request.
        - `credits_used` 0: Together with credits_charged=0, proves that this failed request consumed no Signaliz credits. Omission means unproven.
        - `credits_charged` 0: Together with credits_used=0, proves that this failed request consumed no Signaliz credits. Omission means unproven.
        - `run_id` string
        - `verification_run_id` string
        - `job_id` string
        - `idempotency_key` string
        - `suggested_action` string: Machine-readable recovery action. retry_with_run_id means resume existing provider work instead of dispatching a new run.
        - `do_not_auto_resubmit` boolean
        - `results_cleaned` boolean
        - `results_expired` boolean
        - `signal_run_id` string
        - `company_signal_run_id` string
        - `resume_context_persisted` boolean
        - `index` integer, required
        - `email` string, nullable, required

## Other responses

- `202`: Email finding is still running; retry with the returned run_id for one lookup or job_id for a large fresh batch
- `429`: Rate limited. Retry after the indicated delay.
- `502`: PROVIDER_001: email verification could not run under the configured provider policy. Obey retry_eligible; zero-credit fields are included only when proven.
- `504`: PROVIDER_002: an email provider did not complete. Retry only when retry_eligible is true; zero-credit fields are included only when proven.

---

[API](https://skmtc.dev/signaliz/apis/signaliz-api.md) · [All operations](https://skmtc.dev/signaliz/apis/signaliz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signaliz/apis/signaliz-api/revisions/53cb64feddad?raw)