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). 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.

• 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 — [email protected] or the in-app chat.

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", ... }:

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