getaero-io/gtm-eng-skills / skills/deepline-gtm
deepline-gtm
UnverifiedGTM leads, enrichment, outreach, Plays, developer signals/Reo.dev. Providers: adyntel,affinity,ai_ark,akta,allegrow,amplemarket,apify,attention,attio,aviato,bettercontact,bigquery,bluesky,bounceban,brave,browserbase,builtwith,buyercaddy,cbinsights,clay,clickhouse,close,cloudflare,contactout,contextdev,crunchbase,crustdata-v3,customer_db,databricks,dataforseo,datagma,dealroom,deepline_ip_to_company,deepline_native,deeplineagent,deepseek,discolike,dnb,edges,emailbison,emailguard,enformion,enigma,exa,findymail,firecrawl,fireflies,firmable,forager,fullenrich,fundable,generic_http,getleads,gong,google_ads_audiences,google_workspace,govfiles,grain,hackernews,harvestapi,heyreach,hubspot,hunter,icypeas,instantly,intercom,ipqs,kaspr,kernel,kickbox,leadmagic,lemlist,limadata,linkedin_ads_audiences,luma,lusha,meerapi,meta_audiences,millionverifier,nooks,notion,openmart,opensosdata,openwebninja,outreach,parallel,particle,peopledatalabs,pitchbook,podscan,polymarket,postgres,predictleads,prospeo,quickenrich,rapidapi,….
provider-playbooks/ai-ark.md
View on GitHub<!-- skill-tool-field: account -- Nested AI Ark search-filter object, not a tool ID. -->
# AI Ark Integration Guide
## Overview
AI Ark provides company search, people search, reverse lookup, mobile phone finding, personality analysis, async export, and async email finding across enriched profiles.
**Base URL:** `https://api.ai-ark.com/api/developer-portal`
**Auth:** `X-TOKEN` header with API key.
**Rate limit:** AI Ark documents a default limit of 5 requests per second per API token. Deepline queues calls at that rate within its provider scope; the queue hint does not coordinate separate organizations that use their own tokens. If AI Ark returns HTTP 429, wait for its `Retry-After` value before retrying. [AI Ark rate-limit guidance](https://docs.ai-ark.com/docs/ai-agents).
## Pricing and credential lane
`deepline describe <tool>` and `deepline run <tool> --dry-run` show the
current Deepline rate. Managed async email finding/export settles from terminal
`statistics.found`; misses add no Deepline email charge. People Search is charged
separately. An initial hold is an estimate, not a final charge. Statistics and
results reads add no Deepline credits. With your own AI Ark credentials,
Deepline charges no tool credits; provider usage still counts against your
AI Ark account.
[AI Ark's current public contract](https://docs.ai-ark.com/docs/ai-agents)
differs from Deepline's retained settlement policy: the provider documents
1 AI Ark credit per found valid email for Find Emails, and 0.5 per exported
person plus 0.5 per found valid email for Export. These are provider units,
not Deepline credits. Use describe for the Deepline price, rather than
converting the provider's tariff.
## Filter Structure (CRITICAL)
AI Ark uses a strict nested filter structure. **Do NOT flatten or simplify these structures.** Deepline still accepts legacy aliases for existing scripts, but new code should use the AI Ark-native fields below.
### Text filters
Text filters require `{ mode, content }` inside `include`/`exclude`:
```json
{
"contact": {
"fullName": {
"any": {
"include": {
"mode": "SMART",
"content": ["Ada Lovelace"]
}
}
},
"experience": {
"current": {
"title": {
"any": {
"include": {
"mode": "SMART",
"content": ["VP", "Director", "Head of"]
}
}
}
}
}
}
}
```
### String filters
String filters use arrays directly in `include`/`exclude`:
```json
{
"contact": {
"seniority": {
"any": {
"include": ["vp", "director", "c_suite"]
}
},
"departmentAndFunction": {
"any": {
"include": ["sales", "marketing"]
}
}
}
}
```
### Company filters
Contact company filters use AI Ark company IDs, not company names. Get IDs from `ai_ark_company_search`, then use `latest`, `current`, or `previous`.
```json
{
"contact": {
"company": {
"previous": {
"any": {
"include": ["8b1c2fa5-3ceb-437e-5ef5-495bc6d34ace"]
}
}
}
}
}
```
### Large company exclusions
For a customer-company blacklist, run Company Search and collect the returned
`company_ref_id` values. Call `ai_ark_create_company_list` once with up to
10,000 `company_ref_ids` and a stable `idempotency_key`; it returns one
`company_list_ref_id`, which can be supplied to Company Search as
`company_exclusion_list_ref_ids` (up to 10 lists). The list expires after 24
hours. Deepline keeps the Ark list ID private: managed executions are isolated
to the Deepline workspace, while an active customer Ark key uses that
customer's native Ark account. Do not pass Ark company or list IDs to the list
action.
This is a **Company Search-only** feature. Ark's published People Search and
Export People APIs accept `lists.people_id.exclude`, but not
`lists.company_id.exclude`. Do not send `company_exclusion_list_ref_ids` to
People Search or Export People; direct Ark API calls have the same endpoint
limitation.
### Complete People Search example
```json
{
"page": 0,
"size": 25,
"account": {
"domain": {
"any": {
"include": ["acme.com", "example.com"]
}
}
},
"contact": {
"experience": {
"current": {
"title": {
"any": {
"include": {
"mode": "SMART",
"content": ["VP of Sales", "Head of Sales"]
}
}
}
}
},
"seniority": {
"any": {
"include": ["vp", "director"]
}
},
"location": {
"any": {
"include": ["San Francisco"]
}
}
}
}
```
### Field type reference
**Contact text filters** (use `{ mode: "SMART", content: [...] }`):
`fullName`, `skill`, `certification`, `education.degree`, `education.fieldOfStudy`, `experience.latest.title`, `experience.current.title`, `experience.previous.title`
**Contact keyword filter**:
`keyword` uses `{ include: { content: [...] } }` with optional `sources`, not a normal text operand.
**Contact string filters** (use `["value1", "value2"]`):
`socialMediaLink`, `seniority`, `location`, `linkedin`, `departmentAndFunction`, `company.latest`, `company.current`, `company.previous`, `education.school`
**Legacy aliases**:
`name` maps to `fullName`; `title` maps to `experience.current.title`; `pastCompany` maps to `company.previous`; `currentCompany` maps to `company.current`; `contactLocation` maps to `location`; `socialProfile` maps to `socialMediaLink`. Do not send an alias and its native equivalent in the same request.
**Account text filters**: `url`, `name`, `productAndServices`, `technologies`
**Account string filters**: `domain`, `linkedin`, `socialMediaLink`, `phoneNumber`, `location`, `technology`, `naics`
**Account metric filter**:
`metric` holds `employee` and `growth` arrays of bands. Every band needs `function` and at least one of `start` and `end`. A `growth` band also needs `timeFrame`; an `employee` band accepts `timeFrame`, but it does not change results. Deepline rejects any other band before calling AI Ark, because AI Ark ignores it and returns unfiltered results, or returns 0 results for a `growth` band without `timeFrame`. `account.metric` only filters: responses contain no growth or per-department metric values.
```json
{
"account": {
"metric": {
"employee": [{ "function": ["sales"], "start": 10, "end": 100 }],
"growth": [{ "function": ["sales"], "start": 20, "timeFrame": "TWELVE" }]
}
}
}
```
### Common mistakes to avoid
- Prefer `contact.experience.current.title` over legacy `contact.title`
- Prefer `contact.company.previous` with AI Ark company IDs over legacy `contact.pastCompany`
- ❌ `{ include: ["value"] }` for text filters → ✅ `{ include: { mode: "SMART", content: ["value"] } }`
- ❌ `{ include: { mode: "SMART", content: ["value"] } }` for string filters → ✅ `{ include: ["value"] }`
- ❌ `{ start: 20, timeFrame: "TWELVE" }` for a `metric.growth` band → ✅ `{ function: ["sales"], start: 20, timeFrame: "TWELVE" }`
- Do not read growth or per-department numbers from search results: `account.metric` only filters, and responses do not contain those values
## Recommended Workflow
### Prospecting
1. **Company Search** (`ai_ark_company_search`) to build account lists. Use `account` filters for firmographics, funding, technology, geography, and optional `lookalikeDomains`.
2. For a large existing-customer exclusion, make one `ai_ark_create_company_list` from the Company Search `company_ref_id` values, then use its `company_list_ref_id` in a second Company Search through `company_exclusion_list_ref_ids`.
3. **People Search** (`ai_ark_people_search`) uses its documented nested `account`, `contact`, and optional `lists.people_id` filters. It cannot accept the Company Search exclusion list; do not claim that an account blacklist carries into People Search.
### Email Finding (two paths)
**Path A — Export People (recommended for bulk verified email pulls):**
1. `ai_ark_export_people` with filters + required real HTTPS webhook → returns `trackId`.
2. With `wait_for_completion: false`, save the returned job `trackId`. Poll `ai_ark_export_statistics` until `state: "DONE"`.
3. Fetch results via `ai_ark_export_results` (paginated).
**Path B — Find Emails from Search:**
1. Run `ai_ark_people_search` first → response includes a `trackId`.
2. `ai_ark_find_emails` with that `trackId` and a `webhook` URL (single-use, expires in 6 hours).
3. With `wait_for_completion: false`, save the returned job `trackId`. Poll `ai_ark_email_finder_statistics` until `state: "DONE"`.
4. Fetch results via `ai_ark_email_finder_results` (paginated).
Both launchers require your real HTTPS webhook even when you consume results
by polling. Deepline does not provide a callback. Omitted or true
`wait_for_completion` waits and fetches results; if the wait ends while pending,
retain the returned job `trackId` and poll instead of submitting again.
Repeated statistics/results reads do not submit new email jobs. Handle webhook
duplicates by job `trackId` and result `refId`.
### Identity Resolution
- **Reverse Lookup** (`ai_ark_reverse_lookup`): Look up a person by email or phone number using the `search` field only.
### Phone Numbers
- **Mobile Phone Finder** (`ai_ark_mobile_phone_finder`): Find mobile numbers by LinkedIn URL or name + domain. Use this after you already have a high-confidence person match because it is relatively expensive (5.0/request).
### Personality Analysis
- **Personality Analysis** (`ai_ark_personality_analysis`): Analyze personality traits from a LinkedIn profile URL.
## Pagination
All search/list endpoints use zero-based pagination with `page` and `size` parameters. Search and export creation use JSON body pagination; results browsing uses query params.
## Error Handling
- **409 Conflict**: The job is still processing; Deepline returns `running` and `state: "PROCESSING"`, not a terminal email miss. Poll statistics first. Email Finder may also return readable partial pages with unfinished items in `PROCESSING`; these are not final misses.
- **404 Not Found**: Profile not found (personality analysis).
- **429 Too Many Requests**: Rate limit exceeded. Honor the response's `Retry-After` header when present; otherwise use a short exponential backoff. Do not assume a fixed 60-second reset window.
## Key Constraints
- Export People: max 10,000 results per export.
- Find Emails trackId: single-use, expires 6 hours after the People Search that generated it.
- Webhooks can be redelivered. Use a real HTTPS endpoint, respond `200` promptly, and deduplicate by job `trackId` and result `refId`.
- Undocumented endpoints in the vendor docs snapshot are intentionally not exposed here.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |