Snov.io

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:

1. Submit emails — post a list of addresses for verification. The first response usually returns not_verified because Snov queues the SMTP probe internally.
2. 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:

1. Create or find the destination list by name and keep its numeric listId.
2. Add prospects to it, either one at a time or by piping email-finder, domain-search, or database-search results into the same list.
3. Inspect the staged contents with pagination. Results are returned in reverse-chronological order and may allow up to 5000 records per page.
4. 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)

1. Confirm credit headroom before a burst.
2. 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.
3. Stage the discovered contacts into a list.
4. Verify staged addresses before sending — bad addresses tank deliverability for the whole sender.
5. 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.