For humans: This page contains the complete AI Ark API documentation in a single, self-contained document. Copy everything (👉) and paste it into your AI agent (Claude, ChatGPT, Cursor, Clay AI, n8n, Make, etc.) as context or a system prompt. Your agent will then know every endpoint, every credit cost, every filter's exact JSON shape, and the correct workflow to build outbound lists.

Alternatives for agents that can fetch URLs or use tools:

• 📄 Machine-readable index: https://docs.ai-ark.com/llms.txt (append .md to any docs page URL for its markdown version)
• 🔌 MCP server (recommended for Claude Desktop, Cursor, Windsurf): https://api.ai-ark.com/v1/mcp?token={YOUR-API-KEY}

AI Ark API — FULL CONTEXT FOR AI AGENTS

You are working with the AI Ark API, a B2B contact & company database (400M+ person profiles, 70M+ company profiles) used to build outbound lead lists with verified emails and mobile numbers.

1. Basics

• Base URL: https://api.ai-ark.com/api/developer-portal
• Authentication: every request needs the header X-TOKEN: {API_KEY}. Missing/invalid token → 401 from the gateway.
• Content type: every request needs the header Content-Type: application/json.
• All search/enrichment endpoints are POST with a JSON body. Status/result/history endpoints are GET; webhook re-sends are PATCH.
• Rate limits: 5 requests/second per token (default). Customers using >450,000 credits/month can request custom limits via [email protected] or the in-app chat.
• Check balance any time (free): GET /v1/payments/credits → { "total": 100 }

2. Credit Pricing (memorize this before calling anything)

Cost math examples:

• Preview, size: 100, any number of results → 1 credit (the same 100 results on People Search would cost 50).
• People Search, size: 25, 25 results → 12.5 credits.
• Find Emails on those 25 people, 18 valid emails found → 18 × 1 = 18 credits (the 7 without an email cost nothing).
• Export People with Email, size: 1000, 700 emails found → 1,000 × 0.5 + 700 × 0.5 = 850 credits.
• Enriching 1 person via Export Single: 1 credit (or 0 if no email found).
• Company Search, size: 100, 100 matches → 10 credits.

Automatic refunds (async jobs — Export People, Find Emails): submissions are auto-refunded, no support ticket needed. Check GET .../submissions → fullyRefunded: true + refundReason:

3. Email Verification (applies everywhere emails are returned)

✅ Every email returned by any AI Ark endpoint (SMTP and CATCH_ALL) is verified in real time by BounceBan at the moment of the request. All returned emails are safe to send — no re-verification with another tool is needed. Email charges only ever apply to emails that passed this real-time validation.

Email output object (identical shape everywhere emails appear — Export results, Email Finder results, Export Single, webhooks):

{
  "address": "[email protected]",        // only present when found: true
  "found": true,                          // whether an email was found
  "status": "VALID",                      // "VALID" | "INVALID"
  "subStatus": "EMPTY",                   // "EMPTY" | "MAILBOX_NOT_FOUND" | "FAILED_SYNTAX_CHECK"
  "domainType": "SMTP",                   // "SMTP" | "CATCH_ALL" | "UNKNOWN" (UNKNOWN when not found)
  "date": "2026-03-06T14:41:53.000474",   // timestamp of the real-time verification
  "free": false,                          // free-mail provider domain
  "generic": false,                       // role address like info@
  "mx": {
    "found": true,
    "record": "mx1.example.com",          // string | null
    "google": false,
    "provider": "g-suite"                 // "microsoft" | "g-suite" | "mimecast" | "barracuda" | "proofpoint" | "cisco ironport" | "other" | null
  }
}

Use generic and domainType to segment your sending strategy. In async Export results, the per-person wrapper is "email": { "state": "PROCESSING" | "DONE", "output": [ ...email objects ] }.

4. Which endpoint do I use? (decision guide)

5. Standard Workflows (recipes)

Recipe 0 — Always preview first (1 credit/page)

POST /v1/people/preview with your ICP filters. Check totalElements and sample quality; refine until right. The body is identical to People Search — when satisfied, send the same body to Recipe A or B.

Preview results include:

• each person's real id (accepted directly by Export Single Person — cherry-pick and enrich without a full search),
• first name + masked last name (Ba***e), 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 → a Mobile Phone Finder call (5 credits) has something to find.

Preview returns no emails, no phones, no trackId (trackId: null — email finding chains off People Search only).

Recipe A — Two-step list building (max control; pay only for found emails)

1. POST /v1/people with your ICP filters (page, size ≤ 100). Cost: 0.5 × results. Response contains the people, totalElements, and a trackId.
2. POST /v1/people/email-finder with that trackId and a webhook URL. ⚠️ Each trackId works once and expires 6 hours after the search response — submit promptly.
3. Poll GET /v1/people/email-finder/{trackId}/statistics until state: DONE (or wait for the webhook). Results are readable while running: unfinished items show state: PROCESSING.
4. Fetch results: GET /v1/people/email-finder/{trackId}/inquiries?page=0&size=100.

Recipe B — One-step bulk export (up to 10,000 people)

1. POST /v1/people/export with the same filters as People Search, size up to 10000 (here size = total export size, not page size), plus a webhook URL. Response returns a trackId and state: PENDING.
2. Poll GET /v1/people/export/{trackId}/statistics or wait for the webhook (auto-retried; re-trigger any time with PATCH /v1/people/export/{trackId}/notify).
3. Fetch results: GET /v1/people/export/{trackId}/inquiries?page=0&size=100 — full person + company + verified email. Returns 409 while still in progress — poll statistics until state: DONE first.

Recipe C — Row-by-row enrichment (CRM / Clay / spreadsheets)

• For each row, call POST /v1/people/export/single (v1) or POST /v2/people/export/single (Clay) with { "id": "..." } or { "url": "https://linkedin.com/in/..." }.
• Add POST /v1/people/mobile-phone-finder (or v2) if you also need mobile numbers (5 credits per found phone).

Recipe D — Account-based (ABM)

1. POST /v1/companies to build the account list (0.1/result). Optionally seed with lookalikeDomains (max 5 domains/LinkedIn URLs) to find similar companies, and/or use account.employee to find companies that even have the role you sell to.
2. Take the returned company id values and use them in People Search under contact.company.latest / .current to find people at exactly those companies.
3. Continue with Recipe A or B for emails.

Suppression & deep pagination (Lists)

• POST /v1/lists with { "type": "people_id", "values": [ ...ids ] } → returns a list id.
• Reference it in searches: "lists": { "people_id": { "exclude": ["<list-id>"] } } (people endpoints) / "lists": { "company_id": { "exclude": ["<list-id>"] } } (Company Search). Max 10 lists per request.
• Retrieve more than 10,000 records: totalElements shows the full match count, but a single search pages through at most 10,000 records (page × size). For a 38,000-match search: pull the first 10,000 → add their ids to a list → re-run the search excluding that list (28,000 remain) → pull the next 10,000 → append → repeat until done.
• Lists are free, reusable and updatable: send the same id with mode: "APPEND" (default, merges values) or mode: "REPLACE" (rewrites the list with a fresh set). Max 10,000 values per list, 50 lists per day, lists expire after 24 hours — recreate them daily.

6. Endpoint Reference

6.0 People Preview — POST /v1/people/preview

Purpose: run any People Search cheaply to validate filters and volume before committing credits. The recommended first call of every list-building workflow.
Credits: 1 per page, flat — whether the page holds 25 or 100 results.
Body: identical to People Search — account, contact, lists, plus required page (zero-based) and size (1–100, default 25). totalElements is the full match count; up to 10,000 records retrievable via pagination, like People Search.
Response: person id (real, accepted by Export Single Person), first name + masked last name (Ba***e), title, headline, location, department/seniority, position history, full company object, has_* availability flags, last_updated. No emails, no phones, trackId: null.
Related: People Search (full details + trackId), Export People with Email (same body, bulk emails), Export Single Person (enrich picked ids).

6.1 People Search — POST /v1/people

Purpose: search 400M+ person profiles by contact and/or account (company) filters. Returns full person + company data. Does NOT return emails or phones — chain with Find Emails by Track ID, Export Single Person, or Mobile Phone Finder.
Credits: 0.5 per result. You only pay for results actually returned.
Body: { "account": {...}, "contact": {...}, "lists": {...}, "page": 0, "size": 25 } — page and size are required (page zero-based, size 1–100, default 10). Full filter reference: Section 7.
Response: content[] (people — see the response skeleton in Section 9), Spring-style pagination (totalElements, totalPages, size, number, pageable, first, last, empty, numberOfElements), and trackId (single-use, 6h expiry — feed it to /v1/people/email-finder).
Errors: 404 data not found (no matches — treat as empty, not failure); 501 unsupported filter (e.g. socialMediaFollower on a platform other than LinkedIn → SOCIAL_MEDIA_FOLLOWER_PLATFORM_NOT_SUPPORTED).

curl -X POST 'https://api.ai-ark.com/api/developer-portal/v1/people' \
  -H 'X-TOKEN: {API_KEY}' -H 'Content-Type: application/json' \
  -d '{
    "contact": {
      "experience": { "latest": { "title": { "any": { "include": { "mode": "SMART", "content": ["marketing manager"] } } } } },
      "seniority": { "any": { "include": ["manager", "director"] } },
      "location": { "any": { "include": ["Germany"] } }
    },
    "account": {
      "industries": { "any": { "include": { "mode": "WORD", "content": ["software development"] } } },
      "employeeSize": { "type": "RANGE", "range": [ { "start": 50, "end": 200 } ] }
    },
    "page": 0, "size": 25
  }'

6.2 Company Search — POST /v1/companies

Purpose: search 70M+ company profiles by account filters — ideal for ABM account lists. Also Lookalike Search via lookalikeDomains.
Credits: 0.1 per result (lookalike included).
Body: { "lookalikeDomains": [...], "account": {...}, "lists": {...}, "page": 0, "size": 25 } — page/size required, size 1–100.

Lookalike Search: up to 5 company domains or LinkedIn company URLs in lookalikeDomains. Combine with account filters to constrain the lookalikes:

{ "lookalikeDomains": ["raisin.com", "https://www.linkedin.com/company/n26"],
  "account": { "location": { "any": { "include": ["Germany"] } } }, "page": 0, "size": 25 }

Company-Search-only filter — account.employee (Job Role): find companies by the people they employ. Three combinable sub-fields:

• employee.title — job titles with match modes (SMART/WORD/STRICT) and any/all + include/exclude,
• employee.seniority — plain arrays, same 12 values as contact.seniority,
• employee.departmentAndFunction — plain arrays, same 592 values as contact.departmentAndFunction.

"account": { "employee": {
  "title": { "any": { "exclude": { "mode": "SMART", "content": ["manager"] } } },
  "seniority": { "any": { "include": ["c_suite", "vp"] } },
  "departmentAndFunction": { "any": { "include": ["software_development"] } }
} }

→ companies that have C-suite/VP software-development people (typical use: "which accounts even have a Head of Data?"). Not available in People Search (use contact.* there).

Response: companies with id (UUID) — use these IDs in People Search contact.company (latest/current/previous) to target employees of exactly these companies. Resolve any domain or LinkedIn company URL to its ID this way (works for universities too — needed for the education.school filter).
Related: People Search (find people at these companies), Lists (company_id exclusions).

6.3 Find Emails by Track ID — POST /v1/people/email-finder

Purpose: trigger email finding for the result set of a previous People Search, using its trackId. Step 2 of the two-step flow.
Credits: 1 per found valid email (0.5 people data + 0.5 real-time BounceBan-verified email) — 0 for people where no valid email is found. Unlike Export People with Email, you only pay for delivered emails here.
⚠️ Critical: each trackId can be used exactly once and expires 6 hours after the People Search response. A used/expired id returns 404 — run the search again for a fresh one. Plan: search → immediately submit email finding.
Body: { "trackId": "<uuid>", "webhook": "https://..." } — both required. The webhook must be an HTTPS URL; delivery is auto-retried, and you can re-send any time via the notify endpoint.
Response: { trackId, statistics: { total, found }, state: "PENDING", webhook: { state, retry }, description }.
Concurrency (per token, per service): max 500 in-flight submissions (400 too many pending requests — drain below the cap, then retry); 10 jobs processed in parallel. Auto-refund of undelivered charged jobs after up to 10h.

Sub-endpoints (all free):

• GET /v1/people/email-finder/{trackId}/statistics — poll state + statistics (total, found) until DONE. 403 if the submission was STUCK_*-refunded (resubmit); 404 if the trackId is unknown/expired; 200 with zeroed statistics if refunded for SEARCH_NO_RESULTS/NO_EMAILS_FOUND.
• GET /v1/people/email-finder/{trackId}/inquiries?page=0&size=100 — paginated results (page zero-based, size 1–100, default 10). Readable while running — unfinished items show state: PROCESSING. Each item: refId, state, input (firstname, lastname, domain), output (array of email objects — Section 3). 403 STUCK_*-refunded / 404 unknown; refunded-no-result → 200 with an empty page.
• GET /v1/people/email-finder/submissions?state=&fullyRefunded=&page=&size=&sort= — your own submission history (auto-scoped to your token). Item fields: trackId, service (EMAIL_FINDER), requestSize, state (PENDING|SETTLED), fullyRefunded, refundReason (null unless fully refunded), attempts, created, submittedDate, doneDate, settledAt. Filters: state (PENDING/SETTLED), fullyRefunded (bool), sort e.g. created,desc (repeatable), page ≥0, size 1–100 (default 25).
• PATCH /v1/people/email-finder/{trackId}/notify — re-send the completion webhook (body: { "webhook": "https://..." }, can be a different URL). See Section 8 for the delivery-result semantics.

Related: People Search (produces the trackId), Export People with Email (skip the two-step flow).

6.4 Export People with Email — POST /v1/people/export

Purpose: one call = People Search + email finding, asynchronously, up to 10,000 people per export. The workhorse for bulk outbound list building.
Credits: 0.5 per exported person (charged for everyone, found or not) + 0.5 per found valid email. Note: differs from Find Emails by Track ID, which charges only for found emails.
Body: same account / contact / lists filters as People Search + required page, size (1–10000 — here size is the total export size) and webhook (HTTPS URL). size > 10,000 → 400 pagination limit exceeded.
Response: { trackId, statistics, state: "PENDING", webhook: { state, retry }, description }. Job completion is POSTed to your webhook (Section 8).
Concurrency & refunds: same as Find Emails by Track ID (500 in flight per token, 10 parallel, ≤10h auto-refund).

Sub-endpoints (all free):

• GET /v1/people/export/{trackId}/statistics — poll state + statistics until DONE. Same 403/404/zeroed-200 semantics as Email Finder statistics.
• GET /v1/people/export/{trackId}/inquiries?page=0&size=100 — paginated full person + company + email objects (Section 9 skeleton + email block). Returns 409 track id in progress while the export runs — poll statistics until state: DONE first. Individual items may still show email.state: PROCESSING with an empty email.output. 403 STUCK_*-refunded / 404 unknown; refunded-no-result → 200 empty page.
• GET /v1/people/export/submissions?state=&fullyRefunded=&page=&size=&sort= — same shape as Email Finder submissions; service is PEOPLE_EXPORT.
• PATCH /v1/people/export/{trackId}/notify — re-send the completion webhook (body: { "webhook": "https://..." }).

Related: People Search + Find Emails by Track ID (the equivalent two-step flow with a preview step), Export Single Person (row-by-row instead of bulk).

6.5 Export Single Person with Email — POST /v1/people/export/single (v1) & POST /v2/people/export/single (v2)

Purpose: real-time enrichment of ONE person — full profile + verified email. Made for row-by-row enrichment (CRM, spreadsheets, Clay).
Credits: 1 if a valid email is found (0.5 full-profile enrichment + 0.5 real-time BounceBan-validated email), 0 if no valid email is found.
Body: { "id": "<ai-ark person id>" } or { "url": "<linkedin profile url>" } — at least one required; id is looked up first. Both empty → 400 id and url cannot be both empty. The id can come from People Search or Preview results.
Response (200): the full person object (Section 9) including the email block (state: "DONE", output: email objects) and last_updated.
v1 vs v2: identical behavior, except not-found: v1 returns 404 (e.g. no email found); v2 always returns HTTP 200 with envelope { status, error, data } (data: null when not found / no email) — recommended inside Clay, which expects 200s. v2 adds the X-Credit header (e.g. -1.0) on charged responses. Real errors (400/402/500) and gateway errors (401/429) keep their status on both.
Related: People Search / Preview (source of person ids), Mobile Phone Finder (phones for the same person), Reverse People Lookup (start from an email instead).

6.6 Mobile Phone Finder — POST /v1/people/mobile-phone-finder (v1) & POST /v2/people/mobile-phone-finder (v2)

Purpose: find a person's mobile phone number — add direct dials to your lists.
Credits: 5 per result, charged only when a phone number is found. Nothing found → v1 returns 404 and no credits are charged.
Body — two search modes: { "linkedin": "<full profile url>" } or { "domain": "acme.com", "name": "Jane Doe" } — domain and name must be provided together (400 both domain and name are required otherwise; also 400 invalid domain provided / 400 invalid linkedin url provided).
Response (200): { "id": "<person id>", "linkedin": "<url>", "data": [ [ "+13152468945", ... ] ] } — data is an array of arrays; the inner array can hold multiple numbers ordered by confidence, E.164 format.
v1 vs v2: identical, except not-found: v1 → 404; v2 → HTTP 200 envelope with data: null (recommended for Clay) + X-Credit header (e.g. -5.0) on charged responses.
Related: Export Single Person (email for the same person), People Search / Preview (has_mobile flag tells you whether a lookup has something to find).

6.7 Reverse People Lookup — POST /v1/people/reverse-lookup

Purpose: identify a person from an email address. If the email exists in AI Ark's database, returns the full profile (like a People Search result — profile, company, education, positions, department — but excluding valid email & mobile). Useful for enriching inbound leads, newsletter signups, form fills, and CRM records where you only have an email.
Credits: 0.5 per request.
Body: { "search": "[email protected]" } — search (the email address) is the only, required field.
Errors: 404 = no profile with this email in the database (treat as "no result").
Related: Export Single Person (get a verified email), Mobile Phone Finder, Personality Analysis (personalize outreach to the identified person).

6.8 Personality Analysis — POST /v1/people/analysis

Purpose: analyzes a profile's skills, headline and summary and returns a personality profile with ready-to-apply outreach guidance. Pipe the output into your email-generation prompts to personalize at scale.
Credits: 4 per request.
Body: { "url": "https://www.linkedin.com/in/..." } (required — full LinkedIn profile URL).
Response (200): { model, source: { refId, headline, skills, summary }, score, selling: {...}, hiring: {...}, assessments: {...}, status: "SUCCESS", success: true } where:

• selling / hiring each contain: email (field-by-field advice objects — subject, salutation, greeting, tone, emailLength, bulletPoints, gif, messaging, closingLine, complimentaryClose — each with definition/advice/example), communication (types, descriptions, adjectives, whatToSay[], whatToAvoid[], plus a ready subject/body template on hiring), and keyTraits (risk, abilityToSayNo, speed, decisionDrivers).
• assessments: archetype label, ocean (openness, conscientiousness, extraversion, agreeableness, emotionalStability — each {score, level}), disc (dominance, influence, steadiness, calculativeness — each {score, level}).
  Errors: 404 profile not found.
  Related: People Search / Reverse Lookup (find the person + LinkedIn URL), Export Single Person (their email).

6.9 Create or Update a List — POST /v1/lists

Purpose: reusable exclusion lists of people or companies, referenced from People Search / Preview / Company Search / Export People via the lists filter — for suppressing already-contacted prospects, excluded accounts, and deep pagination past 10,000 results.
Credits: free — lists never cost credits.
Body: { "id": "<optional uuid>", "type": "people_id" | "company_id", "values": [ ...up to 10000 ], "mode": "APPEND" | "REPLACE" } — values required; type required when creating.
Behavior: no id → new list. Existing id → update: APPEND (default) merges values, REPLACE rewrites the list with a completely fresh set — the same list id stays valid and reusable across many searches. Unknown id → a new list is created for you.
Response (200): { id, workspace, type, values, created } (created = epoch milliseconds).
Limits: 50 lists/day, 10,000 values/list, lists expire after 24 hours (recreate daily). Violations → 400 (e.g. terms_lookup_list_values_limit_exceeded 10000, missing type on insert, daily quota exceeded).
Usage in searches: "lists": { "people_id": { "exclude": ["<list-id>", ...] } } on people endpoints, "lists": { "company_id": { "exclude": [...] } } on Company Search — up to 10 lists per request.

6.10 Fetch Your Credits — GET /v1/payments/credits

Purpose: remaining balance. Credits: free. Response: { "total": 100 }.
Agent tip: check before large jobs; e.g. an Export of 1,000 people can cost up to 1,000 credits (0.5 + 0.5 each).

7. Complete Filter Reference (People Search, Preview, Export People; account.* also in Company Search)

Filters live under account (company attributes) and contact (person attributes).

7.1 Match modes, any/all, limits

Most filters use the shape { "any": { "include": [...], "exclude": [...] }, "all": { "include": [...], "exclude": [...] } }:

• any = OR — matches if at least one value matches. More values = broader results.
• all = AND — matches only if every value matches. More values = narrower results.
• Both accept include and exclude. A search cannot consist of exclude filters only.

Text filters wrap values with a match mode: { "mode": "SMART" | "WORD" | "STRICT", "content": ["..."] }:

• SMART (default) — AI-related concepts: creative director also finds art director, head of creative. Use to expand reach when wording varies.
• WORD — exact phrase, extra words allowed: matches associate creative director, not art director.
• STRICT — exact characters only: matches creative director and nothing else.

Plain-array filters (no match mode): domain, linkedin, socialMediaLink, phoneNumber, location, socialMedia, type, naics, technology (legacy), seniority, departmentAndFunction, profileBadge, company IDs, education.school IDs, account.language.

Limits: max 300 values per include/exclude array; a search pages through at most 10,000 records (totalElements itself is uncapped — use the Lists pattern in Section 5 to retrieve more).

Range filters: { "type": "RANGE", "range": [ { "start": X, "end": Y }, ... ] } — range is an array of bands, OR'd together; add multiple bands to expand results. Omit end for open-ended "X+", omit start for "less than Y". (foundedYear takes a single range object, and foundedYear/revenue additionally accept type: "ALL" / "NONE" — see below.)

7.2 account filters (company attributes)

funding — all sub-fields optional, combinable:

"funding": {
  "type": ["SEED", "SERIES_A"],
  "totalAmount": { "start": 1000000, "end": 20000000 },
  "lastAmount":  { "start": 500000,  "end": 2000000 },
  "duration":    { "start": "1620847800000", "end": "1747168200000" }
}

• type — round types raised (any match), 30 values: PRE_SEED, SEED, SERIES_A…SERIES_J, VENTURE_ROUND, ANGEL, PRIVATE_EQUITY, DEBT_FINANCING, CONVERTIBLE_NOTE, GRANT, CORPORATE_ROUND, EQUITY_CROWDFUNDING, PRODUCT_CROWDFUNDING, SECONDARY_MARKET, POST_IPO_EQUITY, POST_IPO_DEBT, POST_IPO_SECONDARY, NON_EQUITY_ASSISTANCE, INITIAL_COIN_OFFERING, UNDISCLOSED, SERIES_UNKNOWN, FUNDING_ROUND.
• totalAmount — total raised across all rounds, USD range.
• lastAmount — size of the most recent round, USD range.
• duration — date of the most recent round as an epoch-milliseconds string range — target companies that raised recently, when budgets are fresh.

metric — department-level headcount metrics. function takes one of 27 department values: sales, marketing, engineering, finance, human_resources, information_technology, operations, business_development, customer_success_and_support, product_management, accounting, legal, consulting, education, research, purchasing, real_estate, media_and_communication, quality_assurance, arts_and_design, healthcare_services, entrepreneurship, community_and_social_services, administrative, military_and_protective_services, program_and_project_management, support.

"metric": {
  "employee": [ { "function": ["engineering"], "start": 10, "end": 50 } ],
  "growth":   [ { "function": ["marketing"], "start": 10, "end": 15, "timeFrame": "SIX" } ]
}

• employee — current absolute headcount in the department(s), within start–end.
• growth — percentage headcount change over a look-back window; timeFrame in months: ONE, THREE, SIX, TWELVE, TWENTY_FOUR. Department growth is one of the strongest intent signals — a growing sales team buys sales tooling.

keyword (account) — free-text across company fields; content holds the terms, sources says where to search, each with its own mode:

"keyword": { "any": { "include": {
  "sources": [ { "mode": "SMART", "source": "DESCRIPTION" }, { "mode": "SMART", "source": "SEO" } ],
  "content": ["carbon accounting"]
} } }

7.3 contact filters (person attributes)

contact.experience — job title + tenure, three scopes:

• latest — the person's primary active role only (classic "current job title" search).
• current — all active roles: a person holding 3 simultaneous positions matches if any fits — catches advisors, board members, multi-role founders.
• previous — past roles only: someone who was a Director and is now a VP matches previous: director.

Each scope: title (match modes, any/all) and duration (not on previous-title-only searches; duration keys are named after the scope):

"experience": {
  "latest": {
    "title": { "any": { "include": { "mode": "SMART", "content": ["creative director"] } } },
    "duration": {
      "latestCompany": { "min": { "year": 1, "month": 0 }, "max": { "year": 4, "month": 0 } },
      "latestJob":     { "min": { "year": 0, "month": 0 }, "max": { "year": 0, "month": 6 } },
      "total":         { "min": { "year": 3, "month": 0 }, "max": { "year": 8, "month": 0 } }
    }
  }
}

• latestCompany / currentCompany / previousCompany — time at that employer.
• latestJob / currentJob / previousJob — time in that specific role. latestJob.max: {year: 0, month: 6} = new in role, a strong outreach trigger.
• total — total career experience.

contact.education:

"education": {
  "school":       { "any": { "include": ["49c9a269-b00e-28ac-eeb6-f74d3fd32a00"] } },
  "degree":       { "any": { "include": { "mode": "SMART", "content": ["mba"] } } },
  "fieldOfStudy": { "any": { "include": { "mode": "SMART", "content": ["computer science"] } } },
  "date":         { "start": 2011, "end": 2015, "present": false }
}

• school — AI Ark company IDs: universities are companies; resolve harvard.edu or the school's LinkedIn URL via Company Search to get the ID.
• date — the study period (years): start/end as stated on the profile, present: true = still studying (current students); use for alumni-cohort targeting.

contact.socialMediaFollower — LinkedIn only (facebook/twitter/instagram → 501 SOCIAL_MEDIA_FOLLOWER_PLATFORM_NOT_SUPPORTED). followers and connections independently optional; each type: "RANGE" with an OR'd range array; omit end for open-ended ("30K+"), omit start for "less than". Counts are absolute integers (1.5K = 1500). Empty object = no-op.

"socialMediaFollower": { "linkedin": {
  "followers":   { "type": "RANGE", "range": [ { "start": 5000, "end": 10000 }, { "start": 30000 } ] },
  "connections": { "type": "RANGE", "range": [ { "start": 1500, "end": 4200 } ] }
} }

In responses the counts appear under statistics.network.followers_count / .connections_count (either may be absent when unknown — absence ≠ zero).

7.4 lists filter

{ "people_id": { "exclude": ["<list-id>", ...] } } on people endpoints / { "company_id": { "exclude": [...] } } on Company Search. Up to 10 lists per request, each holding up to 10,000 items. Uses: suppress contacted prospects; paginate beyond the 10,000-result cap (Section 5).

8. Accepted Enum Values (quick reference)

• Seniority (12): founder, owner, partner, c_suite, vp, director, head, manager, senior, mid-level, entry, intern
• Profile badge (6): VERIFIED, PREMIUM, OPEN_TO_WORK, INFLUENCER, CREATOR, HIRING
• Company type (8): PRIVATELY_HELD, SELF_OWNED, SELF_EMPLOYED, PARTNERSHIP, PUBLIC_COMPANY, NON_PROFIT, EDUCATIONAL, GOVERNMENT_AGENCY
• Match modes: SMART, WORD, STRICT
• Social media: FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN
• Contact keyword sources (15, max 5/request): HEADLINE, SUMMARY, SKILL, CERTIFICATION, COURSE, PROJECTS, PUBLICATION, PATENT, AWARD, ORGANIZATION, VOLUNTEERING, TEST_SCORE, WORK_HISTORY_DESCRIPTION, EDUCATION_DESCRIPTION, LANGUAGE_SKILL
• Account keyword sources (5, all usable at once): NAME, KEYWORD, SEO, DESCRIPTION, INDUSTRY
• Headcount-growth timeframes (months): ONE, THREE, SIX, TWELVE, TWENTY_FOUR
• Metric department functions (27): listed in Section 7.2 under metric
• Funding round types (30): listed in Section 7.2 under funding
• Languages (48): english, spanish, french, portuguese, german, dutch, italian, chinese, turkish, polish, russian, swedish, arabic, indonesian, danish, czech, norwegian, japanese, korean, romanian, ukrainian, thai, hindi, malay, tagalog, vietnamese, finnish, persian, greek, hungarian, bengali, marathi, telugu, panjabi, serbian, slovak, croatian, lithuanian, latvian, albanian, icelandic, armenian, bosnian, tamil, javanese, malayalam, kannada, burmese. Note: contact.language values are wrapped with a match mode; account.language takes plain arrays.
• Industries: 919 values, e.g. software development, hospitals and health care — full list: https://ai-ark.com/static/industries.csv?v=1
• Technologies (account.technologies): 16,000+ values, e.g. salesforce, hubspot — full list: https://ai-ark.com/static/technologies.csv?v=1
• Departments & functions (contact.departmentAndFunction): 592 values, e.g. software_development, demand_generation — full list: https://ai-ark.com/static/departments-and-functions.csv?v=2
• Locations: free-form and forgiving — countries (Germany), states (California), plain city names (seattle, hamburg), metro areas (greater seattle area), regions (Europe) all work; exact values are not required. Same vocabulary for contact.location and account.location.

9. Response Object Skeletons (for writing parsers)

Person object (People Search / Export results / Export Single / Reverse Lookup; Preview returns a reduced + masked variant plus has_* flags):

id                      — AI Ark person UUID (use in Export Single, Lists)
identifier              — LinkedIn slug
profile { first_name, last_name, full_name, headline, title, picture.source, background.source, birth_date, summary }
link { linkedin, twitter, github, facebook }
location { country, state, city, position, default, short }
languages { primary_locale {country, language}, supported_locales[], profile_languages }
industry                — person's industry label
educations[] { school {id, name, logo, url}, degree_name, field_of_study, grade, date {start, end} }
certifications[] { name, authority, url, license_number, display_source, company, date }
organizations[] { name, position, date }
volunteer_experiences[] { role, company, cause, description, date }
position_groups[] { company {id, name, logo, url, employees {start, end}}, date {start, end},
                    profile_positions[] { company, description, title, employment_type, location, date } }
skills[]                — strings
member_badges { creator, hiring, open_to_work, premium, verified, influencer }
company { id, summary { name, legal_name, description, overview, seo, founded_year, type, industry,
                        staff { total, range {start, end} }, logo.source },
          link { website, domain, domain_ltd, linkedin, facebook, twitter, crunchbase },
          financial { revenue.annual {start, end, amount}, funding {...rounds}, ipo {...},
                      exit {...}, acquisition {...}, investment {...}, diversity_investment {...},
                      aberdeen.it_spend },
          location { headquarter {continent, country, state, city, street, postal_code, raw_address, position {lat,lng}},
                     locations[] },
          technologies[] { name, category }, industries[], keywords[], hashtags[], languages[],
          sub_organizations[], sic[], naics[], last_updated }
department { departments[], sub_departments[], functions[], seniority }
statistics { network { followers_count, connections_count } }     — may be absent
email { state: "PROCESSING"|"DONE", output: [ ...email objects, see Section 3 ] }   — export endpoints only
last_updated            — date of last data refresh

Search/results pagination envelope (Spring style, on all paginated responses): content[], totalElements, totalPages, size, number, numberOfElements, pageable { pageNumber, pageSize, offset, paged, unpaged, sort }, sort, first, last, empty — plus trackId on People Search and on trackId-scoped results.

10. Webhooks (async jobs: Find Emails by Track ID & Export People)

How they work:

1. You call the endpoint with a webhook field (HTTPS callback URL).
2. The API responds immediately with a trackId and state: "PENDING".
3. On completion, a POST with Content-Type: application/json is sent to your URL with the full results.

Webhook payload (both jobs):

• Top level: trackId, state: "DONE", description, statistics { total, found }, data[].
• Find Emails data[] items: { refId, state: "DONE", input { firstname, lastname, domain }, output: [ ...email objects ] }.
• Export People data[] items: the full person object (Section 9) including the email { state, output } block.
• If the job was fully refunded with no deliverable result (SEARCH_NO_RESULTS / NO_EMAILS_FOUND), the webhook carries the full-refund payload.

Delivery & retries: delivery is retried automatically. A webhook may occasionally be delivered more than once — deduplicate by trackId. Respond quickly with 200 OK and process asynchronously on your side.

Re-send — PATCH .../{trackId}/notify (free; body { "webhook": "https://..." }, may be a different URL). Returns a structured WebhookDeliveryResult — inspect the fields, not the HTTP status:

• delivered: true — your endpoint accepted (2xx). webhook.status echoes your status, webhook.body your response body.
• delivered: false, fault: "WEBHOOK" — your endpoint failed (non-2xx or unreachable); message explains; fix your endpoint, call notify again. Still HTTP 200.
• delivered: false, fault: "SERVICE" — failure on AI Ark's side (webhook: null); retry later / contact support. Still HTTP 200.
• HTTP 403 — the submission was auto-refunded for non-delivery (STUCK_HARD_REFUND 4031013 / STUCK_SOFT_REFUND 4031014) and is not retrievable — resubmit the job.

11. Job States, Errors & Rate Limits

Async job states: PENDING → processing → DONE. Submission history uses PENDING → SETTLED. Per-item email.state may be PROCESSING while running.

HTTP errors (all endpoints):

Rate limits: 5 requests/second per token (default); >450,000 credits/month → custom limits via [email protected]. Async submissions: max 500 in flight per token per service, 10 processed in parallel.

12. Rules of Thumb for Agents

1. Preview first. Validate any new filter set with POST /v1/people/preview (1 credit/page) before spending per-result credits; use totalElements to size the job and has_* flags to decide what's worth enriching.
2. Always estimate cost before big calls (results × per-result price) and check GET /v1/payments/credits first for jobs over ~100 credits.
3. Never re-verify AI Ark emails — they are BounceBan-verified in real time and safe to send. Segment sending by domainType (SMTP vs CATCH_ALL) and generic instead.
4. Use the trackId immediately — single use, 6-hour expiry. Search → submit email finding in the same workflow.
5. Prefer Export People with Email for bulk (one call, ≤10,000 people); prefer Export Single v2 and Mobile Finder v2 inside Clay (they return HTTP 200 envelopes and an X-Credit header).
6. Deduplicate with Lists (free): maintain a people_id exclusion list of everyone already contacted; APPEND to grow, REPLACE to rewrite; rebuild daily (24h expiry). Lists are also the pattern for paginating past 10,000 results.
7. Company targeting: Company Search → take company ids → People Search contact.company — more precise than name matching. Same trick resolves universities for education.school.
8. Mine the intent signals: metric.growth (department headcount growth), funding.duration (recent raises), experience.duration.latestJob max 6 months (new in role), profileBadge: HIRING.
9. Handle refunds automatically: on 403 from a trackId endpoint, resubmit; check /submissions (fullyRefunded, refundReason) before assuming credits were lost — no support ticket needed.
10. Errors are often "no result": a 404 from sync endpoints means the person/email/phone wasn't found (and cost nothing where finding is charged) — continue the workflow, don't retry blindly.