Snov.io
B2B email prospecting + outreach data. Five capability areas share one credit pool: account balance + plan visibility, email finding (name + domain or whole-domain crawl), email verification, ICP database search (plan-gated), and prospect list management for staging contacts before pushing them into a campaign.
The credit model (read this first)
Every workspace has one shared credit pool that resets monthly. The pool is consumed by finding new contact data, not by searching for it.
- A search that returns "we don't know" or "we know nothing new about this contact" is free.
- A search that returns a previously-unknown email charges 1 credit. Re-searching the same email later is free (cached).
- An email verification charges 0.5 credit per verified address (or 1 credit per not_verified → verified transition, depending on plan).
- Bulk operations charge per result row, not per request — searching a domain that returns 50 emails costs 50 credits if all 50 are new.
Always inspect account balance before a credit-spending burst. The response carries the balance and the days remaining in the current billing window.
Capability areas
1. Account & balance
- Balance + plan window — current credit balance, billing-window days remaining, whether the workspace is teamwork-enabled.
Use this as the cheapest sanity check that auth is wired correctly: it returns 200 even on Trial accounts and consumes zero credits.
2. Email finding (the main free→paid funnel)
Three strategies, ranked by precision:
- By person + domain — supply firstName, lastName, domain. Returns 0–N candidate emails, each tagged with a emailStatus (unknown, valid, invalid). Highest signal when the person is publicly attached to the company. 1 credit per candidate returned.
- By whole domain — supply domain, optional type=personal|generic|all and limit (max 100 per call). Returns staff inboxes Snov has previously crawled. Cheapest per email, but biased toward larger / older companies that have been crawled. 1 credit per email returned.
- By LinkedIn URL — queue a linkedin.com/in/<slug> URL for asynchronous email discovery. Returns 200 immediately; the resolved email lands on the prospect record once Snov's worker completes. Useful when you have a name → LinkedIn map but no domain.
The single-email lookup is read-only against the existing prospect database — it does NOT call out to find a new email. Use it to check whether an address is already enriched in the workspace.
3. Email verification
Two-step async flow:
- Submit emails — post a list of addresses for verification. The first response usually returns not_verified because Snov queues the SMTP probe internally.
- Re-check the same addresses — the resolved status (valid, invalid, unknown, accept_all, etc.) appears once Snov's worker finishes, typically after a few seconds.
There is no separate "check status" endpoint — the same verify_emails call is both the submit and the poll. Use it idempotently.
4. ICP database search (API-permission gated)
The ICP database search capability searches Snov's full B2B prospect database with structured filters (countries, locations, job_titles, industries, company_sizes, seniorities, …). The search ITSELF is free; revealing a returned prospect's email costs 1 credit per profile.
Some accounts return permission errors on ICP database search even when account balance reads succeed — that usually means Snov has not enabled database-search API permission on the credential. Surface the upstream error verbatim; do not treat ICP search as available until the account is entitled.
5. Lists (the staging surface)
A Snov List is a reusable bucket of prospect records. The canonical pre-outreach flow is:
- Create or find the destination list by name and keep its numeric listId.
- Add prospects to it, either one at a time or by piping email-finder, domain-search, or database-search results into the same list.
- Inspect the staged contents with pagination. Results are returned in reverse-chronological order and may allow up to 5000 records per page.
- Push the list into an outreach campaign (Snov's own native sender or via export to another tool).
List shape: {id, name, contacts, isDeleted, creationDate, deletionDate}. Only name is stored on the list itself — there is no description / tags / metadata field at the list level. Group by naming convention (e.g. ICP-cto-saas-eu-q1).
Adding a prospect requires a non-bogus email shape (name@domain.tld) — the call validates format up front but does NOT verify deliverability (that's the verifier's job). Re-adding the same email returns added: false, updated: true rather than failing.
Operational order (do these in this sequence)
- Confirm credit headroom before a burst.
- Choose a discovery strategy:
- Have name + domain → use person-and-domain email finding.
- Have domain only → use domain email search and paginate with lastId for more than 100 results.
- Have LinkedIn URL → queue the LinkedIn URL and poll the prospect record afterwards.
- Have an ICP and a Pro+ plan → use structured ICP database search.
- Stage the discovered contacts into a list.
- Verify staged addresses before sending — bad addresses tank deliverability for the whole sender.
- Push the verified list into the outreach channel (Snov's native sender, or export to Smartlead / Instantly / Lemlist).
Error envelope
- HTTP 4xx → {"errors": {"code": <int>, "title": <str>, "source": <str>}}. The most common are 404 (endpoint typo or resource gone) and 403 (plan-gated).
- HTTP 200 with {"success": false, "message": "…"} → upstream validation failure (bad email format, missing required field). The framework raises a ToolError with the full body so the model can surface it to the caller.
Date filters
The list creation date is returned as a Snov-flavoured composite ({date, timezone_type, timezone}) rather than ISO 8601. Always read the date sub-field for the wall-clock timestamp.
