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

  • 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). Job Post Search matches differently: its default is WORD, and SMART there means every word in any order. any = OR, all = AND; both accept include/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.

EndpointUse it to…Credits
People Preview POST /v1/people/previewValidate filters and size a market with masked sample results1 per page (25–100 results per page)
People Search POST /v1/peopleSearch people (full profiles, no contact data); returns a trackId for email finding0.5 per result
Company Search POST /v1/companiesSearch 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-postsSearch job posts to find companies that are hiring for a role or ask for a tool right now0.1 per result
Find Emails by Track ID POST /v1/people/email-finderGet emails for a People Search result set (async)1 per found valid email, 0 if none
Export People with Email POST /v1/people/exportSearch + emails in one async job, up to 10,000 people, with a webhook0.5 per person + 0.5 per found valid email
Export Single Person with Email POST /v1/people/export/singleEnrich 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-finderMobile 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-lookupProfile data for a given email address or mobile number0.5 per request
Personality Analysis POST /v1/people/analysisDISC/OCEAN profile with outreach and hiring guidance from a LinkedIn URL4 per request
Lists POST /v1/listsExclusion lists for suppression and for retrieving more than 10,000 recordsFree
Credits GET /v1/payments/credits; all statistics/results/submissions/notify endpointsBalance, job status, results, webhook resendFree
  • 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

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.

PlanWhat a request costsRequest limits
Credit plansCredits from your balanceRequests per second
Unlimited plansNo creditsRequests per second, plus two longer windows (currently 4 hours and 7 days) per kind of request
Free and StarterNo accessEvery 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

HeaderMeaning
X-CreditCredits 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-ResetThe same three values for the one window that is closest to its limit. Sent on every plan.
Retry-AfterOn 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: 479868

When 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-After seconds, 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 endpoint means 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 requests until running jobs complete. Jobs are processed 10 at a time; limits are independent per service.
LimitValue
Results per search request (size)1–100 (default 25 on People Preview, 10 elsewhere)
Records retrievable per search via pagination10,000 (totalElements itself is uncapped)
People per Export People with Email jobmax 10,000
Values per filter arraymax 300
Lookalike seed companies · keyword sourcesmax 5 · max 5
Lists50 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.

CodeMeaningWhat to do
400Invalid request (missing fields, size over the limit, too many pending async jobs)Fix the request; for async jobs, wait for running jobs
401Missing or invalid API keyCheck the X-TOKEN header
402Not enough creditsTop up; check GET /v1/payments/credits
403The plan has no API access, or the trackId was auto-refunded and can't be retrievedUpgrade the plan; for a trackId, submit the job again
404No data / person not found / trackId used or expiredTreat as "no result" (Clay: v2 endpoints return 200 instead)
409Export results not ready yetPoll /statistics until state: DONE, then fetch results
429Rate limit exceededWait Retry-After seconds, then retry (see section 6)
500Unexpected errorRetry; contact support if it persists

Next



Did this page help you?