Create Saved Search

Store a set of filters to re-run later.

POSThttps://api.foxreach.io/api/v1/lead-finder/saved-searches

Requires an API key with the write scope.

Body Parameters#

namestringbodyrequired

Name, 1 to 200 characters.

kindstringbodyrequired

people or companies.

filtersobjectbody

The filters, with the keys returned by Get Filter Options.

Response#

Returns the saved search with a 201 status code.

dataobject

Show data

idstring

Saved search identifier.

namestring

Name.

kindstring

people or companies.

filtersobject

The stored filter object.

lastRunAtstring

ISO 8601 timestamp of the last run, or null.

lastTotalinteger

Result count from the last run, or null.

alertEnabledboolean

Whether alerts are on for this search.

createdAtstring

ISO 8601 timestamp.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`404`	`Lead Finder is not enabled` while Lead Finder is switched off on this environment
`503`	`Lead Finder is not configured` when it is enabled but has no data provider key
`422`	`name` is empty or `kind` is not `people` or `companies`

Rate Limit#

120 requests per minute, shared by every write call in your workspace. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (write).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Request

cURL

curl -X POST "https://api.foxreach.io/api/v1/lead-finder/saved-searches" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CTOs in Berlin", "kind": "people", "filters": {"jobTitles": ["CTO"]}}'

Python SDK

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
search = client.lead_finder.create_saved_search("CTOs in Berlin", "people", filters={"job_titles": ["CTO"]})

TypeScript SDK

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const search = await client.leadFinder.createSavedSearch({ name: "CTOs in Berlin", kind: "people", filters: { jobTitles: ["CTO"] } });

Response

JSON

{
  "data": {"id": "ss_abc123", "name": "CTOs in Berlin", "kind": "people", "filters": {"jobTitles": ["CTO"]}, "lastRunAt": null, "lastTotal": null, "alertEnabled": false, "createdAt": "2026-11-04T10:00:00+00:00"}
}

Was this page helpful?

View as MarkdownLast updated November 4, 2026