---
title: "Preview pool matches"
method: POST
path: "/v1/pool/search"
tags: ["Pool"]
---

# Preview pool matches

`POST /v1/pool/search`

## Request

- Base URL: `https://api.automatedclientacquisition.com`
- URL: `https://api.automatedclientacquisition.com/v1/pool/search`
- Auth: HTTP bearer

Runs a filter against the shared lead pool and returns the **exact** match
count plus a small sample. Always run this before a build: the count it
returns is the same number the build gates on, so it tells you in advance
whether a build will be accepted and how many contacts it would create.

The filter is rejected outright if it is not selective enough to run
quickly. The pool is over 100M rows, so an unbounded filter is not a slow
query — it is one that must not start. A filter qualifies when it carries
at least one of: `v_category_in` (preferred — verified from the company's
own website), `industry_exact`, `industry_pattern`, `p_bucket`,
`sic_code_in`, a `keyword` of 2+ characters, or `state` together with
`employees_min`.

**Geography is US-state-level.** Use `state` (2-letter code) and `city`.
There is no `country` filter — the pool has no country column, so passing
one is rejected with a 400 rather than accepted and ignored.

A few filters the pool cannot honour (`founded_year_min`,
`founded_year_max`, `funding_stage_in`, `technology`) are dropped rather
than rejected. When that happens the response carries a `warnings` array
naming them, so a count is never mistaken for a narrower one than it is.

## Request body

- object
  - `filter` object, required: Pool filter. Must be selective enough to bound the scan.
  - `limit` integer: How many sample rows to return alongside the count.

## Response `200`

Exact count plus a preview sample.

- object
  - `success` boolean
  - `total` integer: Exact number of matches, not an estimate.
  - `data` object[]
  - `preview_limit` integer
  - `warnings` string[]: Present only when part of the filter was dropped. Names the filters the pool could not apply — `total` and `data` are NOT restricted by them.

## Other responses

- `400`: Malformed or invalid body. Do not retry — it will fail identically.
- `401`: Missing, invalid or revoked token.
- `429`: Over 120 requests in the current minute. `Retry-After` says how many seconds until the window resets; wait that long and continue.
- `500`: Something broke on our side. Safe to retry with backoff.

---

[API](https://skmtc.dev/automatedclientacquisition/apis/aca-api.md) · [All operations](https://skmtc.dev/automatedclientacquisition/apis/aca-api/llms.txt) · [OpenAPI document](https://skmtc.dev/automatedclientacquisition/apis/aca-api/revisions/8f3e3b141311?raw)