# AI Ark Documentation

> Documentation for AI Ark

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Quickstart](https://docs.ai-ark.com/docs/get-started.md)
- [AI Agents (API Context)](https://docs.ai-ark.com/docs/ai-agents.md)

## API Reference
- [People Search API](https://docs.ai-ark.com/reference/people-search-1.md): Searches 400+ million enriched, verified and active person profiles using contact and/or account (company) filters — the starting point for building outbound lead lists. Each result contains the full person profile and their company data. <strong>Results do not include emails or phone numbers</strong> — enrich them with the endpoints listed under Related Endpoints below. <br/><br/> 💳 <strong>Credit Usage:</strong> 0.5 credits per returned result (e.g. <code>size: 25</code> with 25 matches = 12.5 credits). You only pay for results actually returned. <br/><br/> ⚠️ <strong>Track ID:</strong> The response includes a <code>trackId</code>. Pass it to <a href="/reference/people-email-finder-by-track-id">Find Emails by Track ID</a> to get verified emails for this exact result set. The <code>trackId</code> can be used <strong>once</strong> and expires <strong>6 hours</strong> after this response — submit it promptly. <br/><br/> <strong>Contact Filters:</strong> <br/> &nbsp;&nbsp;<strong>Profile:</strong> Full Name, Social Media Link, LinkedIn, Location, Language Skills, Profile Badge, LinkedIn Follower &amp; Connection Count <br/> &nbsp;&nbsp;<strong>Professional:</strong> Current &amp; Past Company, Seniority, Department and Function, Experience (Current/Previous Title, Duration) <br/> &nbsp;&nbsp;<strong>Skills &amp; Education:</strong> Skills, Certifications, Education (School, Degree, Field of Study, Date), Keywords, Social Media <br/><br/> <strong>Account Filters:</strong> <br/> &nbsp;&nbsp;<strong>Company Identification:</strong> Name or Domain, Domain, LinkedIn, URL, Name, Social Media Link, Phone Number <br/> &nbsp;&nbsp;<strong>Company Details:</strong> Industry, Location, Products and Services, Social Media, Company Type, Founded Year, Operation Language, Geo Location <br/> &nbsp;&nbsp;<strong>Financial &amp; Size:</strong> Employee Size, Annual Revenue, Funding <br/> &nbsp;&nbsp;<strong>Advanced Filters:</strong> Keywords, Employee by Department, Headcount Growth, Technologies, NAICS <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-preview">People Preview</a> — validate these filters first for a flat 1 credit per page <br/> &nbsp;&nbsp;• <a href="/reference/people-email-finder-by-track-id">Find Emails by Track ID</a> — get BounceBan-verified emails for this result set (1 credit per found email, 0 if not found) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — search + email finding in a single async call, up to 10,000 people <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email</a> — enrich one person from a result <code>id</code> <br/> &nbsp;&nbsp;• <a href="/reference/company-search-1">Company Search</a> — build the account list first, then target its employees via <code>contact.company</code> <br/> &nbsp;&nbsp;• <a href="/reference/save-list">Lists</a> — exclude already-contacted people (free) <br/><br/> 📥 <strong>Filter value lists:</strong> <a href="https://ai-ark.com/static/industries.csv?v=1">industries.csv</a> (919) · <a href="https://ai-ark.com/static/technologies.csv?v=1">technologies.csv</a> (16,000+) · <a href="https://ai-ark.com/static/departments-and-functions.csv?v=2">departments-and-functions.csv</a> (592). All other allowed values are listed inline in the field descriptions below. <br/><br/> <strong>Learn how to use this API to enrich leads inside Clay:</strong> <a href="https://www.loom.com/share/7a70cfdc73994abebefc239aafbfc22e" target="_blank" rel="noopener">Watch Video</a> <br/><br/> <strong>Rate limits:</strong> 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at <a href="mailto:support@ai-ark.com">support@ai-ark.com</a> or via the in-app chat. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [People Preview](https://docs.ai-ark.com/reference/people-preview.md): Run any People Search for a flat <strong>1 credit per page</strong> and see who matches before spending per-result credits — the recommended first call of every list-building workflow. Validate your filters, check <code>totalElements</code>, inspect match quality, then send the <strong>exact same filter body</strong> to <a href="/reference/people-search-1">People Search</a> or <a href="/reference/people-export-with-email">Export People with Email</a>. <br/><br/> 💳 <strong>Credit Usage:</strong> 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. <br/><br/> <strong>Each preview result contains:</strong> <br/> &nbsp;&nbsp;• The person's real AI Ark <code>id</code> — accepted directly by <a href="/reference/people-export-single">Export Single Person with Email</a>, no full search needed <br/> &nbsp;&nbsp;• First name, <strong>masked last name</strong> (e.g. <code>Ba***e</code>), title, headline, location, department/functions/seniority, position history with dates <br/> &nbsp;&nbsp;• The full company object: <code>id</code>, name, description, industry, headcount, revenue, HQ + office locations, keywords, NAICS/SIC <br/> &nbsp;&nbsp;• <code>has_*</code> availability flags (<code>has_mobile</code>, <code>has_skills</code>, <code>has_educations</code>, …) — see what data exists <strong>before</strong> paying to enrich; <code>has_mobile: true</code> means a <a href="/reference/people-mobile-phone-finder">Mobile Phone Finder</a> call (5 credits) has something to find <br/><br/> <strong>Not included:</strong> unmasked last names, emails, phone numbers, and no <code>trackId</code> (email finding chains off People Search only). <br/><br/> <strong>Body:</strong> identical to People Search — all account, contact and lists filters plus <code>page</code> and <code>size</code>. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> — full unmasked profiles + <code>trackId</code> for email finding (0.5/result) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — same filters, full data + BounceBan-verified emails (0.5/person + 0.5/found email) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email</a> — cherry-pick preview <code>id</code>s and enrich row by row (1 credit per found email) <br/><br/> <strong>Rate limits:</strong> 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at <a href="mailto:support@ai-ark.com">support@ai-ark.com</a> or via the in-app chat. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Company Search API](https://docs.ai-ark.com/reference/company-search-1.md): Searches 70+ million enriched, verified and active company profiles using account filters — ideal for building target-account (ABM) lists. Includes <strong>Lookalike Search</strong>: pass up to 5 domains or LinkedIn company URLs in <code>lookalikeDomains</code> to find similar companies. <br/><br/> 💳 <strong>Credit Usage:</strong> 0.1 credits per returned result (Lookalike Search included). E.g. <code>size: 100</code> with 100 matches = 10 credits. <br/><br/> 💡 <strong>Tip:</strong> Each result includes a company <code>id</code> (UUID). Use these IDs in the People Search filter <code>contact.company</code> to find people working at exactly these companies — more precise than matching by name. <br/><br/> <strong>Company Identification:</strong> Name or Domain, Domain, LinkedIn, URL, Name, Social Media Link, Phone Number <br/> <strong>Company Details:</strong> Industry, Location, Products and Services, Social Media, Company Type, Founded Year, Operation Language, Geo Location <br/> <strong>Financial &amp; Size:</strong> Employee Size, Annual Revenue, Funding <br/> <strong>Advanced Filters:</strong> Keywords, Employee by Department, Headcount Growth, Technologies, NAICS <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> — find the people at these companies (0.5/result) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — bulk-export those people with verified emails <br/> &nbsp;&nbsp;• <a href="/reference/save-list">Lists</a> — exclude accounts you already work (free) <br/><br/> 📥 <strong>Filter value lists:</strong> <a href="https://ai-ark.com/static/industries.csv?v=1">industries.csv</a> (919) · <a href="https://ai-ark.com/static/technologies.csv?v=1">technologies.csv</a> (16,000+) · <a href="https://ai-ark.com/static/departments-and-functions.csv?v=2">departments-and-functions.csv</a> (592). All other allowed values are listed inline in the field descriptions below. <br/><br/> <strong>Learn how to use this API to enrich leads inside Clay:</strong> <a href="https://www.loom.com/share/7a70cfdc73994abebefc239aafbfc22e" target="_blank" rel="noopener">Watch Video</a> <br/><br/> <strong>Rate limits:</strong> 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at <a href="mailto:support@ai-ark.com">support@ai-ark.com</a> or via the in-app chat. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Create or Update a List](https://docs.ai-ark.com/reference/save-list.md): Build reusable lists of people or companies, then reference them from <a href="/reference/people-search-1">People Search</a>, <a href="/reference/company-search-1">Company Search</a> and <a href="/reference/people-export-with-email">Export People with Email</a> to <strong>exclude</strong> matches — the standard way to skip prospects you already contacted or accounts you want to avoid. <br/><br/> 💳 <strong>Credit Usage:</strong> Free — lists never cost credits. <br/><br/> ♻️ <strong>Reusable &amp; rewritable:</strong> the same list <code>id</code> stays valid across many searches. Update it any time: <code>mode: APPEND</code> (default) adds values; <code>mode: REPLACE</code> rewrites the list with a completely fresh set of values. <br/><br/> You can keep up to <strong>50 lists per day</strong>. Each list can hold up to <strong>10,000 items</strong>. Lists expire automatically after <strong>24 hours</strong> — recreate them daily. <br/><br/> <strong>How it works</strong> <br/> &nbsp;&nbsp;• No <code>id</code> → a new list is created (<code>type</code> is required). <br/> &nbsp;&nbsp;• Your existing <code>id</code> → the list is updated (<code>APPEND</code> merges, <code>REPLACE</code> overwrites). <br/> &nbsp;&nbsp;• Unknown <code>id</code> → a new list is created for you. <br/><br/> <strong>Supported types</strong>: <code>people_id</code>, <code>company_id</code>. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> — exclude via <code>lists.people_id</code> <br/> &nbsp;&nbsp;• <a href="/reference/company-search-1">Company Search</a> — exclude via <code>lists.company_id</code> <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — suppress contacted people from bulk exports <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Export Single Person with Email](https://docs.ai-ark.com/reference/people-export-single.md): Exports a single person with email finding in real time — built for row-by-row enrichment (CRM records, spreadsheets, Clay tables). Returns the full person profile plus a verified email. <br/><br/> You must provide either <code>id</code> (the person's AI-Ark ID from a previous <a href="/reference/people-search-1">People Search</a>) or <code>url</code> (the person's LinkedIn profile URL). At least one of the two fields is required; if both are empty, the API returns <code>400 Bad Request</code>. If no email is found, the API returns <code>404 Not Found</code>. <br/><br/> 💳 <strong>Credit Usage:</strong> 1 credit per successful call (0.5 for the Full Profile Enrichment and 0.5 for the real-time BounceBan-validated email) — and <strong>0 credits if we do not find a valid email</strong>. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP &amp; CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong> — safe to send, no re-verification needed. <br/><br/> <strong>Using Clay?</strong> The Clay-compatible <a href="/reference/people-export-single-v2">/v2/people/export/single</a> endpoint is recommended: it returns HTTP 200 for found and not-found cases, which is what Clay expects. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single-v2">Export Single Person with Email (V2 – Clay Compatible)</a> <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — bulk export up to 10,000 people at once <br/> &nbsp;&nbsp;• <a href="/reference/people-mobile-phone-finder">Mobile Phone Finder</a> — add a mobile number for the same person (5 credits/result) <br/> &nbsp;&nbsp;• <a href="/reference/people-reverse-lookup">Reverse People Lookup</a> — start from an email or phone instead <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Export Single Person with Email (V2 - Clay Compatible)](https://docs.ai-ark.com/reference/people-export-single-v2.md): V2 of <a href="/reference/people-export-single">Export Single Person with Email</a> — <strong>Clay-compatible</strong>. Behaves exactly like <code>/v1/people/export/single</code>, except that when the person is not found or has no email it returns <strong>HTTP 200</strong> with an envelope <code>{ status, error, data }</code> and <code>data: null</code> (instead of the v1 <code>404</code>). <br/><br/> Lookup uses <code>id</code> first, then <code>url</code>. You must provide either <code>id</code> or <code>url</code>; if both are empty the API returns <code>400 Bad Request</code>. <br/><br/> ✨ <strong>Recommended for Clay:</strong> this V2 endpoint gracefully returns <strong>HTTP 200</strong> for both the found and not-found cases, which is what Clay expects when enriching leads. <br/><br/> 💳 <strong>Credit Usage:</strong> 1 credit per successful call (0.5 Full Profile Enrichment + 0.5 real-time BounceBan-validated email), and <strong>0 credits if we do not find a valid email</strong>. The charged amount is also returned in the <code>X-Credit</code> response header (e.g. <code>-1.0</code>), present only on the charged (email found) response. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP &amp; CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong> — safe to send, no re-verification needed. <br/><br/> Real errors (400 / 402 / 500) and gateway errors (401 / 429) are returned as-is with their real HTTP status — they are not wrapped. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email (V1)</a> — same pricing, 404 on not-found <br/> &nbsp;&nbsp;• <a href="/reference/people-mobile-phone-finder-v2">Mobile Phone Finder (V2 – Clay Compatible)</a> — add mobile numbers in the same Clay table <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — bulk instead of row-by-row <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Export People with Email](https://docs.ai-ark.com/reference/people-export-with-email.md): Search and email finding in a single asynchronous call: exports up to <strong>10,000</strong> people matching the same account and contact filters as the <a href="/reference/people-search-1">People Search API</a>, with real-time verified emails included. The recommended endpoint for bulk outbound list building. <br/><br/> 💳 <strong>Credit Usage:</strong> 0.5 credits per exported person (charged for everyone, whether or not an email is found) <strong>+ 0.5 credits per found valid email</strong>. Example: 1,000 people with 700 emails found = 1,000 × 0.5 + 700 × 0.5 = 850 credits. You only pay the email portion for emails verified in real time by BounceBan. Note: this differs from <a href="/reference/people-email-finder-by-track-id">Find Emails by Track ID</a>, which charges only for found emails. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP &amp; CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong> — safe to send, no re-verification needed. <br/><br/> <strong>Limit:</strong> <code>size</code> maximum is <strong>10000</strong>. Exceeding this limit returns <code>400 Bad Request - pagination limit exceeded</code>. <br/><br/> Results are processed asynchronously; provide a <code>webhook</code> URL to receive a <code>POST</code> when the export completes, or poll <a href="/reference/get-export-people-statistics-by-track-id">Export People Statistics</a>. <br/><br/> <strong>Auto-refund window:</strong> A submission that is charged but never delivered is auto-refunded after up to <strong>10 hours</strong>. <br/><br/> <strong>Rate limits (per token):</strong> If a token already has <strong>500</strong> requests in flight, a further submit is rejected with <code>400 too many pending requests</code> — drain below the cap (or wait for completions), then retry. <strong>10</strong> jobs are processed at once. Limits are independent per service and per token. <br/><br/> The response returns a <code>trackId</code> and <code>state</code> (e.g. <code>PENDING</code>) with <code>statistics</code> (total, success, failed, found). <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/get-export-people-statistics-by-track-id">Export People Statistics</a> — poll job progress (free) <br/> &nbsp;&nbsp;• <a href="/reference/export-people-results-by-track-id">Export People Results</a> — fetch the exported people + emails, paginated (free) <br/> &nbsp;&nbsp;• <a href="/reference/get-export-people-submissions">Export People Submissions</a> — your submission &amp; refund history (free) <br/> &nbsp;&nbsp;• <a href="/reference/resend-export-people-webhook-1">Resend Export People Webhook</a> — re-trigger delivery (free) <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> + <a href="/reference/people-email-finder-by-track-id">Find Emails by Track ID</a> — the equivalent two-step flow with a preview step <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email</a> — row-by-row instead of bulk <br/><br/> 📘 <strong>Webhook Payload:</strong> see <a href="/reference/export-people-webhook">Export People Webhook Payload</a>. 🔄 <strong>Retry:</strong> We automatically retry webhook delivery up to 3 times. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Export People Results API](https://docs.ai-ark.com/reference/export-people-results-by-track-id.md): 💳 <strong>Credit Usage:</strong> Free — fetching results never costs credits (you already paid at submission). Paginate with <code>page</code> (zero-based) and <code>size</code> (1–100, default 10). <strong>Export People Results:</strong> returns <code>409</code> while the export is still in progress — poll Statistics until <code>state: DONE</code>. <strong>Email Finder Results:</strong> readable while running; unfinished items show <code>state: PROCESSING</code>. A fully refunded (<code>STUCK_*</code>) <code>trackId</code> returns <code>403</code> — resubmit it. <br/><br/><br/>Returns paginated export results for a given <code>trackId</code>. The <code>trackId</code> is from the Export People with Email response. Use the <code>page</code> and <code>size</code> query parameters to paginate through results. <br/><br/> Returns full people data with email, company, and profile information. When email finding is still in progress, items may have <code>email.state</code> <code>PROCESSING</code> and an empty <code>email.output</code> array. When complete, <code>email.state</code> is <code>DONE</code> and <code>email.output</code> contains the found email(s). <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong>. <br/><br/> Returns <code>409 Conflict</code> when the track ID is still in progress. <br/><br/> <strong>Fully-refunded submissions:</strong> if the submission was auto-refunded for non-delivery (<code>STUCK_HARD_REFUND</code> / <code>STUCK_SOFT_REFUND</code>), this endpoint returns <code>403 Forbidden</code> with an actionable message — the results are not retrievable, so submit the request again. If it was refunded because there was no deliverable result (<code>SEARCH_NO_RESULTS</code> / <code>NO_EMAILS_FOUND</code>), it returns <code>200</code> with an empty page.
- [Export People Statistics](https://docs.ai-ark.com/reference/get-export-people-statistics-by-track-id.md): 💳 <strong>Credit Usage:</strong> Free — polling never costs credits (you already paid at submission). Use this to track <code>state</code> and <code>statistics</code> until the job is <code>DONE</code> (Email Finder: total, found · Export: total, success, failed, found). A fully refunded (<code>STUCK_*</code>) <code>trackId</code> returns <code>403</code> with the refund reason — resubmit it. <br/><br/><br/>Returns export statistics for a given <code>trackId</code>. The <code>trackId</code> is from the Export People with Email endpoint. Use this endpoint to poll progress (e.g. <code>statistics.total</code>, <code>statistics.found</code>) and <code>state</code> until the job completes. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong>. <br/><br/> <strong>Fully-refunded submissions:</strong> if the submission was auto-refunded for non-delivery (<code>STUCK_HARD_REFUND</code> / <code>STUCK_SOFT_REFUND</code>), this endpoint returns <code>403 Forbidden</code> with an actionable message — the results are not retrievable, so submit the request again. If it was refunded because there was no deliverable result (<code>SEARCH_NO_RESULTS</code> / <code>NO_EMAILS_FOUND</code>), it returns <code>200</code> with zeroed statistics. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Export People Submissions](https://docs.ai-ark.com/reference/get-export-people-submissions.md): 💳 <strong>Credit Usage:</strong> Free. Your own submission history, including refund status (<code>fullyRefunded</code>, <code>refundReason</code>: <code>STUCK_SOFT_REFUND</code> / <code>STUCK_HARD_REFUND</code>) — check here if a charged job was never delivered (auto-refund within up to 10 hours). <br/><br/><br/>Returns the caller's own People-Export submission history, paged and filterable. The list is automatically scoped to the authenticated token's customer — no special role is required. <br/><br/> Each item is a submission summary including its <code>trackId</code>, <code>state</code>, refund status (<code>fullyRefunded</code>, <code>refundReason</code>) and timestamps. <code>refundReason</code> is <code>null</code> unless the submission was fully refunded. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Export People Webhook Payload](https://docs.ai-ark.com/reference/export-people-webhook.md)
- [Resend Export People Webhook](https://docs.ai-ark.com/reference/resend-export-people-webhook-1.md): 💳 <strong>Credit Usage:</strong> Free. Re-sends the completion webhook for a <code>trackId</code> to the URL you specify — use it when the initial delivery (auto-retried 3×) failed or you need to notify a different URL. <br/><br/><br/>Resends the webhook notification for a given <code>trackId</code> to the specified <code>webhook</code> URL. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong>. <br/><br/> Returns a structured <code>WebhookDeliveryResult</code>: <code>delivered</code> tells you whether your webhook accepted the delivery (HTTP 2xx) and <code>webhook.status</code> echoes the status your endpoint returned. A rejected or unreachable webhook still returns <code>200</code> with <code>delivered: false</code> — inspect those fields rather than the HTTP status. A failure on our side likewise returns <code>200</code> with <code>delivered: false</code> and <code>fault: SERVICE</code> (contact support). If the submission was auto-refunded for non-delivery (<code>STUCK_HARD_REFUND</code> / <code>STUCK_SOFT_REFUND</code>) it returns <code>403</code> and is not retrievable — resubmit. If it was fully refunded with no deliverable result (<code>SEARCH_NO_RESULTS</code> / <code>NO_EMAILS_FOUND</code>), the re-delivered webhook carries the full-refund payload. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Find Emails by Track ID](https://docs.ai-ark.com/reference/people-email-finder-by-track-id.md): Triggers email finding for a previous People Search result set, using the <code>trackId</code> from the <a href="/reference/people-search-1">People Search API</a> response. This is step 2 of the two-step list-building flow (search → find emails). <br/><br/> 💳 <strong>Credit Usage:</strong> 1 credit per found valid email (0.5 for the people data + 0.5 for the real-time BounceBan-verified email) — and <strong>0 credits for people where no valid email is found</strong>. Example: 25 people submitted, 18 valid emails found = 18 × 1 = 18 credits; the other 7 cost nothing. Unlike <a href="/reference/people-export-with-email">Export People with Email</a> (0.5 per person regardless + 0.5 per found email), here you only pay for delivered emails. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP &amp; CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong> — safe to send, no re-verification needed. <br/><br/> ⚠️ <strong>Important:</strong> Each <code>trackId</code> can only be used once. After the first request, the track ID is consumed and subsequent requests with the same ID will fail. The <code>trackId</code> also expires <strong>6 hours</strong> after the original People Search response. <br/><br/> Provide a <code>webhook</code> URL to receive asynchronous notifications when email finding completes. When the job completes, we <code>POST</code> the result to your webhook URL. <br/><br/> <strong>Auto-refund window:</strong> A submission that is charged but never delivered is auto-refunded after up to <strong>10 hours</strong>. <br/><br/> <strong>Rate limits (per token):</strong> If a token already has <strong>500</strong> requests in flight, a further submit is rejected with <code>400 too many pending requests</code> — drain below the cap (or wait for completions), then retry. <strong>10</strong> jobs are processed at once. Limits are independent per service and per token. <br/><br/> The response includes <code>statistics</code> (total, found) and <code>state</code> (e.g. <code>PENDING</code>) to track progress. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> — produces the <code>trackId</code> (run it first) <br/> &nbsp;&nbsp;• <a href="/reference/get-email-finder-statistics-by-track-id">Email Finder Statistics</a> — poll job progress (free) <br/> &nbsp;&nbsp;• <a href="/reference/get-email-finder-results-by-track-id">Email Finder Results</a> — fetch the found emails, paginated (free) <br/> &nbsp;&nbsp;• <a href="/reference/get-email-finder-submissions">Email Finder Submissions</a> — your submission &amp; refund history (free) <br/> &nbsp;&nbsp;• <a href="/reference/resend-email-finder-webhook-1">Resend Email Finder Webhook</a> — re-trigger delivery (free) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a> — prefer this to do search + emails in one call <br/><br/> 📘 <strong>Webhook Payload:</strong> For the full webhook response schema, see <a href="/reference/find-emails-webhook">Find Emails Webhook Payload</a>. 🔄 <strong>Retry:</strong> We automatically retry webhook delivery up to 3 times. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Email Finder Results API](https://docs.ai-ark.com/reference/get-email-finder-results-by-track-id.md): 💳 <strong>Credit Usage:</strong> Free — fetching results never costs credits (you already paid at submission). Paginate with <code>page</code> (zero-based) and <code>size</code> (1–100, default 10). <strong>Export People Results:</strong> returns <code>409</code> while the export is still in progress — poll Statistics until <code>state: DONE</code>. <strong>Email Finder Results:</strong> readable while running; unfinished items show <code>state: PROCESSING</code>. A fully refunded (<code>STUCK_*</code>) <code>trackId</code> returns <code>403</code> — resubmit it. <br/><br/><br/>Returns paginated email finder results for a given <code>trackId</code>. The <code>trackId</code> is from the Find Emails by Track ID response. Use the <code>page</code> and <code>size</code> query parameters to paginate through results. <br/><br/> Each item includes a <code>refId</code>, <code>state</code>, <code>input</code> (firstname, lastname, domain), and <code>output</code> (email results with verification details). <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong>. <br/><br/> <strong>Fully-refunded submissions:</strong> if the submission was auto-refunded for non-delivery (<code>STUCK_HARD_REFUND</code> / <code>STUCK_SOFT_REFUND</code>), this endpoint returns <code>403 Forbidden</code> with an actionable message — the results are not retrievable, so submit the request again. If it was refunded because there was no deliverable result (<code>SEARCH_NO_RESULTS</code> / <code>NO_EMAILS_FOUND</code>), it returns <code>200</code> with an empty page.
- [Email Finder Statistics](https://docs.ai-ark.com/reference/get-email-finder-statistics-by-track-id.md): 💳 <strong>Credit Usage:</strong> Free — polling never costs credits (you already paid at submission). Use this to track <code>state</code> and <code>statistics</code> until the job is <code>DONE</code> (Email Finder: total, found · Export: total, success, failed, found). A fully refunded (<code>STUCK_*</code>) <code>trackId</code> returns <code>403</code> with the refund reason — resubmit it. <br/><br/><br/>Returns email-finding statistics for a given <code>trackId</code>. The <code>trackId</code> is from the Find Emails by Track ID endpoint. Use this endpoint to poll progress (e.g. <code>statistics.total</code>, <code>statistics.found</code>) and state until the job completes. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong>. <br/><br/> <strong>Fully-refunded submissions:</strong> if the submission was auto-refunded for non-delivery (<code>STUCK_HARD_REFUND</code> / <code>STUCK_SOFT_REFUND</code>), this endpoint returns <code>403 Forbidden</code> with an actionable message — the results are not retrievable, so submit the request again. If it was refunded because there was no deliverable result (<code>SEARCH_NO_RESULTS</code> / <code>NO_EMAILS_FOUND</code>), it returns <code>200</code> with zeroed statistics. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Email Finder Submissions](https://docs.ai-ark.com/reference/get-email-finder-submissions.md): 💳 <strong>Credit Usage:</strong> Free. Your own submission history, including refund status (<code>fullyRefunded</code>, <code>refundReason</code>: <code>STUCK_SOFT_REFUND</code> / <code>STUCK_HARD_REFUND</code>) — check here if a charged job was never delivered (auto-refund within up to 10 hours). <br/><br/><br/>Returns the caller's own Email-Finder submission history, paged and filterable. The list is automatically scoped to the authenticated token's customer — no special role is required. <br/><br/> Each item is a submission summary including its <code>trackId</code>, <code>state</code>, refund status (<code>fullyRefunded</code>, <code>refundReason</code>) and timestamps. <code>refundReason</code> is <code>null</code> unless the submission was fully refunded. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Find Emails Webhook Payload](https://docs.ai-ark.com/reference/find-emails-webhook.md)
- [Resend Email Finder Webhook](https://docs.ai-ark.com/reference/resend-email-finder-webhook-1.md): 💳 <strong>Credit Usage:</strong> Free. Re-sends the completion webhook for a <code>trackId</code> to the URL you specify — use it when the initial delivery (auto-retried 3×) failed or you need to notify a different URL. <br/><br/><br/>Resends the webhook notification for a given <code>trackId</code> to the specified <code>webhook</code> URL. Use this when the initial webhook delivery failed or you need to trigger a new notification to a different URL. <br/><br/> ✅ <strong>Email Verification:</strong> All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by <strong>BounceBan</strong>. <br/><br/> Returns a structured <code>WebhookDeliveryResult</code>: <code>delivered</code> tells you whether your webhook accepted the delivery (HTTP 2xx) and <code>webhook.status</code> echoes the status your endpoint returned. A rejected or unreachable webhook still returns <code>200</code> with <code>delivered: false</code> — inspect those fields rather than the HTTP status. A failure on our side likewise returns <code>200</code> with <code>delivered: false</code> and <code>fault: SERVICE</code> (contact support). If the submission was auto-refunded for non-delivery (<code>STUCK_HARD_REFUND</code> / <code>STUCK_SOFT_REFUND</code>) it returns <code>403</code> and is not retrievable — resubmit. If it was fully refunded with no deliverable result (<code>SEARCH_NO_RESULTS</code> / <code>NO_EMAILS_FOUND</code>), the re-delivered webhook carries the full-refund payload. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Mobile Phone Finder API](https://docs.ai-ark.com/reference/people-mobile-phone-finder.md): Finds mobile phone numbers for a person — use it to add direct-dial numbers to your outbound lists. <br/> <strong>Search Options:</strong> <br/> &nbsp;&nbsp;&nbsp;&nbsp;• <strong>LinkedIn Search:</strong> Provide only the <code>linkedin</code> URL (no need for domain/name) <br/> &nbsp;&nbsp;&nbsp;&nbsp;• <strong>Domain + Name Search:</strong> Provide both <code>domain</code> and <code>name</code> (no need for LinkedIn) <br/><br/> 💳 <strong>Credit Usage:</strong> 5 credits per result (charged when a phone number is found). If nothing is found, the API returns <code>404</code> and no credits are charged. <br/><br/> <strong>Using Clay?</strong> The Clay-compatible <a href="/reference/people-mobile-phone-finder-v2">/v2/people/mobile-phone-finder</a> endpoint is recommended for enriching leads inside Clay. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-mobile-phone-finder-v2">Mobile Phone Finder (V2 – Clay Compatible)</a> <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email</a> — verified email for the same person (1 credit) <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> — find the people (and their LinkedIn URLs) first <br/> &nbsp;&nbsp;• <a href="/reference/people-reverse-lookup">Reverse People Lookup</a> — identify who a phone number belongs to <br/><br/> <strong>Rate limits:</strong> 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at <a href="mailto:support@ai-ark.com">support@ai-ark.com</a> or via the in-app chat. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Mobile Phone Finder API (V2 - Clay Compatible)](https://docs.ai-ark.com/reference/people-mobile-phone-finder-v2.md): V2 of the <a href="/reference/people-mobile-phone-finder">Mobile Phone Finder</a> — <strong>Clay-compatible</strong>. Behaves exactly like <code>/v1/people/mobile-phone-finder</code>, except that when no person or phone is found it returns <strong>HTTP 200</strong> with an envelope <code>{ status, error, data }</code> and <code>data: null</code> (instead of the v1 <code>404</code>). <br/> <strong>Search Options:</strong> <br/> &nbsp;&nbsp;&nbsp;&nbsp;• <strong>LinkedIn Search:</strong> Provide only the <code>linkedin</code> URL (no need for domain/name) <br/> &nbsp;&nbsp;&nbsp;&nbsp;• <strong>Domain + Name Search:</strong> Provide both <code>domain</code> and <code>name</code> (no need for LinkedIn) <br/><br/> ✨ <strong>Recommended for Clay:</strong> gracefully returns <strong>HTTP 200</strong> for both found and not-found cases, which is what Clay expects when enriching leads. <strong>Learn how to use this API inside Clay:</strong> <a href="https://www.loom.com/share/7a70cfdc73994abebefc239aafbfc22e" target="_blank" rel="noopener">Watch Video</a> <br/><br/> 💳 <strong>Credit Usage:</strong> 5 credits per result (charged when a phone is found), 0 otherwise. The charged amount is also returned in the <code>X-Credit</code> response header (e.g. <code>-5.0</code>), present only on the charged (phone found) response. <br/><br/> Real errors (400 / 402 / 500) and gateway errors (401 / 429) are returned as-is with their real HTTP status — they are not wrapped. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-mobile-phone-finder">Mobile Phone Finder (V1)</a> — same pricing, 404 on not-found <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single-v2">Export Single Person with Email (V2 – Clay Compatible)</a> — verified email in the same Clay flow (1 credit) <br/><br/> <strong>Rate limits:</strong> 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at <a href="mailto:support@ai-ark.com">support@ai-ark.com</a> or via the in-app chat. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Personality Analysis API](https://docs.ai-ark.com/reference/people-analysis.md): Analyzes the skills, headline, and summary of a profile and returns a complete personality profile with ready-to-apply outreach guidance: <strong>DISC</strong> and <strong>OCEAN (Big Five)</strong> scores with an archetype label, plus <code>selling</code> and <code>hiring</code> blocks containing field-by-field email advice (subject, salutation, tone, length, bullet points, closing line), <em>whatToSay / whatToAvoid</em> talking points, and key decision traits (risk tolerance, decision speed, decision drivers). Pipe these into your email-generation prompts to personalize outreach at scale. <br/><br/> 💳 <strong>Credit Usage:</strong> 4 credits per request. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a> — find the people (and their LinkedIn URLs) first (0.5/result) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email</a> — their BounceBan-verified email (1 credit) <br/> &nbsp;&nbsp;• <a href="/reference/people-reverse-lookup">Reverse People Lookup</a> — identify a person from an email/phone before analyzing them (0.5/request) <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [Reverse People Lookup API](https://docs.ai-ark.com/reference/people-reverse-lookup.md): Identifies a person from an <strong>email address</strong>: if a person with that email exists in the AI Ark database, you get back their full profile (name, title, company, LinkedIn, and more) — similar to a People Search result, excluding valid email and mobile phone. Useful for enriching inbound leads, newsletter signups, form fills, and CRM records where you only have an email. A <code>404</code> means no profile with this email was found. <br/> The <code>search</code> parameter contains the email address to look up and is the only request field. <br/><br/> 💳 <strong>Credit Usage:</strong> 0.5 credits per request. <br/><br/> 🔗 <strong>Related Endpoints:</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person with Email</a> — get a BounceBan-verified email for the identified person (1 credit) <br/> &nbsp;&nbsp;• <a href="/reference/people-mobile-phone-finder">Mobile Phone Finder</a> — get their mobile number (5 credits/result) <br/> &nbsp;&nbsp;• <a href="/reference/people-analysis">Personality Analysis</a> — personalize your outreach to this person (4 credits) <br/><br/> 📥 <strong>Filter value lists:</strong> <a href="https://ai-ark.com/static/industries.csv?v=1">industries.csv</a> (919) · <a href="https://ai-ark.com/static/technologies.csv?v=1">technologies.csv</a> (16,000+) · <a href="https://ai-ark.com/static/departments-and-functions.csv?v=2">departments-and-functions.csv</a> (592). All other allowed values are listed inline in the field descriptions below. <br/><br/> <strong>Learn how to use this API to enrich leads inside Clay:</strong> <a href="https://www.loom.com/share/7a70cfdc73994abebefc239aafbfc22e" target="_blank" rel="noopener">Watch Video</a> <br/><br/> <strong>Rate limits:</strong> 5 requests per second by default. Customers using more than 450,000 credits per month can get custom rate limits — contact us at <a href="mailto:support@ai-ark.com">support@ai-ark.com</a> or via the in-app chat. <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.
- [MCP Server](https://docs.ai-ark.com/reference/mcp.md)
- [Fetch Your Credit](https://docs.ai-ark.com/reference/fetch-credit.md): Retrieves the number of remaining credits in your account. <br/><br/> 💳 <strong>Credit Usage:</strong> Free — this endpoint never costs credits. Call it before large jobs to make sure your balance covers the estimated cost (e.g. an <a href="/reference/people-export-with-email">Export People with Email</a> of 1,000 people can cost up to 1,000 credits). <br/><br/> 💡 <strong>What credits buy (quick reference):</strong> <br/> &nbsp;&nbsp;• <a href="/reference/people-search-1">People Search</a>: 0.5 / result <br/> &nbsp;&nbsp;• <a href="/reference/company-search-1">Company Search</a> (incl. Lookalike): 0.1 / result <br/> &nbsp;&nbsp;• <a href="/reference/people-email-finder-by-track-id">Find Emails by Track ID</a>: 1 / found valid email (0 if not found) <br/> &nbsp;&nbsp;• <a href="/reference/people-export-with-email">Export People with Email</a>: 0.5 / person + 0.5 / found valid email <br/> &nbsp;&nbsp;• <a href="/reference/people-export-single">Export Single Person</a>: 1 if email found, 0 if not <br/> &nbsp;&nbsp;• <a href="/reference/people-mobile-phone-finder">Mobile Phone Finder</a>: 5 / result <br/> &nbsp;&nbsp;• <a href="/reference/people-reverse-lookup">Reverse People Lookup</a>: 0.5 / request <br/> &nbsp;&nbsp;• <a href="/reference/people-analysis">Personality Analysis</a>: 4 / request <br/> &nbsp;&nbsp;• <a href="/reference/save-list">Lists</a>: free <br/><br/> The header <code>Content-Type: application/json</code> must be included in the request.