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, 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
• 🔌 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}
• Content type: every request needs the header Content-Type: application/json
• All search/enrichment endpoints are POST with a JSON body. Status/result endpoints are GET/PATCH.
• 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: 100, 70 emails found → 100 × 0.5 + 70 × 0.5 = 85 credits.
• Enriching 1 person via Export Single: 1 credit (or 0 if no email found).

Refunds: Async jobs (Export People, Email Finder) are auto-refunded (fullyRefunded: true in /submissions) when the search matched nobody (SEARCH_NO_RESULTS), no emails could be found (NO_EMAILS_FOUND), or results were never delivered (STUCK_HARD_REFUND / STUCK_SOFT_REFUND, within up to 10 hours). No support ticket needed.

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 BounceBan validation — the 0.5 email portion on Export People, and the full 1 credit on Find Emails by Track ID and Export Single (both free when no valid email is found).

Email output object (in results): address, domainType (SMTP | CATCH_ALL), status (VALID), date (timestamp of the real-time verification), mx (record, provider, google, found), free (free-mail domain), generic (role address like info@). Use generic and domainType to segment sending strategy. Per-record email.state: PROCESSING → DONE.

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

5. Standard Workflows (recipes)

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

POST /v2/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) and has_* flags (e.g. has_mobile: true → a Mobile Phone Finder call has something to find). Preview returns no emails, masked last names, and trackId: null (no email-finder chaining).

Recipe A — Two-step list building (max control)

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 (optional webhook). ⚠️ Each trackId works once and expires 6 hours after the search response.
3. Poll GET /v1/people/email-finder/{trackId}/statistics until state: DONE (or wait for the webhook).
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, 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 3×; re-trigger 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.

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.
2. Take the returned company id values and use them in People Search under contact.company.latest / contact.company.current to find people at exactly those companies.
3. Continue with Recipe A or B for emails.

Suppression (avoid re-contacting)

• POST /v1/lists with { "type": "people_id", "values": [ ...ids ] } → returns a list id.
• Reference it in searches: "lists": { "people_id": { "exclude": ["<list-id>"] } }.
• Retrieve more than 10,000 records: totalElements shows the full match count, but a single search can page 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 during the day: send the same id with mode: "APPEND" (default, adds values) or mode: "REPLACE" (overwrites values). 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 /v2/people/preview

Purpose: run any People Search cheaply to validate filters and volume before committing credits. Same filter body as People Search.
Credits: 1 per page, flat — whether the page holds 25 or 100 results.
Body: identical to People Search (account, contact, lists, page, 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 (has_mobile, has_skills, …), last_updated. No emails, no phones, trackId: null (email finding chains off People Search only).
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.
Body: { "account": {...}, "contact": {...}, "lists": {...}, "page": 0, "size": 25 } — page is zero-based, size max 100 (default 10).
Response: content[] (people), Spring-style pagination (totalElements, totalPages, size, number), and trackId (single-use, 6h expiry — feed it to /v1/people/email-finder).
Errors: 404 data not found, 501 filter not supported.
Related: People Preview (validate filters for 1 credit/page first), Find Emails by Track ID (emails), Export People with Email (search+email in one call), Company Search (build account lists first), Lists (exclusions).

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": { "range": { "start": 50, "end": 200 } }
    },
    "page": 0, "size": 25
  }'

6.2 Company Search — POST /v1/companies

Purpose: search 70M+ company profiles by account filters; also Lookalike Search via lookalikeDomains (up to 5 domains or LinkedIn company URLs) to find similar companies.
Credits: 0.1 per result (lookalike included).
Body: { "lookalikeDomains": [...], "account": {...}, "lists": {...}, "page": 0, "size": 25 } — size 1–100.
Company-Search-only filter — account.employee (Job Role): find companies by the people they employ — employee.title (match modes), employee.seniority, employee.departmentAndFunction (180 values). Example: "account": { "employee": { "seniority": { "any": { "include": ["c_suite","vp"] } }, "departmentAndFunction": { "any": { "include": ["software_development"] } } } } → companies that have C-suite/VP software-development people. 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.
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. Plan: search → immediately submit email finding.
Body: { "trackId": "<uuid>", "webhook": "https://..." } (webhook optional; delivery auto-retried 3×).
Response: { trackId, statistics: { total, found }, state: "PENDING", webhook: { state, retry } }.
Concurrency: max 500 in-flight submissions per token (400 too many pending requests), 10 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 until DONE.
• GET /v1/people/email-finder/{trackId}/inquiries?page&size — paginated results: refId, input (firstname, lastname, domain), output (email + verification details).
• GET /v1/people/email-finder/submissions — your submission history incl. fullyRefunded, refundReason.
• PATCH /v1/people/email-finder/{trackId}/notify — resend the webhook.
  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 (BounceBan-verified in real time). Note: this differs from Find Emails by Track ID, which charges only for found emails.
Body: same account / contact / lists filters as People Search + page, size (1–10000), webhook. Exceeding 10,000 → 400 pagination limit exceeded.
Response: { trackId, statistics, state: "PENDING", webhook }. Job completion is POSTed to your webhook (retried 3×).
Concurrency & refunds: same as Find Emails by Track ID (500 in flight per token, 10 parallel, ≤10h auto-refund).
Sub-endpoints (all free): GET .../export/{trackId}/statistics, GET .../export/{trackId}/inquiries?page&size (full person + company + email; returns 409 while the export is still in progress — poll statistics until DONE; email.state may be PROCESSING), GET .../export/submissions, PATCH .../export/{trackId}/notify.
Related: People Search + Find Emails by Track ID (the equivalent two-step flow), 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.
v1 vs v2: identical behavior, except not-found: v1 returns 404; 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 (source of person ids), Mobile Phone Finder (phones for the same person), Reverse People Lookup (start from an email/phone 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.
Credits: 5 per result (charged when a phone is found).
Body — two search modes: { "linkedin": "<profile url>" } or { "domain": "acme.com", "name": "Jane Doe" } (domain+name must be together).
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.
Response: data is an array of arrays; the inner array can hold multiple numbers ordered by confidence, E.164 format.
Related: Export Single Person (email for the same person), People Search (find the people first).

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, excluding valid email & mobile). 404 = not in database.
Credits: 0.5 per request.
Body: { "search": "[email protected]" } — search is the only (required) field.
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: analyze a profile's skills, headline and summary and return a personality profile with ready-to-apply outreach guidance: DISC + OCEAN (Big Five) scores, an archetype, and selling/hiring blocks with per-field email advice (subject, tone, length, closing…), whatToSay/whatToAvoid talking points, and key decision traits (risk, speed, drivers). Pipe these into your email-generation prompts.
Credits: 4 per request.
Body: { "url": "https://www.linkedin.com/in/..." } (required).
Related: People Search / Reverse Lookup (find the person), 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 / Company Search / Export People via the lists filter — for suppressing already-contacted prospects or excluded accounts.
Credits: free.
Body: { "id": "<optional uuid>", "type": "people_id" | "company_id", "values": [ ...up to 10000 ], "mode": "APPEND" | "REPLACE" }.
Behavior: no id → new list (type required). Existing id → update: APPEND (default) merges values, REPLACE rewrites the list with a fresh set — the same list id stays valid and reusable across many searches. Unknown id → new list.
Limits: 50 lists/day, 10,000 values/list, lists expire after 24 hours.
Related: People Search, Company Search, Export People with Email (all accept lists).

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. Filter Syntax Primer (People Search, Company Search, Export People)

• Filters live under account (company attributes) and contact (person attributes).
• Most filters use the shape: { "any": { "include": [...], "exclude": [...] }, "all": { "include": [...], "exclude": [...] } } — any = OR, all = AND.
• Text filters (name, url, industries, job title, skills, keywords, product & services…) wrap values with a match mode: { "mode": "SMART" | "WORD" | "STRICT", "content": ["..."] }.
• Match modes: SMART (default) = AI-related concepts — "creative director" also finds "art director", "head of creative". WORD = exact phrase, extra words allowed — matches "associate creative director". STRICT = exact characters only — matches "creative director" and nothing else.
• Caps: max 300 values per include/exclude array; a search pages through at most 10,000 records (totalElements itself is uncapped — use the Lists pattern to retrieve more).
• Experience/company scopes: latest = the person's primary active role only; current = ALL simultaneously-active roles; previous = past roles/employers.
• account.technologies vs account.technology: use technologies (supports match modes); technology is the legacy filter kept for backward compatibility.
• Range filters (employeeSize, revenue, foundedYear, funding, follower counts, experience duration): { "range": { "start": X, "end": Y } } (some with a type).
• contact.company.latest / .current / past take company IDs (UUIDs) from Company Search results — the precise way to target a fixed set of accounts.
• lists filter: { "people_id": { "exclude": ["<list-id>"] } } (People) / { "company_id": { "exclude": ["<list-id>"] } } (Company). Max 10 lists per request.

Key account filters: domain, name, url, linkedin, socialMediaLink, socialMedia, phoneNumber, industries, location, geoLocation, type, foundedYear, language, employeeSize, retailSize, revenue, funding, keyword, technology, technologies, naics, productAndServices, metric (employee by department, headcount growth); Company Search only: employee (Job Role filter — title/seniority/departmentAndFunction of the people a company employs).
Key contact filters: fullName, linkedin, socialMediaLink, socialMedia, socialMediaFollower, location, language, profileBadge, seniority, departmentAndFunction, company (by company IDs), experience (latest/previous title, duration), skill, certification, education (school, degree, fieldOfStudy, date), keyword.

8. Accepted Enum Values

• Seniority (contact.seniority): founder, owner, partner, c_suite, vp, director, head, manager, senior, mid-level, entry, intern
• Profile badge (contact.profileBadge): VERIFIED, PREMIUM, OPEN_TO_WORK, INFLUENCER, CREATOR, HIRING
• Company type (account.type): 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: HEADLINE, SUMMARY, SKILL, CERTIFICATION, COURSE, PROJECTS, PUBLICATION, PATENT, AWARD, ORGANIZATION, VOLUNTEERING, TEST_SCORE, WORK_HISTORY_DESCRIPTION, EDUCATION_DESCRIPTION, LANGUAGE_SKILL
• Account keyword sources: NAME, KEYWORD, SEO, DESCRIPTION, INDUSTRY
• Headcount-growth timeframes: ONE, THREE, SIX, TWELVE, TWENTY_FOUR (months)
• 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/industries.csv
• Technologies (account.technologies): 16,000+ values, e.g. salesforce, hubspot — full list: https://ai-ark.com/technologies.csv
• Departments & functions (contact.departmentAndFunction): 180 values, e.g. software_development, demand_generation — full list: https://ai-ark.com/departments-and-functions.csv
• Locations: free-form and forgiving — countries (Germany), states (California), plain city names (seattle, hamburg), metro areas (greater seattle area), and regions (Europe) all work; exact values are not required. Same vocabulary for contact.location and account.location.

9. Job States, Errors & Rate Limits

Async job states: PENDING → processing → DONE. Per-item email.state may be PROCESSING while running. Stuck jobs auto-refund: STUCK_SOFT_REFUND / STUCK_HARD_REFUND (visible in /submissions).

HTTP errors (all endpoints):

Rate limits: 5 requests per second per token (default). Customers using more than 450,000 credits/month can request custom rate limits via [email protected] or the in-app chat. Async submissions: max 500 in flight per token per service, 10 processed in parallel.

10. Rules of Thumb for Agents

1. Preview first. Validate any new filter set with POST /v2/people/preview (1 credit/page) before spending per-result credits.
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.
4. Use the trackId immediately — single use, 6-hour expiry.
5. Prefer Export People with Email for bulk (one call, ≤10,000 people); prefer Export Single v2 and Mobile Finder v2 inside Clay.
6. Deduplicate with Lists (free): maintain a people_id exclusion list of everyone already contacted; REPLACE to rewrite, APPEND to grow it; rebuild daily (24h expiry).
7. Company targeting: Company Search → take company ids → People Search contact.company — more precise than name matching.