Saved searches and share links

These endpoints require the search key scope. Their MCP equivalents additionally require mcp. They use the shared rolling minute allowance and return X-RateLimit-* headers; a blocked request returns 429 and Retry-After. There is no daily request quota.

Creating definitions or links does not charge credits or save contacts/companies. Search requests remain unchanged. Completed exports use the configured save-by-default policy; explicitly pass saveContacts: false to opt out. Saving adds no separate surcharge; normal export/data charges still apply.

Save a successful searchCopy Anchor Link

POST /functions/v1/api-saved-searches

{ "name": "US founders", "search_id": "SEARCH_UUID_FROM_A_SUCCESSFUL_SEARCH" }

name is a nonblank string of 1–120 characters after trimming. search_id must be an owned, unexpired UUID from a successful People or Company search. The server preserves filters, exclusions, text, matching rules, structured locations and All/Saved/Net New scope. It returns saved_search_id, search_type, definition, url, created, and credits_charged: 0. The search appears in the UI's Saved Searches.

Retrying the same owner/name/definition returns the same saved search with created: false. A different definition under an existing name returns 409 saved_search_name_conflict; choose a new name. A saved definition does not expire with its source search session. Rerunning evaluates current data and relative dates, with normal search permissions and credits. It does not replay an immutable export snapshot.

Create a share linkCopy Anchor Link

POST /functions/v1/api-search-share-links

{ "saved_search_id": "SAVED_SEARCH_UUID", "expires_in_days": 7 }

Send exactly one of saved_search_id or search_id. expires_in_days is an optional JSON integer from 1 to 30; default 7. The response contains share_link_id, share_url, search_type, expires_at, requires_sign_in: true, and credits_charged: 0.

Each successful create makes an independent link. Retain the returned link and ID; a transport retry may create another link. Tokens are stored only as hashes and cannot be recovered by listing. Links contain filters, not exported rows, API keys, or the creator's saved-record membership. Rule-level numeric bounds are not reusable in the UI: send the range as a structured value in filters and run search again before saving or sharing. Private lists and private bulk-reference definitions are rejected with 422 search_definition_not_reusable.

Recipients must sign in. Opening the link loads and runs the criteria using the recipient's own permissions and normal search credits. Saved/Net New refers to the recipient's saved contacts or companies. Unsupported filters require review before execution; they are never silently removed from an automatically executed search. Sharing a link does not make a private saved-search record readable by another owner.

Revoke a linkCopy Anchor Link

DELETE /functions/v1/api-search-share-links

{ "share_link_id": "SHARE_LINK_UUID" }

Only the owner can revoke the link. Repeating revocation is safe. Expired or revoked links return 410 when opened. Revocation prevents future link resolution; it does not remove filters already loaded or copies a recipient has saved. It does not delete the owner's saved search.

MCP toolsCopy Anchor Link

Use create_saved_search, create_search_share_link, and revoke_search_share_link with the same JSON arguments as their REST equivalents. Read tools/list for current schemas. Link creation requires exactly one source ID even though both properties are optional individually in the schema.

ErrorsCopy Anchor Link