Quickstart
The AI Ark API provides programmatic access to a B2B database of 400M+ people and 70M+ companies, together with contact enrichment (verified emails and mobile numbers), lookalike and signal-based company discovery, and personality analysis. It is a REST API — JSON over HTTPS, authenticated with an API key — also available through a hosted MCP server and Clay templates.
- 400M+ people records · 70M+ company profiles (firmographics, technographics, funding, headcount by department)
- 98% data accuracy, validated and continuously monitored · 30-day refresh cycle
- Emails are verified in real time by BounceBan (SMTP and catch-all) at the moment they are returned
1. Get your API key
Create a key in the API Management Dashboard. Use it server-side and never expose it in client-side code or public repositories.
2. Authenticate
Every request needs two headers; the base URL is the same for all endpoints:
X-TOKEN: YOUR_API_KEY
Content-Type: application/json
Base URL: https://api.ai-ark.com/api/developer-portal
3. Make your first request
Company Search for German software companies with 51–200 employees. page and size are required on all search endpoints (page is zero-based, size max 100). This call costs 0.1 credits per returned company — 1 credit for 10 results.
POST https://api.ai-ark.com/api/developer-portal/v1/companies
Request body
{
"account": {
"industries": { "any": { "include": { "mode": "SMART", "content": ["software development"] } } },
"location": { "any": { "include": ["Germany"] } },
"employeeSize": { "type": "RANGE", "range": [{ "start": 51, "end": 200 }] }
},
"page": 0,
"size": 10
}Response (abridged — the full company object is documented on the Company Search reference page)
{
"content": [
{
"id": "4446fca0-f6b2-5c42-7783-92f7a1eeac7f",
"summary": {
"name": "Example Software GmbH",
"industry": "software development",
"founded_year": 2015,
"type": "PRIVATELY_HELD",
"staff": { "total": 120, "range": { "start": 51, "end": 200 } }
},
"link": { "domain": "example-software.de", "linkedin": "https://www.linkedin.com/company/example-software" },
"location": { "headquarter": { "city": "berlin", "state": "berlin" } },
"technologies": [ { "name": "hubspot", "category": "crm" } ],
"last_updated": "2026-07-01"
}
],
"totalElements": 1294,
"totalPages": 130,
"size": 10,
"number": 0
}4. Responses, pagination, and filters
contentholds the results;totalElements/totalPagesreport the total number of matches for the filters (not capped). Through pagination one search can retrieve up to 10,000 records (page×size); to retrieve more, re-run the search excluding already-fetched IDs via Lists.- No matches → an empty
contentarray or404 data not found; treat both as "no results". - Text filters take a
mode:SMART(AI-related concepts — "creative director" also finds "art director"),WORD(phrase plus surrounding words),STRICT(exact). Job Post Search matches differently: its default isWORD, andSMARTthere means every word in any order.any= OR,all= AND; both acceptinclude/exclude; max 300 values per array. Enum value lists: industries.csv · technologies.csv · departments-and-functions.csv. Every field is documented on its endpoint's reference page.
5. Endpoints and credits
Usage is billed in credits per returned result or per delivered email/phone number. Check your balance anytime with GET /v1/payments/credits (free); manage it in the dashboard.
| Endpoint | Use it to… | Credits |
|---|---|---|
People Preview POST /v1/people/preview | Validate filters and size a market with masked sample results | 1 per page (25–100 results per page) |
People Search POST /v1/people | Search people (full profiles, no contact data); returns a trackId for email finding | 0.5 per result |
Company Search POST /v1/companies | Search companies; lookalike search (up to 5 seeds); Job Role filter (companies by the people they employ) | 0.1 per result |
Job Post Search POST /v1/job-posts | Search job posts to find companies that are hiring for a role or ask for a tool right now | 0.1 per result |
Find Emails by Track ID POST /v1/people/email-finder | Get emails for a People Search result set (async) | 1 per found valid email, 0 if none |
Export People with Email POST /v1/people/export | Search + emails in one async job, up to 10,000 people, with a webhook | 0.5 per person + 0.5 per found valid email |
Export Single Person with Email POST /v1/people/export/single | Enrich one person by AI Ark ID or LinkedIn URL (v2 for Clay) | 1 if a valid email is found, 0 if not |
Mobile Phone Finder POST /v1/people/mobile-phone-finder | Mobile number(s) by LinkedIn URL or domain + name (v2 for Clay) | 5 per found phone number, 0 if none |
Reverse People Lookup POST /v1/people/reverse-lookup | Profile data for a given email address or mobile number | 0.5 per request |
Personality Analysis POST /v1/people/analysis | DISC/OCEAN profile with outreach and hiring guidance from a LinkedIn URL | 4 per request |
Lists POST /v1/lists | Exclusion lists for suppression and for retrieving more than 10,000 records | Free |
Credits GET /v1/payments/credits; all statistics/results/submissions/notify endpoints | Balance, job status, results, webhook resend | Free |
- You pay for what comes back: search results, found emails, found phones. Enrichment calls that find nothing cost 0 (Export People with Email charges 0.5 per exported person plus 0.5 per found email).
- All emails are verified in real time by BounceBan (SMTP and catch-all).
- If a job is charged but not delivered within the time limit, it is refunded automatically within up to 10 hours; refund reasons are visible on the
/submissionsendpoints. - Examples: Preview 100 people → 1 credit · People Search
size: 25→ 12.5 · Find Emails on 25 people with 18 found → 18 · Exportsize: 100with 70 found → 85 · 10 mobile lookups with 6 found → 30.
6. Rate limits and quotas
API access is included on the Builder and Scale plans. Plans without API access (Free and Starter) return 403. Search requests return up to 100 records each. How many requests you may send depends on your plan. Every response reports your limits and what is left of them, so read them from the response instead of hard-coding a number.
| Plan | What a request costs | Request limits |
|---|---|---|
| Credit plans | Credits from your balance | Requests per second |
| Unlimited plans | No credits | Requests per second, plus two longer windows (currently 4 hours and 7 days) per kind of request |
| Free and Starter | No access | Every request returns 403 |
- All API keys of one workspace share the same limits.
- On Unlimited plans the two longer windows are counted separately for each kind of request (people search, company search, job post search, export, ...). A full window on one of them does not block the others.
- Need higher limits? Contact [email protected] or use the in-app chat.
Response headers
| Header | Meaning |
|---|---|
X-Credit | Credits this request was charged, as a negative number (-0.5). Not sent when nothing was charged: an Unlimited plan, a free endpoint, no result. |
X-RateLimit-Limit-<window> | Requests allowed in that window. |
X-RateLimit-Remaining-<window> | Requests left in that window. |
X-RateLimit-Reset-<window> | Seconds until that window starts over. Sent on Unlimited plans. |
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset | The same three values for the one window that is closest to its limit. Sent on every plan. |
Retry-After | On a 429 only: seconds to wait until a request is accepted again. |
<window> is second, or the length of the window in seconds: 14400 is 4 hours, 604800 is 7 days. The windows belong to the plan and can change, so read whichever ones the response carries.
A response on an Unlimited plan (the numbers are examples):
X-RateLimit-Limit-second: 10
X-RateLimit-Remaining-second: 9
X-RateLimit-Reset-second: 1
X-RateLimit-Limit-14400: 1000
X-RateLimit-Remaining-14400: 660
X-RateLimit-Reset-14400: 4668
X-RateLimit-Limit-604800: 5000
X-RateLimit-Remaining-604800: 4090
X-RateLimit-Reset-604800: 479868When you hit a limit
The API answers 429 with Retry-After:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
{"message": "API rate limit exceeded"}- Wait
Retry-Afterseconds, then send the request again. A request sent earlier is rejected again. - A rejected request costs no credits and does not count against any window.
API rate limit exceeded for this endpointmeans one of the longer windows of an Unlimited plan is full for that kind of request. Other kinds of request still work.- On Unlimited plans every accepted request counts against its windows, even one that then fails with
400.
Other limits
- Asynchronous jobs (Find Emails by Track ID, Export People with Email): up to 500 submissions in flight per service; a further submit returns
400 too many pending requestsuntil running jobs complete. Jobs are processed 10 at a time; limits are independent per service.
| Limit | Value |
|---|---|
Results per search request (size) | 1–100 (default 25 on People Preview, 10 elsewhere) |
| Records retrievable per search via pagination | 10,000 (totalElements itself is uncapped) |
| People per Export People with Email job | max 10,000 |
| Values per filter array | max 300 |
Lookalike seed companies · keyword sources | max 5 · max 5 |
| Lists | 50 per day, 10,000 IDs each, expire after 24 h, up to 10 lists per request |
trackId (People Search → Find Emails) | single use, expires 6 hours after the search |
Search endpoints return up to 100 records per request; for bulk email work use one Export People with Email job rather than many small requests.
7. Errors
Standard HTTP status codes with a JSON body { "status", "error", ... }. Errors answered by the gateway (429, a missing or invalid API key) carry { "message": ... } instead.
| Code | Meaning | What to do |
|---|---|---|
| 400 | Invalid request (missing fields, size over the limit, too many pending async jobs) | Fix the request; for async jobs, wait for running jobs |
| 401 | Missing or invalid API key | Check the X-TOKEN header |
| 402 | Not enough credits | Top up; check GET /v1/payments/credits |
| 403 | The plan has no API access, or the trackId was auto-refunded and can't be retrieved | Upgrade the plan; for a trackId, submit the job again |
| 404 | No data / person not found / trackId used or expired | Treat as "no result" (Clay: v2 endpoints return 200 instead) |
| 409 | Export results not ready yet | Poll /statistics until state: DONE, then fetch results |
| 429 | Rate limit exceeded | Wait Retry-After seconds, then retry (see section 6) |
| 500 | Unexpected error | Retry; contact support if it persists |
Next
- API Reference — every endpoint with parameters, field-level documentation, and examples
- AI Agents — one page that teaches any AI agent to use the API correctly and cost-efficiently
- MCP Server · Clay Templates
- Support: [email protected] or the in-app chat
Updated 10 days ago