> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Ark

> Give your agents AI Ark's B2B database — 400M+ people and 70M+ company profiles, verified emails and mobile numbers, lookalike discovery, reverse lookup, and personality analysis — through agntdata.

## Overview

The AI Ark connection lets deployed agents build outbound lead lists and enrich contacts from your AI Ark account: search **people** (400M+ profiles) and **companies** (70M+ profiles, including lookalike search from up to 5 seed companies), **preview** a market for free-ish sizing before paying for full results, find **verified emails** and **mobile numbers**, run bulk **export jobs** (search + emails in one async job, up to 10,000 people, optional webhook delivery), **reverse-lookup** a full profile from an email address, and generate a **DISC/OCEAN personality analysis** with outreach guidance from a LinkedIn URL.

* **Base URL**: `https://api.agntdata.dev/v1/connections/ai-ark`
* **AI Ark auth**: an AI Ark API key. Paste it once in the dashboard — agntdata stores it encrypted and attaches it (as AI Ark's `X-TOKEN` header) to every call, so you never send it yourself.
* **MCP tools**: agents call `connection_ai_ark_*` tools, e.g. `connection_ai_ark_people_search`, `connection_ai_ark_company_search`, `connection_ai_ark_people_email_finder_by_track_id`, `connection_ai_ark_fetch_credit`.

<Note>
  **Usage spends AI Ark credits from your AI Ark account.** You pay only for what comes back: 0.5 credits per person search result, 0.1 per company result, 1 per found valid email, 5 per found mobile number, 4 per personality analysis. Previews (1 credit per page), lists, statistics, submissions, and the credit-balance check are free or near-free, and enrichment that finds nothing costs 0. Check the balance anytime with `connection_ai_ark_fetch_credit`.

  **Search → email flow uses a `trackId`.** People Search returns full profiles *without* contact data plus a `trackId`; pass that to Find Emails by Track ID within 6 hours (single use) to get verified emails for that exact result set. Email finding is asynchronous — poll the statistics endpoint until `state: DONE`, then fetch the results, or register a webhook.
</Note>

## Setup

<Steps>
  <Step title="Create an AI Ark API key">
    In AI Ark open **Settings → API Management** ([direct link](https://app.ai-ark.com/settings/api-management/dashboard)) and create a key.
  </Step>

  <Step title="Connect AI Ark">
    In the agntdata dashboard open **Integrations**, pick **AI Ark**, and paste the key.
  </Step>

  <Step title="Pick AI Ark tools">
    In an agent's Tools panel, add the tools the agent needs — for example `people_search`, `company_search`, `people_email_finder_by_track_id`, and `fetch_credit`. Search and preview tools run automatically; enrichment tools that spend meaningful credits (email finder, exports, mobile phone finder, personality analysis) ask for approval by default, and you can tune that per agent.
  </Step>
</Steps>

## Examples

### Check your credit balance

```bash theme={null}
curl "https://api.agntdata.dev/v1/connections/ai-ark/v1/payments/credits" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
```

### Search companies (German software, 51–200 employees)

```bash theme={null}
curl -X POST "https://api.agntdata.dev/v1/connections/ai-ark/v1/companies" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'
```

### Search people, then find their emails

```bash theme={null}
# 1. Search — returns profiles plus a single-use trackId (expires in 6 hours)
curl -X POST "https://api.agntdata.dev/v1/connections/ai-ark/v1/people" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "jobTitle": { "any": { "include": { "mode": "SMART", "content": ["head of sales"] } } } },
    "account": { "location": { "any": { "include": ["United States"] } } },
    "page": 0,
    "size": 10
  }'

# 2. Submit the async email-finder job with the trackId from step 1
curl -X POST "https://api.agntdata.dev/v1/connections/ai-ark/v1/people/email-finder" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "trackId": "TRACK_ID_FROM_SEARCH" }'

# 3. Poll status, then fetch results when state is DONE
curl "https://api.agntdata.dev/v1/connections/ai-ark/v1/people/email-finder/$TRACK_ID/statistics" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
curl "https://api.agntdata.dev/v1/connections/ai-ark/v1/people/email-finder/$TRACK_ID/inquiries?page=0&size=100" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
```

### Reverse-lookup a profile from an email

```bash theme={null}
curl -X POST "https://api.agntdata.dev/v1/connections/ai-ark/v1/people/reverse-lookup" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "person@example.com" }'
```

## Notes

* `page` and `size` are **required** on the search endpoints (`page` is zero-based, `size` max 100; People Preview: 25–100). Pagination retrieves up to 10,000 records per search; to go beyond, exclude already-fetched IDs with a List (`POST /v1/lists`, free, expires after 24 h).
* Text filters take a `mode`: `SMART` (AI-related concepts), `WORD` (phrase match), `STRICT` (exact). `any` = OR, `all` = AND; both accept `include`/`exclude`; max 300 values per array.
* No matches returns an empty `content` array **or** `404 data not found` — treat both as "no results", not an error.
* Rate limit: 5 requests/second per key (`429` on excess). Async jobs allow up to 500 pending submissions per service; charged-but-undelivered jobs auto-refund within 10 hours.