AI Ark

HOW in lib/aiark.py. Docs cached at reference/docs/aiark/raw/; full filter schema in reference/docs/aiark/raw/people_search.openapi.md.

Auth & config

• Base URL: https://api.ai-ark.com/api/developer-portal/v1 · Auth: header X-TOKEN (env AIARK_API_KEY; never hardcode).
• Rate limits: 5 req/s · 300/min · 18,000/hr.
• All paths CONFIRMED from docs.ai-ark.com (ReadMe .md + llms.txt, Tier-2 plain HTTP). Watch the shapes: company search = POST /v1/companies (plural), email finder = POST /v1/people/email-finder, async status/results use {trackId} path segments and the results path is /inquiries, credits = GET /v1/payments/credits. Full endpoint index at reference/docs/aiark/raw/endpoints.md; people-search schema + enums at reference/docs/aiark/raw/people_search.openapi.md.

Filter structure (critical — from the official OpenAPI spec)

People search body = {account, contact, lists, page, size}; page (0-based) and size (≤100) are required. account/contact filters take an any and/or all wrapper, each with include/exclude:

• Text filters → { "mode": "SMART"|"WORD"|"STRICT", "content": [...] } (e.g. account name, url, productAndServices, industries, technologies; contact fullName, skill, certification, title (under experience), language). The mode enum is SMART/WORD/STRICT — not "FUZZY".
• String / enum filters → bare arrays { "include": [...] } (e.g. account domain, linkedin, location, naics, technology, type; contact seniority, departmentAndFunction, socialMedia, profileBadge).
• Field names: the contact location field is contact.location (not contactLocation); titles/durations live under contact.experience.{latest,current,previous}.
• Scope a people search to a company with account.domain / account.linkedin / account.name. contact.company.{latest,current,previous} takes company UUIDs and returns contaminated rows even for a correct UUID — use the account.* fields, with root domains.
• A totalElements of ~414,000,000 means the filters were ignored (that's the whole database), not that you matched a lot. An unrecognized filter key is dropped silently behind a 200, so peek the count with size: 1 when trying a new filter shape: adding a filter must reduce it.
• Enum lists (SeniorityLevel, DepartmentAndFunction, Industry, CompanyType, ProfileBadge, Language, TimeFrame) are in the cached spec.

Response shape: top-level { content: [...people...], pageable, totalElements, totalPages, number, size, trackId, first, last, empty } — read people at response["content"]; the find-emails trackId is top-level. Errors: 404 data-not-found; 501 = socialMediaFollower on a non-LinkedIn platform (only linkedin supported).

Async flows

• Export people: export_people → trackId → poll export_statistics (DONE) → export_results (paginated).
• Find emails: run people_search (returns trackId) → find_emails(trackId,+webhook) → poll email_finder_statistics → email_finder_results. trackId is single-use, expires ~6h.

Guardrails

• mobile_phone_finder is expensive (0.332 credits/request) — use only on high-confidence matches. fetch_credit() reads your own AI Ark account and needs your own AI Ark key. Pilot small; gate bulk export/find-emails, and budget against hyreflow billing balance. A miss (no phone found) is not charged.
• In a waterfall: AI Ark leads the people_search, linkedin_profile and phone_enrichment chains.

Handoff

Sourcing + enrichment: company→people search → email/phone (export/find-emails or mobile finder) → ATS/sequencer. Discover companies first, then people.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

Base URL: server is https://api.ai-ark.com/api/developer-portal; the people-search path is /v1/people, so the full URL is .../developer-portal/v1/people. BASE_URL folds /v1 in and people_search posts to people.

The filter shapes, mode enum (SMART/WORD/STRICT), field names, and response shape are documented from the spec in the Filter structure section above.

Credit costs (live): company search 0.01 credits/result; people search 0.05 credits/result; reverse lookup 1.4 credits/request; mobile phone finder 0.332 credits/request (use only after a high-confidence match); export/email-finder 0.034 credits/email; people analysis 0.266 credits/request; polling, statistics, results = free.

Async (export_people / find_emails): launch -> trackId -> poll *_statistics until state:"DONE" -> fetch *_results (paginated). find_emails trackId is single-use, expires 6h after the people_search that generated it.

Pagination: zero-based page + size (search/export use JSON body; results browsing uses query params). Errors: 409 = you fetched results while the async job is still running (poll statistics first); 404 = profile not found; 429 = rate limit (resets every 60s; limits 5/s, 300/min, 18k/hr). Constraints: export max 10,000 results; webhooks auto-retry up to 30x (respond 200 immediately, HTTPS only).

Callable surface — lib/aiark.py

Import: from lib.aiark import AiArk → instantiate AiArk() (reads key from env). Base: https://api.ai-ark.com/api/developer-portal/v1. Generic passthrough: request(method, path, *, params, json).

• company_search(payload: dict) -> dict — POST /v1/companies — company search (CONFIRMED). Body: filters + page (0-based) + size (<=100).
• email_finder_results(track_id: str, *, page: int | None = None, size: int | None = None) -> dict — GET /v1/people/email-finder/{trackId}/inquiries — paginated results
• email_finder_statistics(track_id: str) -> dict — GET /v1/people/email-finder/{trackId}/statistics — job status (free, CONFIRMED).
• export_people(payload: dict) -> dict — POST /v1/people/export — async export (filters + page + size 1..10000 + webhook).
• export_results(track_id: str, *, page: int | None = None, size: int | None = None) -> dict — GET /v1/people/export/{trackId}/inquiries — paginated export results
• export_single(payload: dict) -> dict — POST /v1/people/export/single — export one person with email by id OR url (CONFIRMED).
• export_statistics(track_id: str) -> dict — GET /v1/people/export/{trackId}/statistics — export job status (free, CONFIRMED).
• fetch_credit() -> dict — GET /v1/payments/credits — remaining credits on your own AI Ark account (needs your own AI Ark key).
• find_emails(payload: dict) -> dict — POST /v1/people/email-finder — async email finder from a prior people_search trackId
• mobile_phone_finder(payload: dict) -> dict — POST /v1/people/mobile-phone-finder — mobile by linkedin OR domain+name (+type).
• people_analysis(payload: dict) -> dict — POST /v1/people/analysis — personality analysis from a LinkedIn profile url (CONFIRMED).
• people_search(payload: dict) -> dict — POST /v1/people — people search (CONFIRMED path). Strict nested filter structure:
• reverse_lookup(payload: dict) -> dict — POST /v1/people/reverse-lookup — look up a person by email/phone via search (CONFIRMED).
• save_list(payload: dict) -> dict — POST /v1/lists — create/update a list (up to 10k items) for use in the people_search