SOURCE_ID: import_from_ai_ark NAME: Companies and People by AI Ark CATEGORY: List Building Build a static list of people or companies from AI Ark using job, person, location, and company filters. Runs on your own AI Ark account by default, or on Floqer credits. Imported records become available to your Floqer workflows for enrichment, scoring, outreach, and the like. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_ai_ark`. POST /api/v1/sources/import_from_ai_ark/preview Scope: sources:read Returns one sample page of matching records (up to 25 people or 20 companies) plus the total match count, without creating anything. POST /api/v1/sources/import_from_ai_ark Scope: sources:write Creates the source and queues an import of matching records (up to `max_count`). Returns `source_instance_id` (the new source's UUID). The import runs asynchronously. GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. Body: { workflow_id, field_mapping, push_existing?, run? }. Source-agnostic; see concepts.txt §10. There is no dynamic-options endpoint for this source (see §6). 2. WHOSE KEY RUNS THE SEARCH use_own_key: false (default) Runs on Floqer's AI Ark access and bills Floqer credits per record imported. No connection needed. Preview is free but needs a Floqer balance of at least 1 credit (402 otherwise). Create returns 402 when the balance cannot cover `max_count` records. use_own_key: true Runs on the AI Ark account the user connected on the Floqer Connections page (connection: aiark). AI Ark bills that account; no Floqer credits are charged. Not connected → 424. Each preview uses AI Ark credits (1 for people, 2 for companies). Create checks the AI Ark balance first and returns 402 when it cannot cover the import. 3. SEARCH MODEL Every call searches ONE object, chosen by `object_type`: people People, filtered by job / person / location keys AND company-context keys (which scope the person's current company). companies Companies, filtered by company-context keys only. At least one key inside `filters` is required. Unknown keys, and people-only keys sent with `object_type: "companies"`, are rejected with 400. All validation errors come back together in one 400. 4. IMPORT LIFECYCLE (ONE-TIME ONLY) Always a one-time static import — there is no `pull_mode`, `schedule`, or recurring re-pull. max_count Records to import on create. Default 100. Whole number, 1–100000. Set it no higher than `metadata.total_results` from Preview. 5. BODY SHAPE (PREVIEW + CREATE) Preview accepts: object_type required: "people" | "companies" filters required: object with at least one filter key (§6) use_own_key optional: boolean, default false (§2) properties optional: column ids to keep on the list (§7); default = every column Create accepts all the preview fields plus: name required: display name for the new source max_count optional: default 100, max 100000 Example create body: { "name": "VPs of Sales at mid-size SaaS", "object_type": "people", "max_count": 500, "filters": { "seniority": ["vp"], "departments": ["sales"], "company_sizes": ["51-200", "201-500"], "company_industries": ["software development"], "person_locations": ["united states"] } } Preview response envelope: { "status": 200, "data": { "data": [ { "full_name": "Jane D.", "title": "VP of Sales", "company_name": "Acme", "location_country": "United States", "linkedin_url": "", ... } ], "metadata": { "total_results": 4210 } } } Rows are plain key/value objects. People preview rows carry partial data (masked last names; links, domains, and most company financials blank) — every column fills on import. Create response envelope: { "status": 201, "data": { "source_instance_id": "", "name": "VPs of Sales at mid-size SaaS", "created_at": "2026-10-27T12:00:00.000Z" } } 6. FILTER FIELDS CATALOGUE All filter keys live inside `filters`. List keys take a non-empty array of non-empty strings. Number keys take a positive number. "Fuzzy" matches similar wording; other text matches are exact (case-insensitive where noted). ──────────────────────────────────────────────────────────────────── PEOPLE ONLY ──────────────────────────────────────────────────────────────────── seniority (string[]) "owner", "founder", "c_suite", "partner", "vp", "director", "manager", "senior", "entry", "intern", "unpaid" job_titles (string[]) Current title, fuzzy. exclude_job_titles (string[]) Drop people whose current title contains any of these words. past_job_titles (string[]) Titles from previous roles, fuzzy. departments (string[]) Department or function, lowercase, e.g. "sales", "product management". skills (string[]) Listed skills, fuzzy. linkedin_urls (string[]) Full LinkedIn profile URLs. person_names (string[]) Full name, fuzzy. certifications (string[]) Certifications, fuzzy. education_degrees (string[]) Degree names, fuzzy, e.g. "MBA". education_fields (string[]) Fields of study, fuzzy. person_languages (string[]) Languages spoken, e.g. "german". person_keywords (string[]) Free text across name and organizations. person_locations (string[]) Countries, states, cities, or regions, case-insensitive, e.g. "united states", "bavaria", "paris". followers_min / followers_max (number) LinkedIn followers. connections_min / connections_max (number) LinkedIn connections. current_role_months_min / current_role_months_max (whole number) Months in a current role. Matches any role the person currently holds, including side roles. ──────────────────────────────────────────────────────────────────── COMPANY CONTEXT (people AND companies) ──────────────────────────────────────────────────────────────────── company_names (string[]) Company name, fuzzy. company_domains (string[]) Bare domains, e.g. "floqer.com". company_linkedin_urls (string[]) Full LinkedIn company URLs. company_sizes (string[]) "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001-100000000" (10,001+) company_industries (string[]) AI Ark industry names, lowercase, e.g. "retail", "software development". company_locations (string[]) Countries, states, cities, or regions, case-insensitive. company_types (string[]) "PRIVATELY_HELD", "PUBLIC_COMPANY", "SELF_OWNED", "SELF_EMPLOYED", "PARTNERSHIP", "NON_PROFIT", "EDUCATIONAL", "GOVERNMENT_AGENCY" founded_year_min / founded_year_max (number) revenue_min / revenue_max (number) Annual revenue, USD. company_keywords (string[]) Free text across name, keywords, SEO text, and description. technologies (string[]) Technologies used, e.g. "salesforce". company_naics (string[]) NAICS codes, e.g. "561740". company_languages (string[]) Operating languages, e.g. "english". funding_types (string[]) "PRE_SEED", "SEED", "SERIES_A" … "SERIES_J", "VENTURE_ROUND", "ANGEL", "PRIVATE_EQUITY", "DEBT_FINANCING", "CONVERTIBLE_NOTE", "GRANT", "CORPORATE_ROUND", "EQUITY_CROWDFUNDING", "PRODUCT_CROWDFUNDING", "SECONDARY_MARKET", "POST_IPO_EQUITY", "POST_IPO_DEBT", "POST_IPO_SECONDARY", "NON_EQUITY_ASSISTANCE", "INITIAL_COIN_OFFERING", "UNDISCLOSED", "SERIES_UNKNOWN", "FUNDING_ROUND" funding_amount_min / funding_amount_max (number) Total raised, USD. funding_last_min / funding_last_max (number) Last round, USD. funding_date_from / funding_date_to (YYYY-MM-DD) Funding date range. Min/max pairs take either side alone; an inverted pair is swapped. Values outside a listed enumeration return 400 naming the allowed set. Examples: Companies by industry, size, and country: { "object_type": "companies", "filters": { "company_industries": ["software development"], "company_sizes": ["51-200"], "company_locations": ["germany"] } } People new in role at funded startups: { "object_type": "people", "filters": { "seniority": ["director", "vp"], "current_role_months_max": 6, "funding_types": ["SERIES_A", "SERIES_B"] } } 7. OUTPUT COLUMNS (`properties`) `properties` keeps only the listed columns on the created list (order follows the catalogue). Ids outside the chosen object's catalogue return 400. Omit it to keep every column. people (commonly used): full_name, first_name, last_name, headline, title, seniority, linkedin_url, location, location_country, location_city, company_name, company_domain, company_size, company_industries, current_role_title, current_role_start_date, skills, past_titles, education_schools, statistics_network_followers_count companies (commonly used): name, domain, industry, employee_count, location, linkedin_url, founded_year, description, contact_email, contact_phone_sanitized, technologies, keywords, naics, financial_funding_type, financial_funding_total_amount, financial_revenue_annual_amount, location_headquarter_country, summary_staff_total The full catalogue is every key on a Preview row for that object. 8. HOW TO CONFIGURE END-TO-END Step 1 — Preview POST /api/v1/sources/import_from_ai_ark/preview Body: { "object_type": "people", "filters": { "seniority": ["vp"], "departments": ["sales"] } } Check `data[]` and `metadata.total_results`. Refine filters. Step 2 — Create POST /api/v1/sources/import_from_ai_ark Body: { "name": "Sales VPs", "object_type": "people", "max_count": 500, "filters": { "seniority": ["vp"], "departments": ["sales"] } } Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 2b — (Optional) Poll imported rows GET /api/v1/sources//data?page_no=1&page_size=20 Step 3 — Sync into a workflow POST /api/v1/sources//sync Example field_mapping: { "input.full_name": "full_name", "input.linkedin_url": "linkedin_url", "input.company_domain": "company_domain" } 9. KEY NOTES - Default runs on Floqer's AI Ark access and bills Floqer credits. Send `use_own_key: true` to run on the user's own AI Ark account (connect it on the Connections page first). - 424: own key selected but AI Ark is not connected, or AI Ark rejected the connected key (reconnect it). - 402: not enough AI Ark balance (own key) or Floqer credits (Floqer key) for the preview or import. - 503: Floqer's AI Ark access is temporarily unavailable; retry later or use your own key. - Records import exactly as AI Ark returns them: the imported count matches `max_count` (or the total match count, if lower). - Location, language, and industry values are matched case-insensitively; an unrecognised location matches nothing. Enumerated values (§6) are case-sensitive. 10. WHERE IT FITS DATA AI Ark's people and company database, filtered at preview / create. THIS SOURCE One-time static import of up to `max_count` people or companies. WORKFLOWS Sync to a workflow for enrichment and outreach. 11. WHEN TO USE - The user has an AI Ark account and wants lists billed to it. - People searches that need skills, certifications, education, past titles, LinkedIn network size, or tenure in role. - Company searches by funding stage, funding amount, revenue, NAICS, or technologies. For Floqer's own people and company search, see `find_people` / `find_companies`. Last updated: 2026-10-27. Reference: https://floqer.com/docs/reference