---
updatedAt: 2026-09-01T08:15:32.000Z
agentTools:
projectIndex: https://docs.ai-ark.com/llms.txt
---
# 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](/docs/mcp) and [Clay templates](/docs/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](https://app.ai-ark.com/settings/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**
```json
{
"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/company-search-1) reference page)**
```json
{
"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
* `content` holds the results; `totalElements` / `totalPages` report 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 `content` array or `404 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). `any` = OR, `all` = AND; both accept `include`/`exclude`; max 300 values per array. Enum value lists: [industries.csv](https://ai-ark.com/static/industries.csv?v=1) · [technologies.csv](https://ai-ark.com/static/technologies.csv?v=1) · [departments-and-functions.csv](https://ai-ark.com/static/departments-and-functions.csv?v=2). 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](/reference/people-preview) `POST /v2/people/preview` | Validate filters and size a market with masked sample results | **1 per page** (25–100 results per page) | |
| [People Search](/reference/people-search) `POST /v1/people` | Search people (full profiles, no contact data); returns a `trackId` for email finding | **0.5 per result** | |
| [Company Search](/reference/company-search-1) `POST /v1/companies` | Search companies; lookalike search (up to 5 seeds); Job Role filter (companies by the people they employ) | **0.1 per result** | |
| [Find Emails by Track ID](/reference/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](/reference/export-people-with-email) `POST /v1/people/export` | Search + emails in one async job, up to 10,000 people, optional webhook | **0.5 per person + 0.5 per found valid email** | |
| [Export Single Person with Email](/reference/export-single-person-with-email) \`POST /v1 | v2/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](/reference/mobile-phone-finder) \`POST /v1 | v2/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](/reference/reverse-people-lookup) `POST /v1/people/reverse-lookup` | Profile data for a given email address | **0.5 per request** | |
| [Personality Analysis](/reference/personality-analysis) `POST /v1/people/analysis` | DISC/OCEAN profile with outreach and hiring guidance from a LinkedIn URL | **4 per request** | |
| [Lists](/reference/save-list) `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 `/submissions` endpoints.
* Examples: Preview 100 people → 1 credit · People Search `size: 25` → 12.5 · Find Emails on 25 people with 18 found → 18 · Export `size: 100` with 70 found → 85 · 10 mobile lookups with 6 found → 30.
## 6. Rate limits and quotas
* **5 requests per second per API key** by default; exceeding it returns `429` — back off and retry.
* 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 requests` until running jobs complete. Jobs are processed 10 at a time; limits are independent per service.
* Accounts using 450,000+ credits per month can get custom rate limits — or the in-app chat.
| Limit | Value |
| --------------------------------------------- | -------------------------------------------------------------------------- |
| Results per search request (`size`) | max 100 (People Preview: 25–100) |
| 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 (about 500 records per second at the default rate limit); 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", ... }`:
| 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 `trackId` was auto-refunded and can't be retrieved | 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 | Back off and retry |
| 500 | Unexpected error | Retry; contact support if it persists |
## Next
* [API Reference](/reference) — every endpoint with parameters, field-level documentation, and examples
* [AI Agents](/docs/ai-agents) — one page that teaches any AI agent to use the API correctly and cost-efficiently
* [MCP Server](/docs/mcp) · [Clay Templates](/docs/clay-templates)
* Support: or the in-app chat
***