Kamata REST API
JSON over HTTPS at https://api.kamata.ai/v1. The same data the MCP server gives an assistant, for your own code.
Authentication · Reference · Examples · Results · Risk grades · Batches and pagination · Webhooks · Rate limits · Errors · Credits
Authentication
Send an API key on every request:
Authorization: Bearer sk_live_…
- Getting a key: a workspace admin creates one in the app (
https://app.kamata.ai/settings, API keys) on every plan. The key is shown once; only its hash is stored. Revoke it there at any time: a revoked key is refused on its next call. - Scopes: each route names the scope it needs. A key created on the Data plan without scopes gets
mcp:read,mcp:write,data:read,data:write. - Keys belong to one workspace. An id from another workspace answers 404, as if it did not exist.
- Keep keys server-side. They are never logged by us; do not put them in browser code.
| Scope | Allows |
|---|---|
leads:read | Read leads, contacts, searches, results and jobs |
leads:write | Approve, reject and edit leads, run searches and reveals, tags |
agents:read | Read agents, plays and competitors |
agents:write | Create and change agents |
signals:read | Read signals and search people and companies |
inbox:read | Read replies and sent email |
inbox:write | Answer and manage replies |
exclusions:read | Read exclusions |
exclusions:write | Add and remove exclusions |
imports:read | Read imports |
imports:write | Import and enrich lists |
watchlist:read | Read the watchlist |
watchlist:write | Watch and unwatch companies |
visitors:read | Read website visitors |
visitors:write | Manage visitor sites and rules |
workspace:read | Read the workspace, usage, plan and integrations |
mailboxes:read | Read mailboxes and their health |
webhooks:read | Read workspace webhook endpoints |
webhooks:write | Manage workspace webhook endpoints |
copilot:read | Ask the assistant |
mcp:read | Connect to the MCP server and use read tools |
mcp:write | MCP write tools (paid lookups and changes) |
signals:write | Create custom signals, rules and lookalike runs |
events:read | Read product events |
events:write | Send product events |
data:read | Read credits, lookups and batches |
data:write | Run lookups, verifications, enrichments and uploads (spends credits) |
mailboxes:write | |
support:write |
Reference
Every endpoint an API key can call, grouped by area and generated from the server's own routes (the same list as openapi.json). The scope column is what the key needs; outbound marks endpoints on the outbound plans (the Data plan gets 402 plan_limit).
- Emails 4
- Phones 12
- People and companies enrichment 5
- Batches and files 8
- Lookups 2
- Credits and plan 12
- Web search, news and competitors 11
- Technologies 5
- Jobs 3
- People and companies search 50
- Signals 95
- Leads 88
- Lists 21
- Agents 124
- Inbox and sending 51
- Visitors 23
- Webhooks 9
- Workspace 37
- MCP 1
- Other 1
No vendor call happens inside a request: a create answers at once (200 when it is already done, 202 while it runs) and the work continues in the background. wait_s (0–25) waits that many seconds for the answer first. Background jobs: GET /v1/jobs/:id.
Emails
Find verified work emails and verify addresses, one at a time or as a list.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/data/find-email | data:write | Find a verified work email | { person: {linkedin_url} | {full_name, domain} | {first_name, last_name, domain} } | 202, as verify-email |
POST /v1/data/verify-email | data:write | Verify one email as a lookup job | { email } | 202 { job_id, progress_id, action, status: "queued", is_sample, credits_reserved } |
POST /v1/verify/email | data:write | Verify one email address | { email, wait_s?: 0–25 (default 5) } | 200 when answered, else 202: a batch with `result` (null while it runs) |
POST /v1/verify/emails | data:write | Verify up to 5,000 email addresses | { items: string[], wait_s?, webhook_url? } | 200 when done, else 202: the batch (+ webhook_secret once) |
Phones
Look up and reverse phone numbers, check lines, find direct phones, and read their status.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/data/find-phone | data:write | Find a direct phone | { person: {linkedin_url} | {email} } | 202, as verify-email |
POST /v1/data/verify-phone | data:write | Check a phone line (mobile, landline, VoIP) | { phone } (with country code; 10 digits read as US) | 202, as verify-email |
GET /v1/phone/levels | data:read | Which lookup levels are available, and their credits | { levels: [{ level, available, reason, credits, reverse }], reverse: { available, use_accepted, use_line, default_level }, max_items } | |
POST /v1/phone/lookup | data:write | Look up one phone number | { phone, level?: "validate" | "name" | "enhanced" | "identity", default_country?, wait_s? } | 200 when answered, else 202: { id, status: queued | running | done | failed, result, cost: { credits } } |
GET /v1/phone/lookup/:id | data:read | One phone lookup: status, result and cost | the lookup | |
POST /v1/phone/lookups | data:write | Look up up to 5,000 phone numbers | { items, level?, default_country?, max_credits?, wait_s? } | 200 when done, else 202: the batch (total, done, found, no_match, failed, credits_used, progress) |
GET /v1/phone/lookups/:id | data:read | A phone lookup list: progress and a page of results | ?cursor=<index>&limit=1–1000 | the batch |
GET /v1/phone/lookups/:id/export | data:read | A phone lookup list as CSV | text/csv | |
POST /v1/phone/reverse | data:write | Who is behind one phone number | { phone, level?: "name" | "enhanced" | "identity", accept_use?, default_country?, wait_s? } | 200 / 202: the lookup, with result.match { status: matched | inferred, confidence, person, company } |
POST /v1/phone/reverses | data:write | Who is behind up to 5,000 phone numbers | { items, level?, accept_use?, default_country?, max_credits?, wait_s? } | 200 / 202: the batch |
POST /v1/verify/phone | data:write | Check one phone number | { phone, default_country?, checks?: ["format" | "line_type"], wait_s? } | 200 / 202: a batch with `result` |
POST /v1/verify/phones | data:write | Check up to 5,000 phone numbers | { items, default_country?, checks?, wait_s?, webhook_url? } | 200 / 202: the batch |
People and companies enrichment
Enrich lists of people and companies, match LinkedIn profiles, and find contacts.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/data/find-contacts | data:write | Run find_contacts as a job | { args } (the find_contacts tool arguments) | 202 { job_id, status: "queued" } |
GET /v1/data/find-contacts/:id | data:read | A find_contacts job | { id, status, rows, pending_job_ids, result_line, is_sample, reason } | |
POST /v1/data/match-linkedin | data:write | Email to LinkedIn profile | { email } | 202, as verify-email |
POST /v1/enrich/companies | data:write | Enrich up to 5,000 companies | { items: (string | {domain} | {name})[], wait_s?, webhook_url? } | 200 / 202: the batch (kind company) |
POST /v1/enrich/people | data:write | Enrich up to 5,000 people | { items: (string | {full_name | first_name + last_name, company | domain} | {email} | {linkedin_url})[], want?: ("email" | "phone" | "linkedin")[], wait_s?, webhook_url? } | 200 / 202: the batch (kind person) |
Batches and files
Upload CSV or .xlsx files, follow batch progress, page results and export them.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/enrich/batches/:id | data:read | Same as /v1/verify/batches/:id | the batch | |
POST /v1/enrich/batches/:id/download-link | data:read | Same as /v1/verify/batches/:id/download-link | { url, expires_at, format, file_name } | |
GET /v1/enrich/batches/:id/export | data:read | Same as /v1/verify/batches/:id/export | text/csv | |
POST /v1/enrich/upload | data:write | Enrich a CSV or .xlsx file | as /v1/verify/upload, with kind?: people | companies and want? | 200 / 202: the batch with `upload` |
GET /v1/verify/batches/:id | data:read | Batch progress and a page of results | ?cursor=<index>&limit=1–1000 | the batch |
POST /v1/verify/batches/:id/download-link | data:read | A one-hour download link to the results | { url, expires_at, format, file_name }: the results in the format the list came in, no auth header needed | |
GET /v1/verify/batches/:id/export | data:read | Batch results as a file | text/csv (or ?format=xlsx): the original columns plus the result columns; ?columns=simple: Status (label), Grade, Reason | |
POST /v1/verify/upload | data:write | Verify a CSV or .xlsx file (≤ 5,000 rows) | multipart `file` (+ kind?: emails | phones, default_country?, checks?, webhook_url?, wait_s?), or JSON { csv | xlsx_base64, file_name?, kind? }, or a raw text/csv body | 200 / 202: the batch with `upload` (the columns found) |
Lookups
Every paid lookup you ran, with its result and what it cost.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/data/lookups | data:read | Your lookups, newest first | ?limit=1–200 (default 50)&cursor= | { items, next_cursor } |
GET /v1/data/lookups/:id | data:read | One lookup and its result | { id, action, status, is_sample, input, result, credits: { charged, state, reason } } |
Credits and plan
Credits left, usage by key and app, plan limits and plans.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/billing | workspace:read | List billing | ||
GET /v1/billing/addons | workspace:read | Billing › addons | ||
GET /v1/billing/charge-decision | data:read | Billing › charge decision | ||
GET /v1/billing/guarantee | workspace:read | Billing › guarantee | ||
GET /v1/billing/plan-limits | workspace:read | Billing › plan limits | ||
GET /v1/credits | data:read | The credit wallet: included, rolled over, bought, used, left | { metered, included, rollover, bought, used, reserved, left, packs, next_pack, prices } | |
GET /v1/credits/usage | data:read | This month's credits by person, API key and connected app, by action, and per day | { period, included, used, reserved, left, pct, resets_at, by_principal: [{ principal, label, kind, credits, by_action }], daily: [{ day, credits }] } | |
GET /v1/data/credits | data:read | Credits left this month and the price per action | { metered, allowance, rollover, used, reserved, left, resets_at, packs, prices } | |
GET /v1/mcp-plans | public | The MCP plans and their prices (public) | { plans, mcp_url } | |
GET /v1/plan | leads:read | Your plan and its limits | the plan | |
GET /v1/plans | public | The plans and their prices (public) | { plans } | |
GET /v1/usage | workspace:read | This month's usage against your plan | the usage |
Web search, news and competitors
Search our company web index, read company news and scored competitors with their evidence.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/companies/:id/competitors | agents:read outbound | A company's scored competitors with their evidence | ?limit=1–50&include_inferred=true|false | { company, items: [{ company_id, name, domain, score, passes, inferred, why, evidence }], computed_at, stale, reason } |
GET /v1/companies/:id/news | leads:read outbound | A company's recent news, each item with its link and date | ?since=&limit=1–100 | { company, items: [{ url, title, publisher, date, source, inferred, why }], fetched_at, stale, reason } |
GET /v1/competitors | agents:read | List competitors | ||
POST /v1/competitors | agents:write | Create a competitor | ||
GET /v1/competitors/:id | agents:read | Get a competitor | ||
PATCH /v1/competitors/:id | agents:write | Update a competitor | ||
PUT /v1/competitors/:id/policy | agents:write | Update: Competitor › policy | ||
POST /v1/competitors/:id/policy/evaluate | agents:write | Competitor › policy evaluate | ||
POST /v1/competitors/discover | agents:write | Competitors › discover | ||
GET /v1/search/web | leads:read outbound | Search our company web index and news | ?q=&intent=news|competitors|company|general&company_id=|domain=&since=&limit=1–20 | { items: [{ url, title, description, date, date_kind, kind, source, inferred }], own, stale, sample, refresh_hint, reason } |
POST /v1/search/web/refresh | leads:write outbound | Look further for news or competitors (runs as a job) | { intent, q?, company_id?, domain? } | 202 { job_id, status } — progress on GET /v1/jobs/{id} |
Technologies
Companies by the technology their websites use, and site profiles from our own crawl.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/data/companies/:domain/technographics | data:read | Technologies named in a company's job posts (inferred) and, as a separate list, seen on its website | ?source=jobs|site|all | { company, source, jobs, jobs_reason, site, site_reason, credits_charged } |
GET /v1/data/tech/catalog | data:read | The technology catalog: parent categories, categories, every technology and how many sites use it now | ?category=&parent_category=&q= | { version, parents, categories, techs, sites_note } |
GET /v1/data/tech/sites | data:read | Companies whose websites use a technology (our own crawl: page code, headers, DNS, files) | ?tech=magento,stripe&match=any|all¬=&category=&parent_category=&channel=&status=current|gone|any&since=YYYY-MM-DD&country=US®ion=FL&limit=1–100&cursor= | { items: [{ domain, company, company_reason, techs: [{ tech, name, category, parent_category, channel, version, matched, status, first_seen, last_seen, inferred, evidence }] }], next_cursor, resolved, not, match, credits_charged } |
GET /v1/site-profile | signals:read | List site profile | ||
GET /v1/technographics/catalog | agents:read | Technographics › catalog |
Jobs
Job posts from companies' own public job boards and careers pages, and what one company is hiring for.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/data/companies/:domain/hiring | data:read | What a company is hiring for: open posts, posts in the last 30 days, by function and seniority, its newest posts and the boards we read | { company, read_at, reason, num_jobs, num_jobs_last_30_days, num_jobs_closed_last_30_days, by_function, by_seniority, newest, boards, credits_charged } | |
GET /v1/data/jobs | data:read | Job posts from companies' own public job boards and careers pages (our own dataset), newest first | ?q=&title=&function=sales,marketing&seniority=&tech=snowflake&country=US&state=TX&city=&remote=true|false&salary_min=&posted_since=YYYY-MM-DD&status=open|closed|any&company_domain=&company_id=&limit=1–100&cursor= | { items: [{ id, url, job_title, function, seniority, description, status, date_posted, location fields, remote, salary fields, technologies, evidence: { url, date_posted }, company, company_reasons }], next_cursor, credits_charged } |
GET /v1/data/jobs/:id | data:read | One job post with its full description | { …the post, credits_charged } |
People and companies search
Search people and companies, reveal contact details, save searches, contacts and lookalike companies.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/champions | leads:read | List champions | ||
POST /v1/champions/import | leads:write | Champions › import | ||
GET /v1/contacts | leads:read | List your contacts | ?q=&limit=&cursor= | { items, next_cursor } |
GET /v1/contacts/:id | leads:read | Get a contact | the contact | |
PUT /v1/contacts/:id/tags | leads:write | Update: Contact › tags | ||
GET /v1/data-coverage | signals:read | List data coverage | ||
GET /v1/data-quality | leads:read | List data quality | ||
GET /v1/data-requests | leads:read | List data requests | ||
POST /v1/data-requests | leads:write | Create a data request | ||
GET /v1/data-requests/:id | leads:read | Get a data request | ||
POST /v1/data-requests/:id/cancel | leads:write | Data request › cancel | ||
GET /v1/data-requests/:id/results | leads:read | Data request › results | ||
POST /v1/data-requests/:id/run | leads:write | Data request › run | ||
GET /v1/lookalikes | signals:read | List lookalike runs | { items } | |
POST /v1/lookalikes | signals:write | Find companies like your best ones (runs as a job) | { seed_domains?, seed_company_ids?, agent_id?, filters? } | 202 the run |
GET /v1/lookalikes/:id | signals:read | A lookalike run and its graded companies | ?grade=A,B&limit=&offset= | the run with its results |
GET /v1/network/insights | leads:read | Network › insights | ||
POST /v1/search/add-to-agent | leads:write outbound | Search › add to agent | ||
GET /v1/search/companies | signals:read outbound | Search companies | ?q=&industries=&sizes=&locations=&technologies=&limit=1–200&cursor= | { items, next_cursor, total } |
GET /v1/search/companies/match | signals:read outbound | Match a company by name or domain | the matched companies | |
POST /v1/search/companies/match | signals:read outbound | Match a list of companies by name or domain | the matched companies | |
GET /v1/search/database | signals:read outbound | Search › database | ||
POST /v1/search/database | signals:read outbound | Search › database | ||
GET /v1/search/detail | signals:read outbound | Search › detail | ||
GET /v1/search/export | signals:read outbound | Search results as CSV | text/csv | |
POST /v1/search/find-contact | leads:write outbound | Search › find contact | ||
POST /v1/search/find-email | leads:write outbound | Find the verified email of a search result (runs as a job) | 202 { progress_id } | |
POST /v1/search/find-phone | leads:write outbound | Find the phone of a search result (runs as a job) | 202 { progress_id } | |
GET /v1/search/leads | signals:read outbound | Find leads: people or companies with recent buying signals | ?kind=people|companies&q=&titles=&industries=&sizes=&locations=&signal_types=&since_days=1–365&limit=1–100&cursor= | { items, next_cursor } |
POST /v1/search/live | leads:write outbound | Run a live people or company search (runs as a job) | 202 { job_id, progress_id, preview } | |
POST /v1/search/live/preview | signals:read outbound | Cost preview of a live people or company search (nothing spent) | the preview | |
GET /v1/search/market | signals:read outbound | Search › market | ||
POST /v1/search/market | signals:read outbound | Search the market database (cost preview, then confirm) | without confirm: the preview; with confirm: 202 { job_id, progress_id } | |
POST /v1/search/market/preview | signals:read outbound | Cost preview of a market database search (nothing spent) | the preview | |
GET /v1/search/people | signals:read outbound | Search people | ?q=&titles=&seniority=&departments=&industries=&sizes=&locations=&limit=1–200&cursor= | { items, next_cursor, total } |
POST /v1/search/people/:id/add-to-agent | leads:write outbound | Search › people add to agent | ||
GET /v1/search/people/:id/enrich | signals:read | Search › people enrich | ||
POST /v1/search/people/:id/enrich | signals:read outbound | Search › people enrich | ||
POST /v1/search/people/:id/send-email | leads:write outbound | Search › people send email | ||
PUT /v1/search/people/:id/tags | leads:write | Update: Search › people tags | ||
POST /v1/search/push-crm | leads:write outbound | Search › push CRM | ||
POST /v1/search/reveal | leads:write outbound | Reveal emails or mobiles for search results (cost preview first) | { person_ids, fields: ["email" | "mobile"], confirm?, max_lookups? } | without confirm: the cost preview; with confirm: 202 { job_id, progress_id, preview } |
GET /v1/search/saved | leads:read | List saved searches | { items } | |
POST /v1/search/saved | leads:write | Save a search | { name, kind, filters } | 201 the saved search |
DELETE /v1/search/saved/:id | leads:write | Delete: Search › saved (one) | ||
GET /v1/search/saved/:id | leads:read | Search › saved (one) | ||
PATCH /v1/search/saved/:id | leads:write | Update: Search › saved (one) | ||
POST /v1/search/selection | signals:read outbound | Search › selection | ||
POST /v1/search/verify-email | leads:write outbound | Verify one email from search (runs as a job) | { email } | 202 { progress_id, is_sample } |
GET /v1/taxonomy/niches | agents:read | Taxonomy › niches |
Signals
Buying signals behind your leads, the signal library, custom signals, saved signal searches, multi-signal rules, and your product events.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/account-lists | signals:read | List your account lists, each with its signals and its progress | { items, limits: { accounts: { used, limit }, lists: { used, limit } } } | |
POST /v1/account-lists | signals:write outbound | Make an account list | { name } | 201 the list with created |
DELETE /v1/account-lists/:id | signals:write | Delete an account list (never "My accounts"); its accounts stay on "My accounts" | { deleted, id, name, accounts } | |
PATCH /v1/account-lists/:id | signals:write | Rename an account list (never "My accounts") | { name } | the list |
POST /v1/account-lists/:id/members | signals:write outbound | Add accounts to a list by domain: a paste or a file (checked against its signals as a job). Also needs watchlist:write | { domains } or { csv } or { rows } | 202 { added, duplicates, invalid, accounts, checking } |
PUT /v1/account-lists/:id/signal-set | signals:write outbound | Pick the signal set a list takes its signals from, or null for its own | { signal_set_id: uuid | null } | the list with checking |
PUT /v1/account-lists/:id/signals | signals:write outbound | Set the signals a list is checked against (the whole set) | { signals: [{ custom_signal_id, priority?, on? }] } | the list with checking |
PUT /v1/account-lists/:id/suggestions | signals:write | Keep finding accounts for a list (on or off) and what a suggestion must fit | { on?, filters?: { since_days, sizes, industries, locations } } | { on, filters, effective_filters, filters_from, filters_line, high_signals, new_this_week, open, per_day, running, last_run_at, reason } |
POST /v1/account-lists/:id/suggestions/watch | signals:write outbound | Watch several suggested accounts at once (refused whole past the plan). Also needs watchlist:write | { ids } or { top } | { watched, domains, accounts, checking } |
GET /v1/accounts | signals:read | List accounts: score with its parts, Why now, signals true, newest evidence, owner and list | ?list_id=&q=&sort=added|score&tab=watching|ruled_out&limit=&cursor= | { items, next_cursor, total, list, progress, tabs } |
DELETE /v1/accounts/:id | signals:write | Take an account off its list; off "My accounts" it leaves every list and the watchlist. Also needs watchlist:write | { removed, domain, everywhere, lists, accounts } | |
GET /v1/accounts/:id | signals:read | One account: its score and Why now, a line per signal with its evidence link and date or the reason it has none, and what we read | the account with lines and reads | |
PATCH /v1/accounts/:id | signals:write outbound | Correct an account's domain. Also needs watchlist:write | { domain } | the account with lines |
POST /v1/accounts/:id/answers/:customSignalId/feedback | signals:write | "Not right?": rate the answer one signal gave for this account (good, bad, or null to clear) | { verdict, reason? } | { custom_signal_id, rating, reason, rated_at, line } |
POST /v1/accounts/:id/lead | leads:write outbound | Make a lead from an account (queued as a job; every lead check applies) | 202 { queued, via, evidence, line } | |
POST /v1/accounts/:id/reject | signals:write | Reject a suggested account: never suggested again; names the filter that fixes the reason | { reason, note? } | { rejected, id, domain, reason, reason_label, suggest_edit, company_size, proposed_filters, filters } |
POST /v1/accounts/:id/watch | signals:write outbound | Watch a suggested account: it joins its list and the watchlist and is checked against the list's signals. Also needs watchlist:write | { watched, id, domain, list_id, accounts, already, checking } | |
GET /v1/accounts/outcomes | signals:read | Your won and lost deals on file (add them with POST /v1/imports kind "outcomes") | ?limit= | { won, lost, items, empty_reason } |
POST /v1/accounts/outcomes | signals:write | Add won and lost deals one by one (then "My accounts" is tested again) | { deals: [{ domain, outcome: won | lost, date: YYYY-MM-DD, value?, currency? }] (≤ 5,000) } | { added, invalid: [{ index, reason }], notes, testing } (each deal kept counts against the monthly import allowance) |
GET /v1/accounts/overview | signals:read | One of your accounts by its domain: score, Why now with quotes, a line per signal, what we read | ?domain=acme.com | the account as GET /v1/accounts/:id; 404 when the domain is not one of your accounts |
GET /v1/accounts/priorities | signals:read | Today's top accounts: the Accounts screen's order, only those with a score, each Why now fact with its date, link and quote | ?limit= (1-25, default 10) | { items (the account rows of GET /v1/accounts, story.clauses with quote and quote_url), reason, list, tabs, progress } |
GET /v1/custom-signals | signals:read | List custom signals | { items, limit, library_limit, room: { used, limit }, tries_left_today } | |
POST /v1/custom-signals | signals:write | Describe a custom signal in one sentence (built as a job) | { description, agent_id?, auto_lead?, leads_per_day?, scope?, list_ids? } | 202 { id, status: "compiling", progress_id }; a signal limited to account lists adds { scope: "lists", list_ids, scope_note? } |
DELETE /v1/custom-signals/:id | signals:write | Delete a custom signal | ||
GET /v1/custom-signals/:id | signals:read | A custom signal, its latest hits and runs | the custom signal | |
PATCH /v1/custom-signals/:id | signals:write | Update a custom signal | ||
POST /v1/custom-signals/:id/activate | signals:write | Custom signal › activate | ||
PUT /v1/custom-signals/:id/alerts | signals:write | Set where a signal sends its matches, or mute it | { muted?, deliver?: { slack?, email?, webhook?, when?: "at_once" | "morning" } | null } | the custom signal with muted and deliver |
GET /v1/custom-signals/:id/backtest/deals | signals:read | The won or lost deals a signal came before, each with its dated proof | ?outcome=won|lost&list_id= | { outcome, with, total, excluded, reason, items: [{ domain, name, occurred_on, value, currency, proof: { url, date, title, quote } }] } |
GET /v1/custom-signals/:id/hits | signals:read | Custom signal › hits | ||
POST /v1/custom-signals/:id/hits/:customSignalHitId/feedback | signals:write | Custom signal › hits feedback | ||
POST /v1/custom-signals/:id/improve | signals:write | Custom signal › improve | ||
GET /v1/custom-signals/:id/outcomes | signals:read | One signal's results and suggested priority | { custom_signal_id, leads, sent, meetings, line, reason, own, network, suggested, window } | |
POST /v1/custom-signals/:id/pause | signals:write | Custom signal › pause | ||
GET /v1/custom-signals/backtest | signals:read | What predicts wins: per signal, the won and lost deals it came before and its matches in 12 months | ?list_id= | { list, deals: { won, lost }, empty_reason, progress, coverage_line, items: [{ custom_signal_id, name, priority, wins, losses, matches, suggested, limit, quiet }] } |
POST /v1/custom-signals/backtest | signals:write | Test signals on the last 12 months of a list's accounts (runs as a job) | { list_id? } ("My accounts" when left out) | 202 { status: "queued" | "running", progress_id, list_id }; 200 { status: "done" } when the same test already ran today; 409 when no signal is on, paused or saved |
GET /v1/custom-signals/outcomes | signals:read | Signal results: per signal the leads, sends, positive replies, meetings and wins in the latest window, and a suggested priority | { window, computed_at, needed_sends, average, network: { on, reason }, items: [{ custom_signal_id, leads, sent, positive_replies, meetings, won, line, reason, own, network, suggested }] } | |
POST /v1/custom-signals/tryouts | signals:write | Try up to five sentences before anything is saved (read and counted as a job) | { sentences, context? } | 202 { items: [{ sentence, id, status: "queued", progress_id } | { sentence, existing_id, existing_status }], tries_left_today } |
GET /v1/custom-signals/tryouts/:id | signals:read | A tried sentence: how it was read, its 30-day count and example companies | the tryout | |
GET /v1/custom-signals/tryouts/:id/backtest | signals:read | A tried sentence's history test: matches in 12 months and the wins it came before | { tryout_id, progress, deals, result, result_reason } | |
POST /v1/custom-signals/tryouts/:id/backtest | signals:write | Test a tried sentence on the last 12 months (runs as a job) | 202 { status, progress_id, tryout_id } | |
GET /v1/custom-signals/tryouts/:id/backtest/deals | signals:read | The won or lost deals a tried sentence came before, each with its dated proof | ?outcome=won|lost | { outcome, with, total, items } |
POST /v1/custom-signals/tryouts/:id/keep | signals:write | Turn a tried sentence on as a signal | { auto_lead?, leads_per_day?, priority?, agent_id?, scope?, list_ids? } | 201 the custom signal with created and first_run_job_id |
GET /v1/events | events:read | List product events | ?account=&event=&limit=&cursor= | { items, next_cursor } |
POST /v1/events | events:write | Send product events (one or up to 500) | { account_domain | company, user_email?, event, properties?, occurred_at? } or { events: [...] } | 202 the accepted count |
GET /v1/events/:id | agents:read | Get an event | ||
PATCH /v1/events/:id | agents:write outbound | Update an event | ||
GET /v1/events/:id/registrants | agents:read | Event › registrants | ||
GET /v1/events/summary | events:read | Product events in the last 30 days | { events, today, per_day } | |
POST /v1/extension/add | watchlist:write | Extension › add | ||
GET /v1/extension/lookup | signals:read | Extension › lookup | ||
GET /v1/reddit | workspace:read | List Reddit | ||
GET /v1/reddit/matches | leads:read | Reddit › matches | ||
GET /v1/reddit/matches/:id | leads:read | Reddit › matches (one) | ||
GET /v1/reddit/plans | workspace:read | Reddit › plans | ||
GET /v1/reddit/posted | inbox:read | Reddit › posted | ||
GET /v1/reddit/replies | workspace:read | Reddit › replies | ||
GET /v1/signal-alerts | signals:read | List signal alerts with where each went | ?custom_signal_id=&limit=&cursor= | { items, next_cursor } |
POST /v1/signal-alerts/retry | signals:write | Send failed signal alerts again (sent by a job) | { channel: "slack" | "webhook" } | 202 { channel, retried, status: "queued" } |
GET /v1/signal-alerts/status | signals:read | Which alert channels are on the plan, connected or failing | { slack, webhook, email, morning_hour, timezone } | |
GET /v1/signal-jobs/:id | signals:read | Get a signal job | ||
GET /v1/signal-library | signals:read | List signal library | ||
POST /v1/signal-library/:key/enable | signals:write | Signal library › enable | ||
GET /v1/signal-library/outcomes | signals:read | The network's suggested priority per library signal (only while network learning is on) | { network: { on, reason }, items: [{ key, suggested }] } | |
GET /v1/signal-rules | signals:read | List signal rules | ||
POST /v1/signal-rules | signals:write | Create a signal rule | ||
DELETE /v1/signal-rules/:id | signals:write | Delete a signal rule | ||
GET /v1/signal-rules/:id | signals:read | Get a signal rule | ||
PATCH /v1/signal-rules/:id | signals:write | Update a signal rule | ||
GET /v1/signal-searches | signals:read | List signal searches | ||
POST /v1/signal-searches | signals:write | Create a signal searche | ||
DELETE /v1/signal-searches/:id | signals:write | Delete a signal searche | ||
GET /v1/signal-searches/:id | signals:read | Get a signal searche | ||
PATCH /v1/signal-searches/:id | signals:write | Update a signal searche | ||
GET /v1/signal-searches/:id/results | signals:read | Signal searche › results | ||
POST /v1/signal-searches/:id/results/:signalSearchResultId/reject | signals:write | Signal searche › results reject | ||
POST /v1/signal-searches/:id/results/add-to-agent | leads:write outbound | Signal searche › results add to agent | ||
POST /v1/signal-searches/:id/run | signals:write | Signal searche › run | ||
POST /v1/signal-searches/estimate | signals:read | Signal searches › estimate | ||
GET /v1/signal-searches/options | signals:read | Signal searches › options | ||
GET /v1/signal-sets | signals:read | List your signal sets, each with its signals and the lists that use it | { items, room: { used, limit } } ("All signals" counts as the first set) | |
POST /v1/signal-sets | signals:write | Make a signal set | { name, signals?: [{ custom_signal_id, priority? }] } | 201 the set |
DELETE /v1/signal-sets/:id | signals:write | Delete a signal set; its lists keep the signals they have | { deleted, id, name, lists } | |
GET /v1/signal-sets/:id | signals:read | One signal set: its signals with the set's priority and the lists that use it | the set | |
PATCH /v1/signal-sets/:id | signals:write outbound | Rename a signal set or replace its signals; every list on it follows (new signals are checked as a job) | { name?, signals? } | the set with checking |
GET /v1/signal-sources | signals:read | List signal sources | ||
GET /v1/signal-suggestions | signals:read | List signal suggestions | ||
POST /v1/signal-suggestions/:id/add | signals:write | Signal suggestion › add | ||
POST /v1/signal-suggestions/:id/dismiss | signals:write | Signal suggestion › dismiss | ||
POST /v1/signal-suggestions/refresh | signals:write | Signal suggestions › refresh | ||
GET /v1/signals | signals:read | Buying signals behind your leads | ?kind=&since_days=&agent_id= | { items } |
GET /v1/signals/:id | signals:read | Get a signal with its evidence link and date | the signal | |
GET /v1/signals/catalog | signals:read | Signals › catalog | ||
PATCH /v1/signals/catalog | agents:write | Update: Signals › catalog | ||
GET /v1/site-monitors | watchlist:read | List site monitors |
Leads
Read leads with their evidence, approve, reject and edit drafts, tags, tasks, results and exports.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/benchmarks | leads:read | List benchmarks | ||
GET /v1/booking/experiments | leads:read | Booking › experiments | ||
GET /v1/booking/funnel | leads:read | Booking › funnel | ||
GET /v1/deliveries | leads:read | List deliveries | ||
GET /v1/deliveries/:id/csv | leads:read | Delivery › CSV | ||
GET /v1/export/leads.csv | leads:read | Leads as CSV | text/csv | |
POST /v1/lead-stops/:id/undo | leads:write | Lead stop › undo | ||
GET /v1/leads | leads:read | List leads | ?limit=&cursor=&agent_id=&status=&feed_date=today|YYYY-MM-DD&signal_type=&q= | { items, next_cursor, is_sample? } |
GET /v1/leads/:id | leads:read | Get a lead: company, person, evidence, fit and draft | the lead | |
POST /v1/leads/:id/approve | leads:write outbound | Approve a lead for sending | { id, status: "approved" | "writing", reason? } ("writing": approved once its email passes review) | |
POST /v1/leads/:id/contact | leads:write | Lead › contact | ||
POST /v1/leads/:id/credit | leads:write | Lead › credit | ||
POST /v1/leads/:id/draft-feedback | leads:write | Lead › draft feedback | ||
POST /v1/leads/:id/drafts | leads:write | Save an edited draft | { subject, body, followup_1, followup_2 } | 201 the draft version |
GET /v1/leads/:id/emails | leads:read | Lead › emails | ||
PUT /v1/leads/:id/emails/:n | leads:write | Update: Lead › emails (one) | ||
POST /v1/leads/:id/emails/:n/advice | leads:write | Lead › emails advice | ||
POST /v1/leads/:id/emails/:n/hold | leads:write | Lead › emails hold | ||
POST /v1/leads/:id/emails/:n/resume | leads:write | Lead › emails resume | ||
POST /v1/leads/:id/emails/:n/rewrite | leads:write | Lead › emails rewrite | ||
PATCH /v1/leads/:id/emails/:n/schedule | leads:write | Update: Lead › emails schedule | ||
POST /v1/leads/:id/emails/own | leads:write outbound | Lead › emails own | ||
POST /v1/leads/:id/feedback | leads:write | Lead › feedback | ||
POST /v1/leads/:id/linkedin-match | leads:write | Lead › LinkedIn match | ||
GET /v1/leads/:id/next-action | leads:read | Lead › next action | ||
POST /v1/leads/:id/next-action | leads:write | Lead › next action | ||
GET /v1/leads/:id/notes | leads:read | Lead › notes | ||
POST /v1/leads/:id/notes | leads:write | Lead › notes | ||
POST /v1/leads/:id/push-crm | leads:write | Lead › push CRM | ||
POST /v1/leads/:id/redraft | leads:write | Lead › redraft | ||
POST /v1/leads/:id/reject | leads:write | Reject a lead | { reason?, exclude_company? } | { id, status: "rejected" | "stopped", excluded_domain } |
POST /v1/leads/:id/rules/:ruleId/correct | leads:write | Lead › rules correct | ||
GET /v1/leads/:id/send | leads:read | Lead › send | ||
POST /v1/leads/:id/send | leads:write outbound | Lead › send | ||
POST /v1/leads/:id/send-now | leads:write | Lead › send now | ||
GET /v1/leads/:id/sequence | leads:read | Lead › sequence | ||
DELETE /v1/leads/:id/sequence/override | leads:write | Delete: Lead › sequence override | ||
PUT /v1/leads/:id/sequence/override | leads:write | Update: Lead › sequence override | ||
POST /v1/leads/:id/stop | leads:write | Lead › stop | ||
PUT /v1/leads/:id/tags | leads:write | Update: Lead › tags | ||
GET /v1/leads/:id/timeline | leads:read | Lead › timeline | ||
POST /v1/leads/:id/unapprove | leads:write | Lead › unapprove | ||
GET /v1/leads/:id/voice | leads:read | Lead › voice | ||
GET /v1/leads/:id/voice/audio | leads:read | Lead › voice audio | ||
POST /v1/leads/:id/voice/preview | leads:write outbound | Lead › voice preview | ||
DELETE /v1/leads/:id/won | leads:write | Delete: Lead › won | ||
GET /v1/leads/:id/won | leads:read | Lead › won | ||
POST /v1/leads/:id/won | leads:write | Lead › won | ||
GET /v1/leads/:leadId/conversion | leads:read | Lead › conversion | ||
PATCH /v1/leads/:leadId/followups/:n | leads:write | Update: Lead › followups (one) | ||
POST /v1/leads/:leadId/followups/:n/cancel | leads:write | Lead › followups cancel | ||
POST /v1/leads/:leadId/followups/:n/hold | leads:write | Lead › followups hold | ||
POST /v1/leads/:leadId/followups/:n/resume | leads:write | Lead › followups resume | ||
POST /v1/leads/:leadId/linkedin | leads:write outbound | Lead › LinkedIn | ||
POST /v1/leads/bulk-approve | leads:write outbound | Approve many leads at once | { lead_ids } or { filter: { min_fit, feed_date?, agent_id? } } | 202 { job_id, accepted, skipped } |
GET /v1/leads/counters | leads:read | Leads › counters | ||
GET /v1/leads/stage-counts | leads:read | Leads › stage counts | ||
GET /v1/leads/view-counts | leads:read | Leads › view counts | ||
POST /v1/learning/:id/undo | agents:write | Learning › undo | ||
GET /v1/meetings | leads:read | List meetings | ||
POST /v1/meetings/:id/outcome | leads:write | Meeting › outcome | ||
GET /v1/queued | leads:read | Queued first emails: scheduled, not scheduled yet, on hold | ?state=all|scheduled|not_scheduled|held&agent_id=&cursor= | { items, counts: { waiting, scheduled, not_scheduled, held }, next_cursor } |
POST /v1/queued/bulk | leads:write | Hold, resume or send back to review | { lead_ids, action: hold | resume | to_review } | { done, skipped } |
POST /v1/queued/schedule | leads:write outbound | Queued › schedule | ||
GET /v1/results | leads:read | List results | ||
GET /v1/results/channels | leads:read | Results › channels | ||
GET /v1/results/daily | leads:read | Results › daily | ||
GET /v1/results/series | leads:read | Results › series | ||
GET /v1/results/signal-value | leads:read | Results › signal value | ||
GET /v1/results/weekly | leads:read | Results › weekly | ||
GET /v1/stats/today | leads:read | Today's numbers | ?period=24h|7d|30d&agent_id= | the stats |
GET /v1/tag-rules | leads:read | List tag rules | ||
POST /v1/tag-rules | leads:write outbound | Create a tag rule | ||
DELETE /v1/tag-rules/:id | leads:write | Delete a tag rule | ||
GET /v1/tag-rules/:id | leads:read | Get a tag rule | ||
PATCH /v1/tag-rules/:id | leads:write outbound | Update a tag rule | ||
GET /v1/tags | leads:read | List tags | { items, colors } | |
POST /v1/tags | leads:write | Create a tag | { name, color? } | 201 the tag |
DELETE /v1/tags/:id | leads:write | Delete a tag | ||
PATCH /v1/tags/:id | leads:write | Update a tag | ||
POST /v1/tags/:id/contacts | leads:write | Tag › contacts | ||
POST /v1/tags/:id/leads | leads:write | Tag › leads | ||
POST /v1/tags/:id/people | leads:write | Tag › people | ||
GET /v1/tasks | leads:read | List tasks | ||
POST /v1/tasks/:id/done | leads:write | Task › done | ||
POST /v1/tasks/:id/skip | leads:write | Task › skip | ||
GET /v1/tests | leads:read | List tests | ||
GET /v1/whats-working | leads:read | List what's working |
Lists
Watchlist, imports and exclusions.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/exclusions | exclusions:read | List exclusions | ?kind=&q=&limit=&cursor= | { items, next_cursor, total } |
POST /v1/exclusions | exclusions:write | Exclude domains or emails (never contacted) | { items: [{ kind, value, reason }] } or { domains, emails, reason } | { added, duplicates, invalid, stopped_leads } |
DELETE /v1/exclusions/:id | exclusions:write | Delete an exclusion | ||
PATCH /v1/exclusions/:id | exclusions:write | Update an exclusion | ||
POST /v1/exclusions/check | exclusions:read | Exclusions › check | ||
GET /v1/exclusions/crm | exclusions:read | Exclusions › CRM | ||
GET /v1/exclusions/export | exclusions:read | Exclusions as CSV | text/csv | |
GET /v1/exclusions/summary | exclusions:read | Exclusions › summary | ||
GET /v1/imports | imports:read | List imports | ?kind=&limit=&cursor= | { items, next_cursor } |
POST /v1/imports | imports:write outbound | Import a list (CSV upload or rows) | multipart (kind: work | watchlist | exclusions | seeds | outcomes, agent_id?, file), raw text/csv + ?kind=, or JSON { kind, csv | rows } | 202 the import |
GET /v1/imports/:id | imports:read | Get an import and its summary | the import | |
POST /v1/imports/:id/enrich | imports:write | Enrich an import's rows (estimate first with dry_run) | { fields, agent_id?, row_ids?, dry_run? } | dry_run: { estimate }; else 202 the run |
GET /v1/imports/:id/rows | imports:read | An import's rows | ?limit=&cursor=&row_bucket= | { items, next_cursor } |
POST /v1/switch/leads | imports:write | Switch › leads | ||
POST /v1/switch/leads/preview | imports:write | Switch › leads preview | ||
POST /v1/switch/sequence | agents:write | Switch › sequence | ||
GET /v1/switch/sequences | agents:read | Switch › sequences | ||
GET /v1/switch/sequences/:id | agents:read | Switch › sequences (one) | ||
GET /v1/watchlist | watchlist:read | List watched companies | ?limit=&cursor=&q=&agent_id= | { items, next_cursor, total } |
POST /v1/watchlist | watchlist:write outbound | Watch companies by domain | { domains, agent_id } | { added, duplicates, invalid } |
DELETE /v1/watchlist/:id | watchlist:write | Stop watching a company | { ok: true } |
Agents
Agents: who to target, which signals to watch, plays, personas and the content library.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/agents | agents:read | List agents | { items } | |
POST /v1/agents | agents:write outbound | Create an agent from a domain or one sentence | { input, name? } | 201 the agent (its profile builds in a job) |
POST /v1/agents/:agentId/build | agents:write outbound | Agent › build | ||
PUT /v1/agents/:agentId/lane | agents:write | Update: Agent › lane | ||
GET /v1/agents/:agentId/linkedin/intros | agents:read | Agent › LinkedIn intros | ||
POST /v1/agents/:agentId/linkedin/intros | agents:write outbound | Agent › LinkedIn intros | ||
DELETE /v1/agents/:agentId/linkedin/intros/:id | agents:write | Delete: Agent › LinkedIn intros (one) | ||
GET /v1/agents/:agentId/linkedin/intros/:id | agents:read | Agent › LinkedIn intros (one) | ||
GET /v1/agents/:agentId/linkedin/network | agents:read | Agent › LinkedIn network | ||
POST /v1/agents/:agentId/linkedin/network/scan | agents:write outbound | Agent › LinkedIn network scan | ||
GET /v1/agents/:agentId/linkedin/searches | agents:read | Agent › LinkedIn searches | ||
POST /v1/agents/:agentId/linkedin/searches | agents:write outbound | Agent › LinkedIn searches | ||
DELETE /v1/agents/:agentId/linkedin/searches/:id | agents:write | Delete: Agent › LinkedIn searches (one) | ||
POST /v1/agents/:agentId/niche-packs/:key/apply | agents:write | Agent › niche packs apply | ||
GET /v1/agents/:agentId/pods | agents:read | Agent › pods | ||
GET /v1/agents/:agentId/pods/:id | agents:read | Agent › pods (one) | ||
PATCH /v1/agents/:agentId/pods/:id | agents:write | Update: Agent › pods (one) | ||
POST /v1/agents/:agentId/pods/:id/approve | agents:write | Agent › pods approve | ||
POST /v1/agents/:agentId/pods/:id/dismiss | agents:write | Agent › pods dismiss | ||
POST /v1/agents/:agentId/pods/:id/messaging/regenerate | agents:write | Agent › pods messaging regenerate | ||
POST /v1/agents/:agentId/pods/:id/pause | agents:write | Agent › pods pause | ||
POST /v1/agents/:agentId/pods/:id/resume | agents:write | Agent › pods resume | ||
GET /v1/agents/:agentId/pods/:id/signals | agents:read | Agent › pods signals | ||
GET /v1/agents/:agentId/pods/:id/style | agents:read | Agent › pods style | ||
GET /v1/agents/:agentId/pods/:id/whats-working | agents:read | Agent › pods what's working | ||
GET /v1/agents/:agentId/pods/history | agents:read | Agent › pods history | ||
POST /v1/agents/:agentId/pods/ideate | agents:write | Agent › pods ideate | ||
POST /v1/agents/:agentId/positioning/variants/:positioningVariantId/approve | agents:write | Agent › positioning variants approve | ||
POST /v1/agents/:agentId/positioning/variants/:positioningVariantId/dismiss | agents:write | Agent › positioning variants dismiss | ||
GET /v1/agents/:agentId/seeds | agents:read | Agent › seeds | ||
POST /v1/agents/:agentId/seeds | agents:write | Agent › seeds | ||
DELETE /v1/agents/:agentId/seeds/:seedId | agents:write | Delete: Agent › seeds (one) | ||
GET /v1/agents/:agentId/segments | agents:read | Agent › segments | ||
PATCH /v1/agents/:agentId/segments/:id | agents:write | Update: Agent › segments (one) | ||
POST /v1/agents/:agentId/segments/:id/approve | agents:write | Agent › segments approve | ||
POST /v1/agents/:agentId/segments/:id/dismiss | agents:write | Agent › segments dismiss | ||
POST /v1/agents/:agentId/segments/:id/off | agents:write | Agent › segments off | ||
POST /v1/agents/:agentId/segments/:id/on | agents:write | Agent › segments on | ||
POST /v1/agents/:agentId/segments/:id/unapprove | agents:write | Agent › segments unapprove | ||
DELETE /v1/agents/:id | agents:write | Delete an agent | { ok: true } | |
GET /v1/agents/:id | agents:read | Get an agent | the agent | |
PATCH /v1/agents/:id | agents:write | Update an agent | any of { name, offer, icp, topics, signal_kinds, daily_volume, mode, review_mode, tone } | the agent |
GET /v1/agents/:id/activity | agents:read | Agent › activity | ||
GET /v1/agents/:id/autopilot | agents:read | Agent › autopilot | ||
PUT /v1/agents/:id/autopilot | agents:write outbound | Update: Agent › autopilot | ||
POST /v1/agents/:id/autopilot/dry-run | agents:write | Agent › autopilot dry run | ||
GET /v1/agents/:id/description | agents:read | Agent › description | ||
PUT /v1/agents/:id/description | agents:write | Update: Agent › description | ||
POST /v1/agents/:id/duplicate | agents:write outbound | Agent › duplicate | ||
GET /v1/agents/:id/events | agents:read | Agent › events | ||
POST /v1/agents/:id/events | agents:write outbound | Agent › events | ||
POST /v1/agents/:id/events/import | agents:write | Agent › events import | ||
POST /v1/agents/:id/icp/confirm | agents:write | Agent › ICP confirm | ||
POST /v1/agents/:id/icp/proposal | agents:write | Agent › ICP proposal | ||
GET /v1/agents/:id/learning | agents:read | Agent › learning | ||
GET /v1/agents/:id/linkedin-engagement | workspace:read | Agent › LinkedIn engagement | ||
GET /v1/agents/:id/list-syncs | agents:read | Agent › list syncs | ||
GET /v1/agents/:id/needs | agents:read | Agent › needs | ||
PUT /v1/agents/:id/needs | agents:write | Update: Agent › needs | ||
GET /v1/agents/:id/overview | agents:read | Agent › overview | ||
POST /v1/agents/:id/pause | agents:write | Agent › pause | ||
GET /v1/agents/:id/personas | agents:read | Agent › personas | ||
POST /v1/agents/:id/personas | agents:write | Agent › personas | ||
POST /v1/agents/:id/personas/generate | agents:write | Agent › personas generate | ||
GET /v1/agents/:id/plan | leads:read | Agent › plan | ||
GET /v1/agents/:id/plays | agents:read | Agent › plays | ||
PATCH /v1/agents/:id/plays/:playId | agents:write outbound | Update: Agent › plays (one) | ||
GET /v1/agents/:id/positioning | agents:read | Agent › positioning | ||
POST /v1/agents/:id/positioning/check | agents:write | Agent › positioning check | ||
GET /v1/agents/:id/preview | agents:read | Agent › preview | ||
POST /v1/agents/:id/resume | agents:write outbound | Agent › resume | ||
GET /v1/agents/:id/sequence | agents:read | Agent › sequence | ||
PUT /v1/agents/:id/sequence | agents:write | Update: Agent › sequence | ||
GET /v1/agents/:id/sequence/arms | agents:read | Agent › sequence arms | ||
POST /v1/agents/:id/sequence/arms | agents:write | Agent › sequence arms | ||
PUT /v1/agents/:id/sequence/arms/:sequenceArmId | agents:write | Update: Agent › sequence arms (one) | ||
POST /v1/agents/:id/sequence/arms/setup | agents:write | Agent › sequence arms setup | ||
POST /v1/agents/:id/sequence/preview | leads:write | Agent › sequence preview | ||
GET /v1/agents/:id/sequence/stats | agents:read | Agent › sequence stats | ||
GET /v1/agents/:id/sequence/steps/:stepId/leads | leads:read | Agent › sequence steps leads | ||
POST /v1/agents/:id/signal-kinds/drop | agents:write | Agent › signal kinds drop | ||
GET /v1/agents/:id/technographics | agents:read | Agent › technographics | ||
PATCH /v1/agents/:id/voice | agents:write outbound | Update: Agent › voice | ||
GET /v1/agents/:id/voice/email | agents:read | Agent › voice email | ||
PATCH /v1/agents/:id/voice/email | agents:write outbound | Update: Agent › voice email | ||
PUT /v1/agents/:id/writing | agents:write | Update: Agent › writing | ||
GET /v1/audience/customers | agents:read | Audience › customers | ||
GET /v1/audience/pods | agents:read | Audience › pods | ||
GET /v1/audience/pods/:id | agents:read | Audience › pods (one) | ||
POST /v1/audience/pods/:id/approve | agents:write | Audience › pods approve | ||
POST /v1/audience/pods/:id/dismiss | agents:write | Audience › pods dismiss | ||
POST /v1/audience/pods/:id/unapprove | agents:write | Audience › pods unapprove | ||
GET /v1/audience/profiles | agents:read | Audience › profiles | ||
POST /v1/audience/refresh | agents:write | Audience › refresh | ||
PATCH /v1/event-guests/:id | agents:write | Update an event guest | ||
GET /v1/library | agents:read | List library | ||
POST /v1/library/offers | agents:write | Library › offers | ||
DELETE /v1/library/offers/:id | agents:write | Delete: Library › offers (one) | ||
PATCH /v1/library/offers/:id | agents:write | Update: Library › offers (one) | ||
POST /v1/library/styles | agents:write | Library › styles | ||
DELETE /v1/library/styles/:id | agents:write | Delete: Library › styles (one) | ||
PATCH /v1/library/styles/:id | agents:write | Update: Library › styles (one) | ||
POST /v1/list-syncs | agents:write | Create a list sync | ||
DELETE /v1/list-syncs/:id | agents:write | Delete a list sync | ||
GET /v1/list-syncs/:id | agents:read | Get a list sync | ||
PATCH /v1/list-syncs/:id | agents:write | Update a list sync | ||
POST /v1/list-syncs/:id/rows | agents:write | List sync › rows | ||
POST /v1/list-syncs/:id/run | agents:write | List sync › run | ||
GET /v1/niche-packs | agents:read | List niche packs | ||
DELETE /v1/personas/:personaId | agents:write | Delete a persona | ||
PATCH /v1/personas/:personaId | agents:write | Update a persona | ||
GET /v1/plays | agents:read | List plays | ||
PUT /v1/pods/settings | agents:write | Update: Pods › settings | ||
GET /v1/scale/copy | agents:read | Scale › copy | ||
GET /v1/scale/tam | agents:read | Scale › tam | ||
GET /v1/sequences | agents:read | List sequences | ||
POST /v1/sequences/:sequenceArmId/leads | leads:write outbound | Sequence › leads | ||
GET /v1/sources | agents:read | List sources | ||
GET /v1/strategies | agents:read | List strategies | ||
GET /v1/supervisor | agents:read | List supervisor | ||
POST /v1/supervisor/actions/:id/undo | agents:write | Supervisor › actions undo | ||
GET /v1/verticals | agents:read | List verticals | ||
GET /v1/voice | workspace:read | List voice | ||
GET /v1/voice/voices | agents:read | Voice › voices |
Inbox and sending
Replies, sent email, mailboxes and LinkedIn accounts.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/calendars | workspace:read | List calendars | ||
GET /v1/fleet | mailboxes:read | List fleet | ||
GET /v1/inbox | inbox:read | List replies | { items, next_cursor } | |
GET /v1/inbox/:id | inbox:read | Get an inbox thread | ||
PATCH /v1/inbox/:id | inbox:write | Update an inbox thread | ||
POST /v1/inbox/:id/auto-reply/undo | inbox:write | Inbox thread › auto reply undo | ||
POST /v1/inbox/:id/book | inbox:write | Inbox thread › book | ||
PATCH /v1/inbox/:id/draft | inbox:write | Update: Inbox thread › draft | ||
POST /v1/inbox/:id/forward | inbox:write | Inbox thread › forward | ||
POST /v1/inbox/:id/handled | inbox:write | Inbox thread › handled | ||
POST /v1/inbox/:id/pick | inbox:write | Inbox thread › pick | ||
POST /v1/inbox/:id/push-crm | inbox:write | Inbox thread › push CRM | ||
POST /v1/inbox/:id/redraft | inbox:write | Inbox thread › redraft | ||
POST /v1/inbox/:id/send | inbox:write | Inbox thread › send | ||
DELETE /v1/inbox/:id/snooze | inbox:write | Delete: Inbox thread › snooze | ||
POST /v1/inbox/:id/snooze | inbox:write | Inbox thread › snooze | ||
POST /v1/inbox/:id/tag | inbox:write | Inbox thread › tag | ||
POST /v1/inbox/bulk | inbox:write | Inbox › bulk | ||
GET /v1/inbox/counts | inbox:read | Inbox › counts | ||
GET /v1/inboxes/offer | mailboxes:read | Inboxes › offer | ||
POST /v1/inboxes/order | mailboxes:write outbound | Inboxes › order | ||
GET /v1/inboxes/orders | mailboxes:read | Inboxes › orders | ||
GET /v1/inboxes/orders/:id | mailboxes:read | Inboxes › orders (one) | ||
GET /v1/linkedin-accounts | workspace:read | List LinkedIn accounts | ||
GET /v1/linkedin/accounts | workspace:read | LinkedIn › accounts | ||
GET /v1/linkedin/accounts/:id | workspace:read | LinkedIn › accounts (one) | ||
GET /v1/linkedin/actions | leads:read | LinkedIn › actions | ||
DELETE /v1/linkedin/actions/:id | leads:write | Delete: LinkedIn › actions (one) | ||
PATCH /v1/linkedin/actions/:id | leads:write | Update: LinkedIn › actions (one) | ||
POST /v1/linkedin/actions/:id/hold | leads:write | LinkedIn › actions hold | ||
POST /v1/linkedin/actions/:id/resume | leads:write | LinkedIn › actions resume | ||
GET /v1/linkedin/engagement/stats | workspace:read | LinkedIn › engagement stats | ||
GET /v1/linkedin/growth | workspace:read | LinkedIn › growth | ||
GET /v1/linkedin/growth/comments | workspace:read | LinkedIn › growth comments | ||
GET /v1/linkedin/growth/posts | workspace:read | LinkedIn › growth posts | ||
GET /v1/linkedin/growth/stats | workspace:read | LinkedIn › growth stats | ||
GET /v1/linkedin/growth/targets | workspace:read | LinkedIn › growth targets | ||
GET /v1/mailboxes | mailboxes:read | List mailboxes | ||
GET /v1/mailboxes/:id | mailboxes:read | Get a mailbox | ||
PATCH /v1/mailboxes/:id | mailboxes:write | Update a mailbox | ||
POST /v1/mailboxes/:id/pause | mailboxes:write | Mailbox › pause | ||
GET /v1/mailboxes/:id/placement-tests | mailboxes:read | Mailbox › placement tests | ||
POST /v1/mailboxes/:id/resume | mailboxes:write | Mailbox › resume | ||
GET /v1/mailboxes/:id/warmup | mailboxes:read | Mailbox › warmup | ||
GET /v1/mailboxes/connect-options | mailboxes:read | Mailboxes › connect options | ||
GET /v1/mailboxes/domains | mailboxes:read | Mailboxes › domains | ||
GET /v1/mailboxes/volume-quote | mailboxes:read | Mailboxes › volume quote | ||
GET /v1/routing | workspace:read | List routing | ||
GET /v1/sent | inbox:read | List sent | ||
GET /v1/sent/:id | inbox:read | Get a sent email | ||
GET /v1/sent/counts | inbox:read | Sent › counts |
Visitors
Companies and people visiting your website (company-by-IP matches are inferred).
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/privacy/deletion-requests | visitors:write | Privacy › deletion requests | ||
GET /v1/visitors | visitors:read | List visitors | ||
DELETE /v1/visitors/:id | visitors:write | Delete a visitor | ||
GET /v1/visitors/:id | visitors:read | Get a visitor | ||
POST /v1/visitors/:id/add-to-agent | visitors:write outbound | Visitor › add to agent | ||
POST /v1/visitors/deletion-requests | visitors:write | Visitors › deletion requests | ||
GET /v1/visitors/install | visitors:read | Visitors › install | ||
DELETE /v1/visitors/person-vendor | visitors:write | Delete: Visitors › person vendor | ||
GET /v1/visitors/person-vendor | visitors:read | Visitors › person vendor | ||
PUT /v1/visitors/person-vendor | visitors:write | Update: Visitors › person vendor | ||
GET /v1/visitors/rules | visitors:read | Visitors › rules | ||
POST /v1/visitors/rules | visitors:write outbound | Visitors › rules | ||
DELETE /v1/visitors/rules/:id | visitors:write | Delete: Visitors › rules (one) | ||
PATCH /v1/visitors/rules/:id | visitors:write outbound | Update: Visitors › rules (one) | ||
GET /v1/visitors/sites | visitors:read | Visitors › sites | ||
POST /v1/visitors/sites | visitors:write | Visitors › sites | ||
DELETE /v1/visitors/sites/:id | visitors:write | Delete: Visitors › sites (one) | ||
GET /v1/visitors/sites/:id | visitors:read | Visitors › sites (one) | ||
PATCH /v1/visitors/sites/:id | visitors:write | Update: Visitors › sites (one) | ||
POST /v1/visitors/sites/:id/check | visitors:write | Visitors › sites check | ||
GET /v1/visitors/sites/:id/notice | visitors:read | Visitors › sites notice | ||
POST /v1/visitors/sites/:id/visit-as-me | visitors:write | Visitors › sites visit as me | ||
GET /v1/visitors/sources | visitors:read | Visitors › sources |
Webhooks
Workspace webhook endpoints and their deliveries.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/webhook-deliveries/:id/retry | webhooks:write | Retry a webhook delivery | 202 the delivery | |
GET /v1/webhooks | webhooks:read | List webhook endpoints | { items, events } | |
POST /v1/webhooks | webhooks:write | Add a webhook endpoint | { url, events: ("lead.ready" | "reply.received" | "visitor.identified")[], description? } | 201 the endpoint with its secret (shown once) |
DELETE /v1/webhooks/:id | webhooks:write | Delete a webhook endpoint | { ok: true, id, deleted: true } | |
GET /v1/webhooks/:id | webhooks:read | Get a webhook endpoint | the endpoint with its last 30 days | |
PATCH /v1/webhooks/:id | webhooks:write | Update a webhook endpoint | any of { url, events, status: "active" | "paused", description } | the endpoint |
GET /v1/webhooks/:id/deliveries | webhooks:read | An endpoint's deliveries | ?status=&limit=&cursor= | { items, next_cursor } |
POST /v1/webhooks/:id/rotate-secret | webhooks:write | Rotate an endpoint's signing secret | { id, secret, secret_hint } | |
POST /v1/webhooks/:id/test | webhooks:write | Send a test event | { event? } | 202 the queued delivery |
Workspace
Your workspace, onboarding, setup, integrations, assistant and background jobs.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/copilot/ask | copilot:read | Copilot › ask | ||
GET /v1/copilot/ask/:id | copilot:read | Copilot › ask (one) | ||
GET /v1/copilot/capabilities | copilot:read | Copilot › capabilities | ||
GET /v1/copilot/threads | copilot:read | Copilot › threads | ||
GET /v1/integrations | workspace:read | List integrations | ||
GET /v1/integrations/:id/account-sync | workspace:read | Account signals on CRM company records: the setting, the field map, what this CRM takes, how many were written | { supported, reason, settings: { on, create_companies, fields }, field_keys, field_hint, fields_allowed, fields_reason, locked, locked_reason, counts: { written, not_found, failed, created }, last_synced_at, last_error } | |
PUT /v1/integrations/:id/account-sync | signals:write | Write account signals to company records (on or off), create missing companies, and the field map (written by a job) | { on?, create_companies?, fields?: { score?, why_now?, newest_at?, signals?, app_url? } (the CRM field names; null clears one) } | the view with checking |
POST /v1/integrations/:id/account-sync/run | signals:write | Write account signals now: every account compared again (a job; only changed stories are written) | 202 the view with checking | |
PATCH /v1/integrations/:id/exclusions | exclusions:write | Update: Integration › exclusions | ||
POST /v1/integrations/:id/exclusions/sync | exclusions:write | Integration › exclusions sync | ||
GET /v1/integrations/:id/monday | workspace:read | Integration › monday | ||
POST /v1/integrations/:id/monday/sync | watchlist:write | Integration › monday sync | ||
GET /v1/integrations/:id/pushes | leads:read | Integration › pushes | ||
GET /v1/integrations/:id/settings | workspace:read | Integration › settings | ||
GET /v1/integrations/catalog | workspace:read | Integrations › catalog | ||
POST /v1/integrations/close/import | imports:write outbound | Integrations › close import | ||
GET /v1/integrations/close/views | imports:read | Integrations › close views | ||
POST /v1/integrations/close/views/refresh | imports:write | Integrations › close views refresh | ||
GET /v1/integrations/hubspot/lists | watchlist:read | Integrations › HubSpot lists | ||
GET /v1/integrations/hubspot/sync | watchlist:read | Integrations › HubSpot sync | ||
POST /v1/integrations/hubspot/sync | watchlist:write | Integrations › HubSpot sync | ||
GET /v1/integrations/list-imports | imports:read | Integrations › list imports | ||
GET /v1/integrations/monday/import | watchlist:read | Integrations › monday import | ||
GET /v1/integrations/slack/channels | workspace:read | Integrations › Slack channels | ||
GET /v1/integrations/slack/settings | workspace:read | Integrations › Slack settings | ||
GET /v1/jobs/:id | leads:read | Progress of a background job | { id, kind, total, done, status: queued | waiting | running | done | failed | canceled, meta, percent } | |
GET /v1/onboarding/preview/:id | workspace:read | Onboarding › preview (one) | ||
GET /v1/onboarding/profile | workspace:read | Onboarding › profile | ||
GET /v1/onboarding/state | workspace:read | Onboarding › state | ||
GET /v1/onboarding/status | workspace:read | Onboarding › status | ||
GET /v1/onboarding/voice | workspace:read | Onboarding › voice | ||
GET /v1/profile | workspace:read | List profile | ||
GET /v1/setup | workspace:read | List setup | ||
GET /v1/slack | workspace:read | List Slack | ||
GET /v1/supply | workspace:read | List supply | ||
POST /v1/support/messages | support:write | Support › messages | ||
GET /v1/workspace | workspace:read | Your workspace | the workspace |
MCP
The MCP endpoint (JSON-RPC over HTTP). Tools and install steps: /docs/mcp.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
POST /v1/mcp | mcp:read | MCP endpoint: one JSON-RPC message per request | { jsonrpc: "2.0", id, method, params } | the JSON-RPC response |
Other
Other endpoints.
| Endpoint | Scope | What it does | Input | Returns |
|---|---|---|---|---|
GET /v1/send-window | workspace:read | List send window |
Examples
Copy, set KAMATA_API_KEY and run. Ids are placeholders.
POST /v1/data/find-email
Find a verified work email. Emails
curl -s -X POST https://api.kamata.ai/v1/data/find-email \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"person":{"full_name":"Jane Doe","domain":"acme.example"}}'
POST /v1/data/verify-email
Verify one email as a lookup job. Emails
curl -s -X POST https://api.kamata.ai/v1/data/verify-email \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"email":"jane.doe@acme.example"}'
POST /v1/verify/email
Verify one email address. Emails
curl -s -X POST https://api.kamata.ai/v1/verify/email \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"email":"jane.doe@acme.example"}'
POST /v1/verify/emails
Verify up to 5,000 email addresses. Emails
curl -s -X POST https://api.kamata.ai/v1/verify/emails \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"items":["jane.doe@acme.example","info@acme.example"],"wait_s":5}'
POST /v1/data/find-phone
Find a direct phone. Phones
curl -s -X POST https://api.kamata.ai/v1/data/find-phone \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"person":{"email":"jane.doe@acme.example"}}'
POST /v1/data/verify-phone
Check a phone line (mobile, landline, VoIP). Phones
curl -s -X POST https://api.kamata.ai/v1/data/verify-phone \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"phone":"+14155550123"}'
GET /v1/phone/levels
Which lookup levels are available, and their credits. Phones
curl -s "https://api.kamata.ai/v1/phone/levels" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/phone/lookup
Look up one phone number. Phones
curl -s -X POST https://api.kamata.ai/v1/phone/lookup \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"phone":"+1 415 555 0123","level":"validate"}'
GET /v1/phone/lookup/:id
One phone lookup: status, result and cost. Phones
curl -s "https://api.kamata.ai/v1/phone/lookup/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/phone/lookups
Look up up to 5,000 phone numbers. Phones
curl -s -X POST https://api.kamata.ai/v1/phone/lookups \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"items":["+1 415 555 0123","415-555-0199"],"default_country":"US"}'
GET /v1/phone/lookups/:id
A phone lookup list: progress and a page of results. Phones
curl -s "https://api.kamata.ai/v1/phone/lookups/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/phone/lookups/:id/export
A phone lookup list as CSV. Phones
curl -s "https://api.kamata.ai/v1/phone/lookups/00000000-0000-4000-8000-000000000001/export" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/phone/reverse
Who is behind one phone number. Phones
curl -s -X POST https://api.kamata.ai/v1/phone/reverse \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/phone/reverses
Who is behind up to 5,000 phone numbers. Phones
curl -s -X POST https://api.kamata.ai/v1/phone/reverses \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/verify/phone
Check one phone number. Phones
curl -s -X POST https://api.kamata.ai/v1/verify/phone \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"phone":"+1 415 555 0123","checks":["format"]}'
POST /v1/verify/phones
Check up to 5,000 phone numbers. Phones
curl -s -X POST https://api.kamata.ai/v1/verify/phones \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"items":["+1 415 555 0123","415-555-0199"],"default_country":"US"}'
POST /v1/data/find-contacts
Run find_contacts as a job. People and companies enrichment
curl -s -X POST https://api.kamata.ai/v1/data/find-contacts \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"args":{"people":[{"full_name":"Jane Doe","domain":"acme.example"}],"want":["email"]}}'
GET /v1/data/find-contacts/:id
A find_contacts job. People and companies enrichment
curl -s "https://api.kamata.ai/v1/data/find-contacts/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/data/match-linkedin
Email to LinkedIn profile. People and companies enrichment
curl -s -X POST https://api.kamata.ai/v1/data/match-linkedin \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"email":"jane.doe@acme.example"}'
POST /v1/enrich/companies
Enrich up to 5,000 companies. People and companies enrichment
curl -s -X POST https://api.kamata.ai/v1/enrich/companies \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"items":["acme.example"]}'
POST /v1/enrich/people
Enrich up to 5,000 people. People and companies enrichment
curl -s -X POST https://api.kamata.ai/v1/enrich/people \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"items":[{"full_name":"Jane Doe","domain":"acme.example"}],"want":["email"]}'
GET /v1/enrich/batches/:id
Same as /v1/verify/batches/:id. Batches and files
curl -s "https://api.kamata.ai/v1/enrich/batches/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/enrich/batches/:id/download-link
Same as /v1/verify/batches/:id/download-link. Batches and files
curl -s -X POST https://api.kamata.ai/v1/enrich/batches/00000000-0000-4000-8000-000000000001/download-link \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/enrich/batches/:id/export
Same as /v1/verify/batches/:id/export. Batches and files
curl -s "https://api.kamata.ai/v1/enrich/batches/00000000-0000-4000-8000-000000000001/export" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/enrich/upload
Enrich a CSV or .xlsx file. Batches and files
curl -s https://api.kamata.ai/v1/enrich/upload \ -H "Authorization: Bearer $KAMATA_API_KEY" \ -F "file=@contacts.csv"
GET /v1/verify/batches/:id
Batch progress and a page of results. Batches and files
curl -s "https://api.kamata.ai/v1/verify/batches/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/verify/batches/:id/download-link
A one-hour download link to the results. Batches and files
curl -s -X POST https://api.kamata.ai/v1/verify/batches/00000000-0000-4000-8000-000000000001/download-link \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/verify/batches/:id/export
Batch results as a file. Batches and files
curl -s "https://api.kamata.ai/v1/verify/batches/00000000-0000-4000-8000-000000000001/export" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/verify/upload
Verify a CSV or .xlsx file (≤ 5,000 rows). Batches and files
curl -s https://api.kamata.ai/v1/verify/upload \ -H "Authorization: Bearer $KAMATA_API_KEY" \ -F "file=@contacts.csv"
GET /v1/data/lookups
Your lookups, newest first. Lookups
curl -s "https://api.kamata.ai/v1/data/lookups" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/lookups/:id
One lookup and its result. Lookups
curl -s "https://api.kamata.ai/v1/data/lookups/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/credits
The credit wallet: included, rolled over, bought, used, left. Credits and plan
curl -s "https://api.kamata.ai/v1/credits" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/credits/usage
This month's credits by person, API key and connected app, by action, and per day. Credits and plan
curl -s "https://api.kamata.ai/v1/credits/usage" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/credits
Credits left this month and the price per action. Credits and plan
curl -s "https://api.kamata.ai/v1/data/credits" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/plan
Your plan and its limits. Credits and plan
curl -s "https://api.kamata.ai/v1/plan" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/usage
This month's usage against your plan. Credits and plan
curl -s "https://api.kamata.ai/v1/usage" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/companies/:id/competitors
A company's scored competitors with their evidence. Web search, news and competitors
curl -s "https://api.kamata.ai/v1/companies/00000000-0000-4000-8000-000000000001/competitors" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/companies/:id/news
A company's recent news, each item with its link and date. Web search, news and competitors
curl -s "https://api.kamata.ai/v1/companies/00000000-0000-4000-8000-000000000001/news" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/search/web
Search our company web index and news. Web search, news and competitors
curl -s "https://api.kamata.ai/v1/search/web" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/search/web/refresh
Look further for news or competitors (runs as a job). Web search, news and competitors
curl -s -X POST https://api.kamata.ai/v1/search/web/refresh \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"intent":"news","domain":"acme.example"}'
GET /v1/data/companies/:domain/technographics
Technologies named in a company's job posts (inferred) and, as a separate list, seen on its website. Technologies
curl -s "https://api.kamata.ai/v1/data/companies/00000000-0000-4000-8000-000000000001/technographics" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/tech/catalog
The technology catalog: parent categories, categories, every technology and how many sites use it now. Technologies
curl -s "https://api.kamata.ai/v1/data/tech/catalog" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/tech/sites
Companies whose websites use a technology (our own crawl: page code, headers, DNS, files). Technologies
curl -s "https://api.kamata.ai/v1/data/tech/sites" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/companies/:domain/hiring
What a company is hiring for: open posts, posts in the last 30 days, by function and seniority, its newest posts and the boards we read. Jobs
curl -s "https://api.kamata.ai/v1/data/companies/00000000-0000-4000-8000-000000000001/hiring" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/jobs
Job posts from companies' own public job boards and careers pages (our own dataset), newest first. Jobs
curl -s "https://api.kamata.ai/v1/data/jobs" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/data/jobs/:id
One job post with its full description. Jobs
curl -s "https://api.kamata.ai/v1/data/jobs/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/contacts
List your contacts. People and companies search
curl -s "https://api.kamata.ai/v1/contacts" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/contacts/:id
Get a contact. People and companies search
curl -s "https://api.kamata.ai/v1/contacts/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/lookalikes
List lookalike runs. People and companies search
curl -s "https://api.kamata.ai/v1/lookalikes" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/lookalikes
Find companies like your best ones (runs as a job). People and companies search
curl -s -X POST https://api.kamata.ai/v1/lookalikes \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/lookalikes/:id
A lookalike run and its graded companies. People and companies search
curl -s "https://api.kamata.ai/v1/lookalikes/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/search/companies
Search companies. People and companies search
curl -s "https://api.kamata.ai/v1/search/companies" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/search/companies/match
Match a company by name or domain. People and companies search
curl -s "https://api.kamata.ai/v1/search/companies/match" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/search/companies/match
Match a list of companies by name or domain. People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/companies/match \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/search/export
Search results as CSV. People and companies search
curl -s "https://api.kamata.ai/v1/search/export" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/search/find-email
Find the verified email of a search result (runs as a job). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/find-email \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/search/find-phone
Find the phone of a search result (runs as a job). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/find-phone \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/search/leads
Find leads: people or companies with recent buying signals. People and companies search
curl -s "https://api.kamata.ai/v1/search/leads" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/search/live
Run a live people or company search (runs as a job). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/live \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/search/live/preview
Cost preview of a live people or company search (nothing spent). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/live/preview \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/search/market
Search the market database (cost preview, then confirm). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/market \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/search/market/preview
Cost preview of a market database search (nothing spent). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/market/preview \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/search/people
Search people. People and companies search
curl -s "https://api.kamata.ai/v1/search/people" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/search/reveal
Reveal emails or mobiles for search results (cost preview first). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/reveal \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/search/saved
List saved searches. People and companies search
curl -s "https://api.kamata.ai/v1/search/saved" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/search/saved
Save a search. People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/saved \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/search/verify-email
Verify one email from search (runs as a job). People and companies search
curl -s -X POST https://api.kamata.ai/v1/search/verify-email \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/account-lists
List your account lists, each with its signals and its progress. Signals
curl -s "https://api.kamata.ai/v1/account-lists" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/account-lists
Make an account list. Signals
curl -s -X POST https://api.kamata.ai/v1/account-lists \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
DELETE /v1/account-lists/:id
Delete an account list (never "My accounts"); its accounts stay on "My accounts". Signals
curl -s -X DELETE https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001 \ -H "Authorization: Bearer $KAMATA_API_KEY"
PATCH /v1/account-lists/:id
Rename an account list (never "My accounts"). Signals
curl -s -X PATCH https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001 \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/account-lists/:id/members
Add accounts to a list by domain: a paste or a file (checked against its signals as a job). Also needs watchlist:write. Signals
curl -s -X POST https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001/members \ -H "Authorization: Bearer $KAMATA_API_KEY"
PUT /v1/account-lists/:id/signal-set
Pick the signal set a list takes its signals from, or null for its own. Signals
curl -s -X PUT https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001/signal-set \ -H "Authorization: Bearer $KAMATA_API_KEY"
PUT /v1/account-lists/:id/signals
Set the signals a list is checked against (the whole set). Signals
curl -s -X PUT https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001/signals \ -H "Authorization: Bearer $KAMATA_API_KEY"
PUT /v1/account-lists/:id/suggestions
Keep finding accounts for a list (on or off) and what a suggestion must fit. Signals
curl -s -X PUT https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001/suggestions \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/account-lists/:id/suggestions/watch
Watch several suggested accounts at once (refused whole past the plan). Also needs watchlist:write. Signals
curl -s -X POST https://api.kamata.ai/v1/account-lists/00000000-0000-4000-8000-000000000001/suggestions/watch \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/accounts
List accounts: score with its parts, Why now, signals true, newest evidence, owner and list. Signals
curl -s "https://api.kamata.ai/v1/accounts" \ -H "Authorization: Bearer $KAMATA_API_KEY"
DELETE /v1/accounts/:id
Take an account off its list; off "My accounts" it leaves every list and the watchlist. Also needs watchlist:write. Signals
curl -s -X DELETE https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001 \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/accounts/:id
One account: its score and Why now, a line per signal with its evidence link and date or the reason it has none, and what we read. Signals
curl -s "https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
PATCH /v1/accounts/:id
Correct an account's domain. Also needs watchlist:write. Signals
curl -s -X PATCH https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001 \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
POST /v1/accounts/:id/answers/:customSignalId/feedback
"Not right?": rate the answer one signal gave for this account (good, bad, or null to clear). Signals
curl -s -X POST https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001/answers/00000000-0000-4000-8000-000000000001/feedback \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/accounts/:id/lead
Make a lead from an account (queued as a job; every lead check applies). Signals
curl -s -X POST https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001/lead \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/accounts/:id/reject
Reject a suggested account: never suggested again; names the filter that fixes the reason. Signals
curl -s -X POST https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001/reject \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/accounts/:id/watch
Watch a suggested account: it joins its list and the watchlist and is checked against the list's signals. Also needs watchlist:write. Signals
curl -s -X POST https://api.kamata.ai/v1/accounts/00000000-0000-4000-8000-000000000001/watch \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/accounts/outcomes
Your won and lost deals on file (add them with POST /v1/imports kind "outcomes"). Signals
curl -s "https://api.kamata.ai/v1/accounts/outcomes" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/accounts/outcomes
Add won and lost deals one by one (then "My accounts" is tested again). Signals
curl -s -X POST https://api.kamata.ai/v1/accounts/outcomes \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/accounts/overview
One of your accounts by its domain: score, Why now with quotes, a line per signal, what we read. Signals
curl -s "https://api.kamata.ai/v1/accounts/overview" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/accounts/priorities
Today's top accounts: the Accounts screen's order, only those with a score, each Why now fact with its date, link and quote. Signals
curl -s "https://api.kamata.ai/v1/accounts/priorities" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/custom-signals
List custom signals. Signals
curl -s "https://api.kamata.ai/v1/custom-signals" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/custom-signals
Describe a custom signal in one sentence (built as a job). Signals
curl -s -X POST https://api.kamata.ai/v1/custom-signals \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/custom-signals/:id
A custom signal, its latest hits and runs. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
PUT /v1/custom-signals/:id/alerts
Set where a signal sends its matches, or mute it. Signals
curl -s -X PUT https://api.kamata.ai/v1/custom-signals/00000000-0000-4000-8000-000000000001/alerts \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/custom-signals/:id/backtest/deals
The won or lost deals a signal came before, each with its dated proof. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/00000000-0000-4000-8000-000000000001/backtest/deals" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/custom-signals/:id/outcomes
One signal's results and suggested priority. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/00000000-0000-4000-8000-000000000001/outcomes" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/custom-signals/backtest
What predicts wins: per signal, the won and lost deals it came before and its matches in 12 months. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/backtest" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/custom-signals/backtest
Test signals on the last 12 months of a list's accounts (runs as a job). Signals
curl -s -X POST https://api.kamata.ai/v1/custom-signals/backtest \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/custom-signals/outcomes
Signal results: per signal the leads, sends, positive replies, meetings and wins in the latest window, and a suggested priority. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/outcomes" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/custom-signals/tryouts
Try up to five sentences before anything is saved (read and counted as a job). Signals
curl -s -X POST https://api.kamata.ai/v1/custom-signals/tryouts \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/custom-signals/tryouts/:id
A tried sentence: how it was read, its 30-day count and example companies. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/tryouts/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/custom-signals/tryouts/:id/backtest
A tried sentence's history test: matches in 12 months and the wins it came before. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/tryouts/00000000-0000-4000-8000-000000000001/backtest" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/custom-signals/tryouts/:id/backtest
Test a tried sentence on the last 12 months (runs as a job). Signals
curl -s -X POST https://api.kamata.ai/v1/custom-signals/tryouts/00000000-0000-4000-8000-000000000001/backtest \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/custom-signals/tryouts/:id/backtest/deals
The won or lost deals a tried sentence came before, each with its dated proof. Signals
curl -s "https://api.kamata.ai/v1/custom-signals/tryouts/00000000-0000-4000-8000-000000000001/backtest/deals" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/custom-signals/tryouts/:id/keep
Turn a tried sentence on as a signal. Signals
curl -s -X POST https://api.kamata.ai/v1/custom-signals/tryouts/00000000-0000-4000-8000-000000000001/keep \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/events
List product events. Signals
curl -s "https://api.kamata.ai/v1/events" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/events
Send product events (one or up to 500). Signals
curl -s -X POST https://api.kamata.ai/v1/events \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/events/summary
Product events in the last 30 days. Signals
curl -s "https://api.kamata.ai/v1/events/summary" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/signal-alerts
List signal alerts with where each went. Signals
curl -s "https://api.kamata.ai/v1/signal-alerts" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/signal-alerts/retry
Send failed signal alerts again (sent by a job). Signals
curl -s -X POST https://api.kamata.ai/v1/signal-alerts/retry \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/signal-alerts/status
Which alert channels are on the plan, connected or failing. Signals
curl -s "https://api.kamata.ai/v1/signal-alerts/status" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/signal-library/outcomes
The network's suggested priority per library signal (only while network learning is on). Signals
curl -s "https://api.kamata.ai/v1/signal-library/outcomes" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/signal-sets
List your signal sets, each with its signals and the lists that use it. Signals
curl -s "https://api.kamata.ai/v1/signal-sets" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/signal-sets
Make a signal set. Signals
curl -s -X POST https://api.kamata.ai/v1/signal-sets \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
DELETE /v1/signal-sets/:id
Delete a signal set; its lists keep the signals they have. Signals
curl -s -X DELETE https://api.kamata.ai/v1/signal-sets/00000000-0000-4000-8000-000000000001 \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/signal-sets/:id
One signal set: its signals with the set's priority and the lists that use it. Signals
curl -s "https://api.kamata.ai/v1/signal-sets/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
PATCH /v1/signal-sets/:id
Rename a signal set or replace its signals; every list on it follows (new signals are checked as a job). Signals
curl -s -X PATCH https://api.kamata.ai/v1/signal-sets/00000000-0000-4000-8000-000000000001 \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/signals
Buying signals behind your leads. Signals
curl -s "https://api.kamata.ai/v1/signals" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/signals/:id
Get a signal with its evidence link and date. Signals
curl -s "https://api.kamata.ai/v1/signals/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/export/leads.csv
Leads as CSV. Leads
curl -s "https://api.kamata.ai/v1/export/leads.csv" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/leads
List leads. Leads
curl -s "https://api.kamata.ai/v1/leads" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/leads/:id
Get a lead: company, person, evidence, fit and draft. Leads
curl -s "https://api.kamata.ai/v1/leads/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/leads/:id/approve
Approve a lead for sending. Leads
curl -s -X POST https://api.kamata.ai/v1/leads/00000000-0000-4000-8000-000000000001/approve \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/leads/:id/drafts
Save an edited draft. Leads
curl -s -X POST https://api.kamata.ai/v1/leads/00000000-0000-4000-8000-000000000001/drafts \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/leads/:id/reject
Reject a lead. Leads
curl -s -X POST https://api.kamata.ai/v1/leads/00000000-0000-4000-8000-000000000001/reject \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/leads/bulk-approve
Approve many leads at once. Leads
curl -s -X POST https://api.kamata.ai/v1/leads/bulk-approve \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/queued
Queued first emails: scheduled, not scheduled yet, on hold. Leads
curl -s "https://api.kamata.ai/v1/queued" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/queued/bulk
Hold, resume or send back to review. Leads
curl -s -X POST https://api.kamata.ai/v1/queued/bulk \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/stats/today
Today's numbers. Leads
curl -s "https://api.kamata.ai/v1/stats/today" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/tags
List tags. Leads
curl -s "https://api.kamata.ai/v1/tags" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/tags
Create a tag. Leads
curl -s -X POST https://api.kamata.ai/v1/tags \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/exclusions
List exclusions. Lists
curl -s "https://api.kamata.ai/v1/exclusions" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/exclusions
Exclude domains or emails (never contacted). Lists
curl -s -X POST https://api.kamata.ai/v1/exclusions \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"domains":["acme.example"],"reason":"customer"}'
GET /v1/exclusions/export
Exclusions as CSV. Lists
curl -s "https://api.kamata.ai/v1/exclusions/export" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/imports
List imports. Lists
curl -s "https://api.kamata.ai/v1/imports" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/imports
Import a list (CSV upload or rows). Lists
curl -s https://api.kamata.ai/v1/imports \ -H "Authorization: Bearer $KAMATA_API_KEY" \ -F "kind=watchlist" -F "file=@companies.csv"
GET /v1/imports/:id
Get an import and its summary. Lists
curl -s "https://api.kamata.ai/v1/imports/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/imports/:id/enrich
Enrich an import's rows (estimate first with dry_run). Lists
curl -s -X POST https://api.kamata.ai/v1/imports/00000000-0000-4000-8000-000000000001/enrich \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/imports/:id/rows
An import's rows. Lists
curl -s "https://api.kamata.ai/v1/imports/00000000-0000-4000-8000-000000000001/rows" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/watchlist
List watched companies. Lists
curl -s "https://api.kamata.ai/v1/watchlist" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/watchlist
Watch companies by domain. Lists
curl -s -X POST https://api.kamata.ai/v1/watchlist \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"domains":["acme.example"],"agent_id":null}'
DELETE /v1/watchlist/:id
Stop watching a company. Lists
curl -s -X DELETE https://api.kamata.ai/v1/watchlist/00000000-0000-4000-8000-000000000001 \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/agents
List agents. Agents
curl -s "https://api.kamata.ai/v1/agents" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/agents
Create an agent from a domain or one sentence. Agents
curl -s -X POST https://api.kamata.ai/v1/agents \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
DELETE /v1/agents/:id
Delete an agent. Agents
curl -s -X DELETE https://api.kamata.ai/v1/agents/00000000-0000-4000-8000-000000000001 \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/agents/:id
Get an agent. Agents
curl -s "https://api.kamata.ai/v1/agents/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
PATCH /v1/agents/:id
Update an agent. Agents
curl -s -X PATCH https://api.kamata.ai/v1/agents/00000000-0000-4000-8000-000000000001 \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/inbox
List replies. Inbox and sending
curl -s "https://api.kamata.ai/v1/inbox" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/webhook-deliveries/:id/retry
Retry a webhook delivery. Webhooks
curl -s -X POST https://api.kamata.ai/v1/webhook-deliveries/00000000-0000-4000-8000-000000000001/retry \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/webhooks
List webhook endpoints. Webhooks
curl -s "https://api.kamata.ai/v1/webhooks" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/webhooks
Add a webhook endpoint. Webhooks
curl -s -X POST https://api.kamata.ai/v1/webhooks \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"url":"https://hooks.acme.example/leads","events":["lead.ready"]}'
DELETE /v1/webhooks/:id
Delete a webhook endpoint. Webhooks
curl -s -X DELETE https://api.kamata.ai/v1/webhooks/00000000-0000-4000-8000-000000000001 \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/webhooks/:id
Get a webhook endpoint. Webhooks
curl -s "https://api.kamata.ai/v1/webhooks/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
PATCH /v1/webhooks/:id
Update a webhook endpoint. Webhooks
curl -s -X PATCH https://api.kamata.ai/v1/webhooks/00000000-0000-4000-8000-000000000001 \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/webhooks/:id/deliveries
An endpoint's deliveries. Webhooks
curl -s "https://api.kamata.ai/v1/webhooks/00000000-0000-4000-8000-000000000001/deliveries" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/webhooks/:id/rotate-secret
Rotate an endpoint's signing secret. Webhooks
curl -s -X POST https://api.kamata.ai/v1/webhooks/00000000-0000-4000-8000-000000000001/rotate-secret \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/webhooks/:id/test
Send a test event. Webhooks
curl -s -X POST https://api.kamata.ai/v1/webhooks/00000000-0000-4000-8000-000000000001/test \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/integrations/:id/account-sync
Account signals on CRM company records: the setting, the field map, what this CRM takes, how many were written. Workspace
curl -s "https://api.kamata.ai/v1/integrations/00000000-0000-4000-8000-000000000001/account-sync" \ -H "Authorization: Bearer $KAMATA_API_KEY"
PUT /v1/integrations/:id/account-sync
Write account signals to company records (on or off), create missing companies, and the field map (written by a job). Workspace
curl -s -X PUT https://api.kamata.ai/v1/integrations/00000000-0000-4000-8000-000000000001/account-sync \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/integrations/:id/account-sync/run
Write account signals now: every account compared again (a job; only changed stories are written). Workspace
curl -s -X POST https://api.kamata.ai/v1/integrations/00000000-0000-4000-8000-000000000001/account-sync/run \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{}'
GET /v1/jobs/:id
Progress of a background job. Workspace
curl -s "https://api.kamata.ai/v1/jobs/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $KAMATA_API_KEY"
GET /v1/workspace
Your workspace. Workspace
curl -s "https://api.kamata.ai/v1/workspace" \ -H "Authorization: Bearer $KAMATA_API_KEY"
POST /v1/mcp
MCP endpoint: one JSON-RPC message per request. MCP
curl -s -X POST https://api.kamata.ai/v1/mcp \
-H "Authorization: Bearer $KAMATA_API_KEY" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
Results
{ email, status: valid | invalid | catch_all | unknown | disposable | role, reason, mx, source, checked_at, do_not_contact, sendable, grade, grade_reasons, from_cache, credits_charged }. sendable is true only for valid addresses not on the opt-out list or your exclusions. A hard bounce or a departure on record grades an address F even when sendable is true: send only to grades A and B. A verification is a measurement.
Phone
{ e164, valid, possible, country, line_type: mobile | landline | voip | toll_free | unknown, line_type_inferred, carrier, source, checked_at, reason }. Without checks: ["line_type"] the line type comes from the numbering plan and is inferred (line_type_inferred: true); with it, a carrier line check measures it.
Person (enrich)
{ status: found | partial | not_found | invalid_input, name, company, domain, email, email_status, email_verified, phone, phone_inferred, linkedin_url, linkedin_inferred, title, location, … }, each value with its source. An email is returned only when the verifier said valid; nothing is pattern-guessed. Phones and matched LinkedIn profiles are provider matches (inferred).
Company (enrich)
{ status, name, domain, domain_inferred, attributes: { industry, employee_count, employee_range, founded_year, revenue_band, funding_stage, country, address, linkedin_url, location }, missing, reason }. Each attribute carries its source and date; a vendor's modelled value is inferred: true; a missing field is listed in missing, never 0.
Lookups (/v1/data/*)
GET /v1/data/lookups/:id → result: verify { email, email_status, sendable, verified: { measured: true, source, checked_at }, reason }; find / match { found, email | phone | linkedin_url, match: { inferred: true, source, matched_at }, cached, reason }; phone check { found, phone, line_type, valid, carrier, checked_at, cached, reason }.
Risk grades (A–F)
Every email result read from /v1/verify/* carries grade and grade_reasons (the MCP tools show the grade with one short reason). This table is computed by the same function that grades results:
| Grade | When | Reasons returned | Sendable |
|---|---|---|---|
| A | valid, with replies on record | deliverable; replies on record | yes |
| A | valid, delivered to at least twice without a bounce | deliverable; delivered before without a bounce | yes |
| B | valid | deliverable | yes |
| C | catch_all | catch-all domain: accepts every address, so this one cannot be confirmed | no |
| D | role (info@, sales@ …) | shared role inbox, not a person | no |
| D | unknown | the verifier could not decide | no |
| F | invalid | undeliverable | no |
| F | disposable | throwaway inbox domain | no |
| F | a hard bounce on record | hard bounce on record | no |
| F | the person left the company | accepts mail, person gone | no |
| F | opted out | opted out | no |
| B | on your exclusion list | deliverable | yes |
Batches and pagination
Every verify and enrich call creates a batch: { batch_id, kind, status: mapping | running | done, is_sample, progress: { done, total, percent, eta_s, eta_reason, rate_per_s }, counts, credits, webhook, upload, error, results, page: { cursor, limit, returned, next_cursor }, pending }.
- Progress: poll
GET /v1/verify/batches/:idevery few seconds, or passwebhook_url.eta_sis null witheta_reasonuntil the speed can be measured. - Batch results: in input order after
cursor(an index), up tolimit(default 500, max 1,000). Passpage.next_cursorascursoruntil it is null. - Lists such as
GET /v1/data/lookups:{ items, next_cursor },limit1–200 (default 50); passnext_cursorback as?cursor=. - Export:
GET /v1/verify/batches/:id/exportreturns CSV with your original columns plus the result columns;POST /v1/verify/batches/:id/download-linkgives a one-hour link to the results in the format you uploaded (.xlsx or .csv) with Status (✅ Valid, ❌ Invalid, ⚠️ Risky, ⚠️ Unverifiable, ⏳ Checking), Grade and Reason added.
Webhooks for batch completion
Pass webhook_url (https) when you create a batch. The create call returns webhook_secret once: store it. When the batch is done you get one POST:
{
"event": "verify.batch.completed",
"created_at": "2026-01-15T10:00:30.000Z",
"data": {
"batch_id": "…",
"status": "done",
"counts": "…",
"results": [
"… the first page …"
],
"page": {
"next_cursor": "…"
}
}
}
- Events:
verify.batch.completed(verify batches) andenrich.batch.completed(enrich batches).datacarries the first 1,000 results; page the rest withpage.next_cursor. - Headers:
x-webhook-id(the batch id),x-webhook-event,x-webhook-timestamp,x-webhook-signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. - Answer 2xx. Failures are retried with backoff, up to 5 attempts;
webhook.statuson the batch shows delivered or failed.
Checking the signature (Node):
const crypto = require('node:crypto');
// header: x-webhook-signature: t=<unix seconds>,v1=<hex>
function verified(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // 5-minute tolerance
const want = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
const got = Buffer.from(parts.v1 ?? '');
return got.length === want.length && crypto.timingSafeEqual(Buffer.from(want), got);
}
Workspace-wide webhooks (GET/POST /v1/webhooks, scopes webhooks:read / webhooks:write) are signed the same way.
Rate limits
| Limit | Value |
|---|---|
| Per API key | The key's own per-minute limit, set when it is created (default 6,000 a minute, up to 6,000), never above your plan's ceiling. Over it: 429 with retry-after |
| Items per batch | 5,000 (files: 5,000 rows, 200 columns, 20 MB) |
| Open batches | 5 running per workspace; more answers 429 too_many_batches |
| Waiting in the request | wait_s up to 25 seconds |
Errors
Errors are JSON: { error, message, issues? }. message is one plain line you can show.
| Status | Meaning |
|---|---|
| 400 | Bad input (issues lists each field) |
| 401 | Missing, unknown or revoked key |
| 402 | credits_exhausted (no credits left and no pack could be bought; the body says why and when they reset) or plan_limit |
| 403 | The key lacks the scope |
| 404 | Not found, or another workspace's id |
| 409 | Wrong state: the workspace needs a step first; the message says what to do |
| 429 | Rate limited or too_many_batches: wait retry-after seconds |
Credits
| Action | Credits | Charged |
|---|---|---|
| Verify an email | 1 | per check |
| Find a work email | 1 | only when a verified email is found |
| Find a phone number | 12 | only when a phone is found |
| Match an email to a LinkedIn profile | 20 | only when a profile is found |
| Check a phone number (mobile, landline or VoIP) | 1 | per check (a number checked in the last 90 days is free) |
| Enrich a company (industry, headcount, revenue, funding, location) | 2 | only when a new company detail is found |
| List a company using a technology | 1 | per company returned (a page with no companies is free) |
| List a job post | 1 | per job post returned (a page with none is free) |
| A company's hiring or job-post technologies | 1 | per company with data returned (none on record is free) |
| Watched-company signal delivered | 5 | per signal credit a delivered signal uses (none while monitors find nothing) |
| Check where a past champion works now | 5 | per check (each champion at most once a month) |
| Look up a phone number (valid, mobile / landline / VoIP, carrier, ported) | 1 | per number looked up (the same number again within 90 days is free) |
| Look up a phone number with its listed caller name | 2 | per number looked up, name or not (the same number again within 90 days is free) |
| Look up a phone number with its name and business / person | 6 | per number looked up, name or not (the same number again within 90 days is free) |
| Look up who a phone number belongs to (caller identity) | 12 | per number looked up, match or not (the same number again within 90 days is free) |
A repeat of the same lookup within 7 days is free; a find that finds nothing releases its credits. Sample inputs (*.example, linkedin.example, 555-01xx numbers) are free, never counted, and marked is_sample: true.