---
title: "POST /v1/find_leads"
method: POST
path: "/v1/find_leads"
tags: ["GTM verbs"]
---

# POST /v1/find_leads

`POST /v1/find_leads`

## Request

- Base URL: `https://api.layrcake.dev`
- URL: `https://api.layrcake.dev/v1/find_leads`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `audience` string, required
  - `titles` string[]
  - `locations` string[]
  - `industries` string[]
  - `company_domains` string[]
  - `company_headcount` object
    - `min` integer
    - `max` integer
  - `limit` integer
  - `route` 'balanced' | 'cheapest' | 'broadest' | 'fastest': Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted.
  - `budget_credits` number: Spend ceiling for this call, in credits. If the most the call can cost is above it, limit is lowered to the largest that fits and result.budget_applied says so; the call is refused, before anything is reserved or charged, only when not even one lead fits. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason.
  - `dry_run` boolean: Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason.
  - `offer_token` string: Accept a previous answer's offer: send the same call again, unchanged, with its offer.offer_token. Only the premium step runs, as its own charge at the offer's price, up to its max_credits; the token works once, until expires_at, and only when max_credits is within this key's premium allowance. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason.
  - `premium` 'within_budget': Consent, for this call only, to a dearer source when the standard sources come back short, as long as the whole call, the premium step included, stays within budget_credits (which it requires). The premium step is charged separately and reported in result.premium_step. Without it, budget_credits is only a ceiling. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason.

## Response `200`

Successful outcome

- object
  - `result` union, required
    - object
      - `match_check` object
        - `status` 'checked' | 'partial' | 'unchecked', required
        - `kept` integer, required
        - `withheld` integer, required
        - `not_checked` integer, required
        - `unsure` integer
        - `charged` integer
      - `leads` object[], required
        - `fingerprint` string, required
        - `full_name` string, nullable, required
        - `title` string, nullable, required
        - `company_name` string, nullable, required
        - `company_domain` string, nullable, required
        - `work_email` string, nullable, required
        - `work_email_status` 'valid' | 'catch_all' | 'unknown' | 'not_found', nullable, required
        - `email_verdict` 'valid' | 'invalid' | 'catch_all_valid' | 'catch_all_unknown' | 'unknown' | 'risky', nullable
        - `mobile_phone` string, nullable, required
        - `linkedin_url` string, nullable, required
        - `location` string, nullable, required
        - `observed_at` string, nullable, required
      - `total_found` integer, required
      - `budget_applied` object
        - `limit_requested` integer, required
        - `limit_used` integer, required
      - `offer` object
        - `offer_token` string, required
        - `reason` 'none_found_standard' | 'partially_filled' | 'filter_needs_premium', required
        - `credits_per_result` string, required
        - `max_results` integer, required
        - `max_credits` string, required
        - `expires_at` string, required
      - `premium_step` object
        - `request_id` string, required
        - `results_added` integer, required
        - `credits_charged` string, required
      - `interpreted` object
        - `places` object[], required
          - `requested` string, required
          - `region` string, required
          - `cities` string[], required
          - `version` string, required
      - `title_filter` object
        - `withheld` integer, required
      - `interpreted_industries` object[]
        - `phrase` string, required
        - `how` 'exact' | 'alias' | 'none', required
        - `industries` string[], required
        - `coarse` 'niche not applied'
        - `candidates` string[]
    - object
      - `dry_run` true, required
      - `advisory` true, required
      - `evaluated_at` string, required
      - `plan` object, required
        - `verb` 'find_leads', required
        - `plan_version` 3, required
        - `input_version` string, required
        - `credits_estimate` string, required
        - `would_exceed` string[], required
        - `warnings` string[], required
        - `would` object, required
          - `limit` integer, required
          - `budget_applied` object, nullable, required
            - `limit_requested` integer, required
            - `limit_used` integer, required
          - `candidate_sources` integer, required
          - `maximum_credits` string, required
          - `budget_credits` string, nullable, required
  - `layrcake` object, required
    - `request_id` string, uuid, required
    - `credits_charged` string, required
    - `credits_available` string, required
    - `replayed` boolean
    - `route` object
      - `used` 'balanced' | 'cheapest' | 'broadest' | 'fastest', required
      - `source` 'request' | 'key' | 'guess' | 'default', required

## Other responses

- `4XX`: Caller, scope, confirmation, or credit error
- `5XX`: Provider or service error

---

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