People Preview

post

https://api.ai-ark.com/api/developer-portal/v1/people/preview

Run any People Search for a flat 1 credit per page and see who matches before spending per-result credits — the recommended first call of every list-building workflow. Validate your filters, check totalElements, inspect match quality, then send the exact same filter body to People Search or Export People with Email.

💳 Credit Usage: 1 credit per page — whether the page holds 25 or 100 results. A full page of 100 previews costs 1 credit; the same page on People Search costs 50 credits (0.5 × 100). Up to 100 results per page (default 25), max 10,000 results per search.

Each preview result contains:
  • The person's real AI Ark id — accepted directly by Export Single Person with Email, no full search needed
  • First name, masked last name (e.g. Ba**), title, headline, location, department/functions/seniority, position history with dates
  • The full company object: id, name, description, industry, headcount, revenue, HQ + office locations, keywords, NAICS/SIC
  • has_ availability flags (has_mobile, has_skills, has_educations, …) — see what data exists before paying to enrich; has_mobile: true means a Mobile Phone Finder call (5 credits) has something to find

Not included: unmasked last names, emails, phone numbers, and no trackId (email finding chains off People Search only).

Body: identical to People Search — all account, contact and lists filters plus page and size.

🔗 Related Endpoints:
  • People Search — full unmasked profiles + trackId for email finding (0.5/result)
  • Export People with Email — same filters, full data + BounceBan-verified emails (0.5/person + 0.5/found email)
  • Export Single Person with Email — cherry-pick preview ids and enrich row by row (1 credit per found email)

Rate limits: 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at [email protected] or via the in-app chat.

The header Content-Type: application/json must be included in the request.

Body Params

account

object

Match modes & combination logic
Every text filter accepts a mode that controls how your search terms are matched:

SMART (default) — Uses AI to find related concepts, not just the words you typed. Searching for creative director will also find people with titles like art director or head of creative. Use SMART to expand your reach when the exact wording varies.
WORD — Finds the exact phrase but allows extra words around it. creative director will match associate creative director or group creative director, but not art director. Use WORD when the phrase must appear literally.
STRICT — The most restrictive mode: only the exact characters you typed. creative director returns only creative director — no variations, prefixes, or suffixes. Use STRICT for precise, deduplicated targeting.

`any` vs `all`

any = OR logic — a record matches if it matches at least one of the values. Adding more values expands your results.
all = AND logic — a record matches only if it matches every value. Adding more values narrows your results.

Both accept include and exclude. A search cannot consist of exclude filters only.

Value limits

Maximum 300 values per include/exclude array.
Maximum 10,000 results per search (100 per page). To retrieve more than 10,000 — e.g. a search matching 38,000 people — use the Lists pagination pattern: pull the first 10,000, add their ids to a list via POST /v1/lists (free), re-run the same search with "lists": { "people_id": { "exclude": ["<list-id>"] } } — now only 28,000 remain — pull the next 10,000, append to the list, and repeat until you have all 38,000.

contact

object

Match modes & combination logic
Every text filter accepts a mode that controls how your search terms are matched:

SMART (default) — Uses AI to find related concepts, not just the words you typed. Searching for creative director will also find people with titles like art director or head of creative. Use SMART to expand your reach when the exact wording varies.
WORD — Finds the exact phrase but allows extra words around it. creative director will match associate creative director or group creative director, but not art director. Use WORD when the phrase must appear literally.
STRICT — The most restrictive mode: only the exact characters you typed. creative director returns only creative director — no variations, prefixes, or suffixes. Use STRICT for precise, deduplicated targeting.

`any` vs `all`

any = OR logic — a record matches if it matches at least one of the values. Adding more values expands your results.
all = AND logic — a record matches only if it matches every value. Adding more values narrows your results.

Both accept include and exclude. A search cannot consist of exclude filters only.

Value limits

Maximum 300 values per include/exclude array.
Maximum 10,000 results per search (100 per page). To retrieve more than 10,000 — e.g. a search matching 38,000 people — use the Lists pagination pattern: pull the first 10,000, add their ids to a list via POST /v1/lists (free), re-run the same search with "lists": { "people_id": { "exclude": ["<list-id>"] } } — now only 28,000 remain — pull the next 10,000, append to the list, and repeat until you have all 38,000.

lists

object

Reference exclusion lists created via POST /v1/lists (free): { "people_id": { "exclude": ["<list-id>"] } } on people endpoints, { "company_id": { "exclude": ["<list-id>"] } } on Company Search. Up to 10 lists per request, each holding up to 10,000 items. Standard uses: suppress already-contacted prospects, and paginate beyond the 10,000-result cap.

page

integer

required

Defaults to 0

Required on People Search and Company Search (default 0). Zero-based page number. Use with size to paginate. The full result set is capped at 10,000 records per search — see the Lists pagination pattern above to go deeper.

size

integer

required

0 to 100

Defaults to 10

Required on People Search and Company Search. Results per page: max 100. Default 10 on People Search / Company Search, 25 on Preview. On Export People with Email, size is the total export size, up to 10,000.

Response

any vs all

any vs all

200Preview page

`any` vs `all`

`any` vs `all`