# Authentication
Source: https://docs.generect.com/api-reference/authentication

How to authenticate API requests

To authenticate requests, include your API token in the `Authorization` header.

You can get your API token from the Generect app settings.

```python theme={null}
headers = {
  "Authorization": "Token xxxxxxxxx"
}
```

The `Token` prefix is required. A raw token without the prefix will not authenticate.

## Live and test keys

Every account can hold two kinds of key, and the key decides how the API behaves. There is no separate host and no separate base URL — both go to `https://api.generect.com`.

| Key | Looks like | What it does |
| - | - | - |
| Live | `a1b2c3d4…` (32 hex characters) | Real data, charged to your balance |
| Test | `test_a1b2c3d4…` | Fictional data, same shapes and timings, charged nothing |

```python theme={null}
live = {"Authorization": "Token a1b2c3d4e5f6..."}
test = {"Authorization": "Token test_a1b2c3d4e5f6..."}
```

A response served in test mode carries `X-Generect-Mode: test`. Assert on that header in your integration tests — it is the quickest way to catch a test key that reached production, or a live key that reached a load test.

See [Test mode](/api-reference/test-mode) for magic inputs, coverage and the going-live checklist.


# Database vs Real-time
Source: https://docs.generect.com/api-reference/database-vs-realtime

Two search modes, one API — how to pick the right one

Every search and enrich operation comes in two modes that share the same request and response shape — switch between them by swapping `database` ↔ `realtime` in the path:

```
POST /search/database/leads/      POST /search/realtime/leads/
POST /enrich/database/company/    POST /enrich/realtime/company/
```

## Decision matrix

| | **Database** | **Real-time** |
| - | - | - |
| Data source | Generect's continuously growing database | Live LinkedIn lookup at request time |
| Response time | Under 1 second | 5–60 seconds |
| Price | Lower | Higher |
| Lead freshness | Updated within the last 12 months | As of the moment of the request |
| Filters | Core set (see below) | Full set — keywords, past companies, schools, groups, live signals |
| Count endpoints | Free, instant | Billable, per request |
| Nothing found | 0 results, \$0 — **no hidden live fallback** | No Data — No Charge |

<Tip>
  Start with database mode: it answers instantly and costs less. Switch the same request to realtime when you need data fresh as of today or filters database mode doesn't support.
</Tip>

## When to use which

**Use database when:**

* you process volume and care about cost and speed (list building, scoring, backfills)
* last-year freshness is acceptable for your workflow
* you want free counts to size an audience before paying for results

**Use real-time when:**

* the record must be current right now (job changes, new role verification)
* you need advanced targeting: `keywords`, `past_company_names`, `schools`, `groups`, `functions`
* you need live signals (`changed_jobs`, `posted_on_linkedin`, `mentioned_in_news`) or `search_emails`

## Filters supported in database mode

**Leads:** `job_titles`, `seniorities`, `locations`, `exclude_locations`, `company_locations`, `exclude_company_locations`, `company_industries`, `exclude_company_industries`, `company_headcounts`, `exclude_company_headcounts`, `company_types`, `gender` (database mode only) — plus targeting a single company via `company_id`, `company_link`, or `company_name`.

**Companies:** `industries`, `exclude_industries`, `headcounts`, `locations`, `exclude_locations`, `company_types`. The `sub_industries` toggle is also accepted here and behaves the same as in real-time mode (it modifies `industries` rather than counting as a filter on its own).

Anything outside this set is rejected with `400` and a message pointing to the realtime endpoint, so an unsupported *filter* is never silently ignored. At least one search filter is always required.

<Warning>
  A supported filter given an **unknown value** is a different matter, and the
  behaviour is not uniform:

  * `locations`, `company_headcounts`, `company_types` and `gender` reject an unknown
    value with `400`, naming the field (the headcount and gender errors also list the
    valid values).
  * `company_industries` / `industries` and `seniorities` do **not** validate.
    An unrecognised value simply matches nothing, so the request succeeds, returns
    `0` results and charges `\$0`.

  So `company_industries: ["Fintech"]` — not a LinkedIn industry — looks exactly
  like a real empty audience. Industry and seniority values are matched
  **exactly**: use the names from
  [ICP Search](/docs/icp-search), and when a count comes back as zero, re-check
  the spelling before concluding the audience does not exist.
</Warning>

## Billing

Both modes charge per returned result at their own rate — real-time costs more than database. If nothing is found, nothing is charged. Exact prices for your account are in your [billing settings](https://app.generect.com/settings/billing).


# Get account profile
Source: https://docs.generect.com/api-reference/endpoint/accounts/get-account-me

get /api/v1/accounts/me/
Retrieve the current account profile, credit balance, monthly usage, and Preview tier eligibility.

## Use Case:

Retrieve the current account profile, credit balance, monthly usage, and whether Preview is currently free for you.

<Note>`preview_tier` is `true` while [`POST /preview/leads/`](/api-reference/endpoint/preview/preview-leads) is free for you — that is, once your total spend in the **current calendar month** reaches \$2,000. It flips back to `false` on the 1st. It is not an access flag: permission to call the Preview endpoints is granted separately.</Note>


# Usage by token
Source: https://docs.generect.com/api-reference/endpoint/accounts/get-account-token-analytics

get /api/v1/accounts/tokens/analytics/
The same usage figures as `/accounts/usage/`, split by API token instead of totalled for the account.

This is for platforms that hand each of their own customers a separate Generect token. You get, per token: how many requests it made, which endpoints it called, and how many of those succeeded or failed — enough to attribute cost to the customer who caused it, or to spot the one client whose integration is retrying in a loop.

You only ever see your own tokens, never another account's. If you do not pass dates, the report covers the last 30 days.

## Use Case:

If you resell Generect inside your own product, you probably issue one token per customer. This endpoint tells you what each of those tokens actually did, so you can bill the right customer, see who is close to their limit, and catch a broken integration before it shows up on your invoice.

Ask for a single client with `client_id`, or leave it off to get every token at once. Tokens with no traffic in the period are still listed, at zero — useful for spotting a customer who has stopped using you.


# Get account transactions
Source: https://docs.generect.com/api-reference/endpoint/accounts/get-account-transactions

get /api/v1/accounts/transactions/
Your billing history: every charge and top-up on the account, newest first.

Filters combine with AND and are applied before paging. Every `__gte` / `__lte` parameter below has a `__gt` / `__lt` twin if you need to exclude the boundary itself, and `amount` also answers to `credits`, the name the response gives it.

One thing to watch: a value we cannot read — a misspelled status, a malformed date — is dropped rather than refused, so you get a `200` with that condition quietly missing. If a filtered call returns more than you expected, check your parameter spelling first.

## Use Case:

Audit account credit transactions and review which operations consumed credits.


# Get account usage
Source: https://docs.generect.com/api-reference/endpoint/accounts/get-account-usage

get /api/v1/accounts/usage/
Retrieve credit usage statistics and operation breakdown for an account.

## Use Case:

Review credit usage by operation type for the selected billing period.


# Find email
Source: https://docs.generect.com/api-reference/endpoint/emails/email-finder

post /api/v1/email/find/
Find a verified work email by lead ID, LinkedIn URL, or by name and domain. Billed only when a valid email is found.

<Note>
  **Important:** All generated emails are automatically validated and ready for use. No additional email validation is required - the emails returned by this endpoint are already verified for deliverability.
</Note>

## Use Case:

Reveal a work email for a lead from Preview, or find a verified email from a name and company domain.

## Pricing

This is a billable endpoint — you are charged only for each valid email found. If no email is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Start bulk email find
Source: https://docs.generect.com/api-reference/endpoint/emails/email-finder-bulk

post /api/v1/email/find/bulk/
Start an asynchronous bulk email find job. Billed only for valid emails found.

## Use Case:

Start an asynchronous bulk job to find verified work emails for many leads (up to 50 per request).

## Pricing

This is a billable endpoint — you are charged only for each valid email found. If no email is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Validate emails
Source: https://docs.generect.com/api-reference/endpoint/emails/email-validation

post /api/v1/email/validate/
Validate email deliverability and risk. Billed per email validated.

## Use Case:

Clean and verify email lists to improve campaign success rates and lower bounce rates.

## Pricing

This is a billable endpoint — you are charged for each email validated.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Get bulk email find job
Source: https://docs.generect.com/api-reference/endpoint/emails/get-email-finder-bulk

get /api/v1/email/find/bulk/{job_id}/
Retrieve the status and results of a bulk email find job.

## Use Case:

Check the status and retrieve results for a bulk email find job.

## Pricing

This endpoint is free — it does not incur any charges.


# Start bulk company enrich (database)
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-database-companies-bulk

post /api/v1/enrich/database/companies/bulk/
Start an asynchronous bulk company enrich job from cached data. Billed per enriched company; if a company is not found, no credit is charged. Max 50 companies per request.

## Use Case:

Enrich many companies at once from cached data — submit up to 50 identifiers and poll the job or receive a completion webhook.

## Pricing

This is a billable endpoint — you are charged only for each company that is found and enriched. Companies not found are free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Enrich company from database
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-database-company

post /api/v1/enrich/database/company/
Retrieve a company profile from cached data. Provide exactly one identifier.

## Use Case:

Retrieve a company profile from cached data by Generect ID, LinkedIn URL, domain, or company name.

## Optional sections

The same flags as [Real-time](/api-reference/endpoint/enrich/enrich-realtime-company) apply here: `posts`, `people_also_viewed` and `people_also_follow` each add +1 credit when the section comes back with data.

## Pricing

This is a billable endpoint — you are charged only when a company is found and returned. If nothing is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Enrich lead from database
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-database-lead

post /api/v1/enrich/database/lead/
Retrieve a full lead profile from cached data. Provide exactly one identifier.

## Use Case:

Retrieve a full lead profile from cached data by Generect ID, LinkedIn URL, or email (reverse lookup).

## Optional sections

The same activity flags as [Real-time](/api-reference/endpoint/enrich/enrich-realtime-lead) apply here: `posts`, `comments`, `reactions` and `people_also_viewed` each add +1 credit when the section comes back with data, while `get_full_experience` and `inexact_company` are free.

## Pricing

This is a billable endpoint — you are charged only when a lead is found and returned. If nothing is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Start bulk lead enrich (database)
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-database-leads-bulk

post /api/v1/enrich/database/leads/bulk/
Start an asynchronous bulk lead enrich job from cached data. Billed per enriched lead; if a lead is not found, no credit is charged. Max 50 leads per request.

## Use Case:

Enrich many leads at once from cached data — submit up to 50 identifiers and poll the job or receive a completion webhook.

## Pricing

This is a billable endpoint — you are charged only for each lead that is found and enriched. Leads not found are free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Start bulk company enrich (realtime)
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-realtime-companies-bulk

post /api/v1/enrich/realtime/companies/bulk/
Start an asynchronous bulk company enrich job with live data. Billed per enriched company; if a company is not found, no credit is charged. Max 50 companies per request.

## Use Case:

Enrich many companies at once with live data — submit up to 50 identifiers and poll the job or receive a completion webhook.

## Pricing

This is a billable endpoint — you are charged only for each company that is found and enriched. Companies not found are free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Enrich company in realtime
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-realtime-company

post /api/v1/enrich/realtime/company/
Retrieve a fresh company profile. Provide exactly one identifier.

## Use Case:

Retrieve a fresh company profile by Generect ID, LinkedIn URL, domain, or company name.

## Optional sections

Company activity and audience lists are opt-in — each flag adds +1 credit when the section comes back with data:

| Flag | Adds |
| - | - |
| `posts` | The company page's recent posts |
| `people_also_viewed` | Companies LinkedIn lists under "People also viewed" |
| `people_also_follow` | Companies LinkedIn lists under "People also follow" |

## Pricing

This is a billable endpoint — you are charged only when a company is found and returned. If nothing is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Enrich lead in realtime
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-realtime-lead

post /api/v1/enrich/realtime/lead/
Retrieve a fresh lead profile. Supports internal ID, LinkedIn URL, or email reverse lookup. If no data is found, the request is free.

## Use Case:

Retrieve a fresh lead profile, including reverse email lookup, by Generect ID, LinkedIn URL, or email.

## Optional sections

Recent LinkedIn activity and the "People also viewed" list are opt-in — send the flag to get the section back:

| Flag | Adds | Extra cost |
| - | - | - |
| `posts` | The lead's recent posts | +1 credit |
| `comments` | The lead's recent comments | +1 credit |
| `reactions` | The lead's recent reactions (likes) | +1 credit |
| `people_also_viewed` | Profiles LinkedIn lists under "People also viewed" | +1 credit |
| `get_full_experience` | Past positions on top of the current ones | free |
| `inexact_company` | Fuzzy company match when the exact company cannot be resolved | free |

<Note>An extra credit is only charged for a section that actually comes back with data. Requesting `posts` on a lead who never posted costs nothing.</Note>

## Pricing

This is a billable endpoint — you are charged only when a lead is found and returned. If nothing is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Start bulk lead enrich (realtime)
Source: https://docs.generect.com/api-reference/endpoint/enrich/enrich-realtime-leads-bulk

post /api/v1/enrich/realtime/leads/bulk/
Start an asynchronous bulk lead enrich job with live data. Billed per enriched lead; if a lead is not found, no credit is charged. Max 50 leads per request.

## Use Case:

Enrich many leads at once with live data — submit up to 50 identifiers and poll the job or receive a completion webhook.

## Pricing

This is a billable endpoint — you are charged only for each lead that is found and enriched. Leads not found are free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Get bulk company enrich job
Source: https://docs.generect.com/api-reference/endpoint/enrich/get-companies-bulk

get /api/v1/enrich/companies/bulk/{job_id}/

## Use Case:

Check the status and retrieve results for a bulk company enrich job.

## Pricing

This endpoint is free — it does not incur any charges.


# Get bulk lead enrich job
Source: https://docs.generect.com/api-reference/endpoint/enrich/get-leads-bulk

get /api/v1/enrich/leads/bulk/{job_id}/

## Use Case:

Check the status and retrieve results for a bulk lead enrich job.

## Pricing

This endpoint is free — it does not incur any charges.


# Get bulk phone find job
Source: https://docs.generect.com/api-reference/endpoint/phone/get-phone-finder-bulk

get /api/v1/phone/find/bulk/{job_id}/
Retrieve the status and results of a bulk phone finder job.

## Use Case:

Check the status and retrieve results for a bulk phone finder job.

## Pricing

This endpoint is free — it does not incur any charges.


# Find phone
Source: https://docs.generect.com/api-reference/endpoint/phone/phone-finder

post /api/v1/phone/find/
Find a phone number by lead ID, LinkedIn URL, or by name and company. Billed only when a phone number is found.

## Use Case:

Find a phone number by `lead_id`, `linkedin_url`, or by `first_name` + `last_name` + `company`.

## Pricing

This is a billable endpoint — you are charged only for each phone number found. If no phone is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Start bulk phone find
Source: https://docs.generect.com/api-reference/endpoint/phone/phone-finder-bulk

post /api/v1/phone/find/bulk/
Start an asynchronous bulk phone finder job. Billed only for phone numbers found.

## Use Case:

Start an asynchronous bulk phone finder job (up to 50 leads per request).

## Pricing

This is a billable endpoint — you are charged only for each phone number found. If no phone is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Count preview leads
Source: https://docs.generect.com/api-reference/endpoint/preview/count-preview-leads

post /api/v1/preview/leads/count/
Count matching database leads for Preview. Count requests are always free.

## Use Case:

Estimate the number of matching Preview leads before displaying or revealing results.

## Pricing

**Always free** — sizing a Preview audience never costs anything, including once [`POST /preview/leads/`](/api-reference/endpoint/preview/preview-leads) bills you \$0.002 per returned result.


# Preview leads
Source: https://docs.generect.com/api-reference/endpoint/preview/preview-leads

post /api/v1/preview/leads/
Search database leads with masked response data. Preview results include an internal lead ID for later enrichment and do not include LinkedIn URL, company domain, email, or phone. Billed at \$0.002 per returned row — a search that matches nothing is free — and free for the rest of the calendar month once the account's total spend that month reaches \$2,000 (see `preview_tier` on `GET /api/v1/accounts/me/`).

## Use Case:

Show masked lead results in SaaS products without exposing paid data such as email, phone, LinkedIn URL, or company domain.

## Pricing

**\$0.002 per returned result** — one charge per masked row this endpoint returns, and a search that matches nothing costs \$0. Preview is never discounted by volume: the price is the same on every [Spend & Save tier](/billing/managing-billing).

<Note>
  **Free above \$2,000 a month.** Once your account's total spend within the current calendar month reaches \$2,000, this endpoint costs nothing for the rest of that month. The counter covers every charge on the account, not only Preview, and it restarts on the 1st (UTC) — requests are billable again from then. The `preview_tier` flag on [`GET /accounts/me/`](/api-reference/endpoint/accounts/get-account-me) tells you which side of the threshold you are on.
</Note>

Always free, whatever your spend: [`POST /preview/leads/count/`](/api-reference/endpoint/preview/count-preview-leads), and Preview inside the Generect web app — \$0.002 is the API price.


# Count database companies
Source: https://docs.generect.com/api-reference/endpoint/search/count-database-companies

post /api/v1/search/database/companies/count/
Count cached companies matching filters. Always free.

## Use Case:

Count matching cached companies before running a database company search.

## Pricing

This endpoint is free — it does not incur any charges.


# Count database company leads
Source: https://docs.generect.com/api-reference/endpoint/search/count-database-company-leads

post /api/v1/search/database/company-leads/count/
Count cached company-lead matches. Database count endpoints are free.

## Use Case:

Count cached company-lead matches before retrieving them.

## Pricing

This endpoint is free — it does not incur any charges.


# Count database leads
Source: https://docs.generect.com/api-reference/endpoint/search/count-database-leads

post /api/v1/search/database/leads/count/
Count cached leads matching filters. Always free.

## Use Case:

Count matching cached leads before running a database lead search.

## Pricing

This endpoint is free — it does not incur any charges.


# Count realtime companies
Source: https://docs.generect.com/api-reference/endpoint/search/count-realtime-companies

post /api/v1/search/realtime/companies/count/
Count fresh companies matching filters. Billed per request.

## Use Case:

Count matching realtime companies before running a fresh company search.

## Pricing

This is a billable endpoint — you are charged per count request.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Count realtime leads
Source: https://docs.generect.com/api-reference/endpoint/search/count-realtime-leads

post /api/v1/search/realtime/leads/count/
Count fresh leads matching filters. Billed per request.

## Use Case:

Count matching realtime leads before running a fresh lead search.

## Pricing

This is a billable endpoint — you are charged per count request.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Search database companies
Source: https://docs.generect.com/api-reference/endpoint/search/database-companies

post /api/v1/search/database/companies/
Search cached companies. Database mode returns results in under 1 second. Billed per result returned.

## Use Case:

Search cached company data with database filters.

## Pricing

This is a billable endpoint — you are charged for each result returned. If no results are found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Search database company leads
Source: https://docs.generect.com/api-reference/endpoint/search/database-company-leads

post /api/v1/search/database/company-leads/
Search cached leads at matching companies.

## Use Case:

Find cached leads at matching companies.

## Pricing

This is a billable endpoint — you are charged for each result returned. If no results are found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Search database leads
Source: https://docs.generect.com/api-reference/endpoint/search/database-leads

post /api/v1/search/database/leads/
Search cached leads. Database mode returns results in under 1 second. Billed per result returned.

## Use Case:

Search cached lead data with fast database filters.

## Pricing

This is a billable endpoint — you are charged for each result returned. If no results are found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Search realtime companies
Source: https://docs.generect.com/api-reference/endpoint/search/realtime-companies

post /api/v1/search/realtime/companies/
Search fresh companies with advanced filters (revenue, department headcount, growth). Response time 5-60 sec. Billed per result returned.

## Use Case:

Search fresh company data with full realtime filters.

## Pricing

This is a billable endpoint — you are charged for each result returned. If no results are found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Search realtime company leads
Source: https://docs.generect.com/api-reference/endpoint/search/realtime-company-leads

post /api/v1/search/realtime/company-leads/
Search fresh leads at matching companies.

## Use Case:

Find fresh leads at matching companies.

## Pricing

This is a billable endpoint — you are charged for each result returned. If no results are found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Search realtime leads
Source: https://docs.generect.com/api-reference/endpoint/search/realtime-leads

post /api/v1/search/realtime/leads/
Search fresh leads with advanced filters (keywords, past companies, schools, groups). Response time 5-60 sec. Billed per result returned.

## Use Case:

Search fresh lead data with full realtime filters.

## Pricing

This is a billable endpoint — you are charged for each result returned. If no results are found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Register webhook
Source: https://docs.generect.com/api-reference/endpoint/webhooks/create-webhook

post /api/v1/webhooks/
Register a webhook endpoint for async notifications.

## Use Case:

Register a webhook endpoint for asynchronous job notifications.


# Delete webhook
Source: https://docs.generect.com/api-reference/endpoint/webhooks/delete-webhook

delete /api/v1/webhooks/{id}/
Remove a registered webhook endpoint.

## Use Case:

Remove a registered webhook endpoint.


# Retrieve webhook
Source: https://docs.generect.com/api-reference/endpoint/webhooks/get-webhook

get /api/v1/webhooks/{id}/
Retrieve a single registered webhook endpoint.

## Use Case:

Retrieve a single registered webhook endpoint by id.


# List webhooks
Source: https://docs.generect.com/api-reference/endpoint/webhooks/list-webhooks

get /api/v1/webhooks/
List registered webhook endpoints.

## Use Case:

List registered webhook endpoints.


# Webhooks
Source: https://docs.generect.com/api-reference/endpoint/webhooks/overview

Get notified when async jobs complete — delivery format, signature verification, retries

Webhooks let you register a callback URL once and receive a `POST` with the **full job results** the moment an asynchronous job finishes — no polling. The delivery is self-contained: everything the bulk status endpoint would return is in the payload.

## Events

### Job events

Scoped to your account — you only receive deliveries for jobs you started.

| Event | Fired when |
| - | - |
| `email.find.bulk.completed` | A [bulk email finder](/api-reference/endpoint/emails/email-finder-bulk) job finishes (or fails) |
| `phone.find.bulk.completed` | A [bulk phone finder](/api-reference/endpoint/phone/phone-finder-bulk) job finishes (or fails) |
| `enrich.lead.bulk.completed` | A [bulk lead enrich](/api-reference/endpoint/enrich/enrich-database-leads-bulk) job finishes (or fails) |
| `enrich.company.bulk.completed` | A [bulk company enrich](/api-reference/endpoint/enrich/enrich-database-companies-bulk) job finishes (or fails) |

### Status page events

Broadcast events from [status.generect.com](https://status.generect.com) — subscribe to pipe Generect incidents into your own alerting instead of polling the status page.

| Event | Fired when |
| - | - |
| `status.incident.created` | An incident is opened |
| `status.incident.updated` | A new update is posted on an open incident |
| `status.incident.resolved` | An incident is resolved |
| `status.maintenance.started` | Scheduled maintenance starts |
| `status.maintenance.completed` | Scheduled maintenance completes |

Incident deliveries carry `data.incident` (slug, title, status, severity, body, affected `components`, `started_at` / `resolved_at`, full `updates` history) and `data.update` with the update that triggered the event. Maintenance deliveries carry `data.maintenance` (slug, title, body, status, `scheduled_start` / `scheduled_end`, affected `components`). `meta.status_page_url` points back to the public page.

<Note>
  Status page events are not tied to your account activity: every active webhook subscribed to them receives every incident, so a single webhook is enough per organization.
</Note>

## Delivery format

Each delivery is an HTTP `POST` to your URL with a JSON body:

```json theme={null}
{
  "event": "email.find.bulk.completed",
  "timestamp": "2026-06-11T12:00:00.123456",
  "data": [
    {
      "lead_id": "ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9",
      "valid_email": "jordan.ellis@microsoft.com",
      "result": "valid",
      "catch_all": false,
      "source": "generect"
    }
  ],
  "meta": {
    "job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "completed",
    "total": 100,
    "processed": 100,
    "found": 87,
    "not_found": 13,
    "amount_charged": 1.74,
    "error": null
  }
}
```

The payload uses the same `data` / `meta` envelope as every other endpoint, plus the webhook's own `event` and `timestamp` on top. `data` is the **results** array — exactly what the matching bulk status endpoint ([email](/api-reference/endpoint/emails/get-email-finder-bulk) / [phone](/api-reference/endpoint/phone/get-phone-finder-bulk)) returns under its `data` key, so you never have to poll. `meta` is the job **summary**: `job_id`, `status`, counts (`total` / `processed` / `found` / `not_found`), `amount_charged` in USD, and `error` when `status` is `error`. The bulk status endpoint stays available to re-fetch by `job_id` — results are retained for 24 hours.

<Note>
  `data` is present on both success and failure deliveries. When `status` is `error` it is an empty array and `meta.error` describes what went wrong.
</Note>

**Headers sent with every delivery:**

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `X-Webhook-Event` | The event type, same as `event` in the body |
| `X-Webhook-Timestamp` | Delivery timestamp, same as `timestamp` in the body |
| `X-Webhook-Signature` | Base64-encoded HMAC-SHA256 of the raw request body |

## Verifying signatures

Every webhook is signed with your webhook's `secret`. If you don't provide one at registration, a cryptographically strong secret is generated for you — it is returned by the create and get endpoints.

The signature is `base64(HMAC_SHA256(secret, raw_body))`. Always compute it over the **raw request bytes**, before any JSON parsing, and compare in constant time:

<CodeGroup>
  ```python Python theme={null}
  import base64
  import hashlib
  import hmac

  def verify(secret: str, raw_body: bytes, signature: str) -> bool:
      digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).digest()
      expected = base64.b64encode(digest).decode("utf-8")
      return hmac.compare_digest(expected, signature)

  # in your handler:
  # verify(secret, request.body, request.headers["X-Webhook-Signature"])
  ```

  ```javascript Node.js theme={null}
  const crypto = require("crypto");

  function verify(secret, rawBody, signature) {
    const expected = crypto
      .createHmac("sha256", secret)
      .update(rawBody)
      .digest("base64");
    return (
      expected.length === signature.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
    );
  }
  ```
</CodeGroup>

<Warning>
  Reject deliveries with a missing or invalid signature. The signature is your only guarantee the payload came from Generect.
</Warning>

## Retries and timeouts

| Policy | Value |
| - | - |
| Response timeout | 30 seconds |
| Success criteria | Any `2xx` response |
| Your endpoint returns `4xx` | Delivery marked failed, **no retries** |
| `5xx` / network error / timeout | Retried with exponential backoff |
| Attempts | 5 total (1 initial + 4 retries) |
| Backoff | 10s → 20s → 40s → 80s between attempts |

<Tip>
  Respond `2xx` immediately and process the payload asynchronously — a handler slower than 30 seconds counts as a failed attempt.
</Tip>

## Testing

Send a test delivery to any registered webhook with [`POST /webhooks/{id}/test/`](/api-reference/endpoint/webhooks/test-webhook) — it fires a `webhook.test` event through the same delivery pipeline, signature included.


# Test webhook
Source: https://docs.generect.com/api-reference/endpoint/webhooks/test-webhook

post /api/v1/webhooks/{id}/test/
Send a sample `webhook.test` delivery to this webhook's URL.

## Use Case:

Send a sample `webhook.test` delivery to a registered webhook endpoint to verify your receiver.


# Update webhook
Source: https://docs.generect.com/api-reference/endpoint/webhooks/update-webhook

put /api/v1/webhooks/{id}/
Replace a webhook endpoint's configuration.

## Use Case:

Update a registered webhook endpoint — change its URL, subscribed events, or signing secret. Use `PATCH` for partial updates.


# Errors
Source: https://docs.generect.com/api-reference/errors

HTTP status codes, error response format, and how to handle failures

Every error response uses the same JSON envelope, so you can handle failures with one code path.

## Error response format

```json theme={null}
{
  "status": "error",
  "status_code": 400,
  "detail": "Human-readable description of what went wrong"
}
```

* `status` — always `"error"` for a failed request.
* `status_code` — mirrors the HTTP status code.
* `detail` — a message string, or, for validation failures, an object keyed by the invalid field.

A validation error looks like this:

```json theme={null}
{
  "status": "error",
  "status_code": 400,
  "detail": { "company_id": "exactly one of company_id, company_link, company_name is required" }
}
```

## Status codes

| Code | Meaning | When it happens |
| - | - | - |
| `400` | Bad Request | Missing or invalid parameters, an unsupported filter for the chosen mode, a malformed LinkedIn URL, or a lookup that matched no record. |
| `401` | Unauthorized | Missing `Authorization` header or an invalid token. See [Authentication](/api-reference/authentication). |
| `402` | Payment Required | Not enough balance to run the operation (`"Insufficient funds in the account."`). Top up in your [billing settings](https://app.generect.com/settings/billing). |
| `403` | Forbidden | Your account or API key is not entitled to this endpoint. |
| `404` | Not Found | The requested resource does not exist — for example, a lead that can't be found by the provided email. |
| `429` | Too Many Requests | You exceeded a per-operation [rate or parallel-request limit](/api-reference/limits). Back off and retry. |
| `500` | Server Error | Something failed on our side. Safe to retry with backoff; if it persists, contact [support](mailto:support@generect.com). |

## No data is never billed

A "not found" result — an enrichment, email, or phone lookup that returns no match — is **not charged**. Any credits reserved for the call are released automatically, so treat a not-found response as a normal, free outcome rather than a billing event. See [Pay-as-you-go](/billing/pay-as-you-go).

## Handling retries

`429` and `5xx` responses are transient. Retry them with **exponential backoff** (for example 1s, 2s, 4s, 8s) instead of retrying immediately in a tight loop.

<Tip>
  Real-time operations can legitimately take up to a minute. Set client timeouts to match the [recommended timeouts](/api-reference/limits) before treating a slow response as a failure.
</Tip>

<Info>
  A `4xx` response (other than `429`) means the request itself needs to change — fix the input and resend; retrying the same request unchanged will return the same error.
</Info>


# Introduction
Source: https://docs.generect.com/api-reference/introduction

Real-time B2B contact and company data API. LinkedIn-grade accuracy, live verification, pay per result.

# **Welcome to Generect Live API**

**Unlock real-time, accurate data directly from its source.**

Our API stands apart as each request is sent directly to live data sources, including LinkedIn, Crunchbase, websites, and our internal AI-powered system. Unlike static databases, the Generect Live API ensures up-to-date information with every call.

## **Core Unique Selling Proposition:**

* **Dynamic Data:** All queries pull fresh data directly from social platforms, ensuring real-time accuracy.
* **Email Finder:** Using AI, we intelligently guess email addresses based on provided inputs (e.g., first name, last name, and domain) and validate them with our proprietary in-house system.
* **Catch-All Validation:** We validate even catch-all domains, reducing risky addresses to just 10% compared to 40-50% with other providers.

Whether you're searching for leads, companies, or validating emails, Generect Live API ensures the highest data quality for your use cases.

API base URL: `https://api.generect.com` — every endpoint path in this reference is relative to this host. Newer endpoints live under `/api/v1/...`, legacy endpoints under `/api/...`; use each path exactly as shown on its page.

<Tip>
  Don't forget to add `/` in the end of URL for every request.
</Tip>

Live uptime and incident history: [status.generect.com](https://status.generect.com)

## OpenAPI Specification

The complete machine-readable API definition behind this reference — import it into Postman, Insomnia, or your code generator.

<Card title="Download the OpenAPI spec" icon="file-code" href="https://docs.generect.com/api-reference/openapi.yaml">
  OpenAPI 3.0 — every endpoint, request, and response in one file
</Card>

Also available from the **⋯** menu on any API Reference page (**Download API spec**), alongside *Copy page* and *Open in ChatGPT / Claude*.

# Integrations

## MCP (Model Context Protocol)

Recently, we are introduced integration of our API into AI. You can read about this here:

<Card title="About MCP" icon="brain-circuit" href="/integrations/mcp/quick-start">
  Section about Generect's MCP
</Card>

## OpenAI Agent Builder

If you want to use Generect in Agent Builder — read about it here:

<Card title="Agent Builder" icon="openai" href="/integrations/agent-builder/agent-builder">
  Section about Agent Builder
</Card>

# Use Cases

<Card title="Use Cases & Best Practices" icon="lightbulb" href="/use-cases/saas/introduction">
  Read about real-world use cases and best practices
</Card>


# Limits
Source: https://docs.generect.com/api-reference/limits

Rate limits, parallel requests and recommended timeouts

## Rate limits

You can request data depending on your data plan and account balance (default: `10000/month`). Pricing depends on the operation and the number of results returned, and may increase with additional data flags. For exact pricing, see each endpoint's **Pricing** section or your [billing settings](https://app.generect.com/settings/billing).

## Parallel requests limit

* [Company search](/api-reference/endpoint/search/realtime-companies) — `POST /search/*/companies/`: 20 requests

* [Company enrichment](/api-reference/endpoint/enrich/enrich-realtime-company) — `POST /enrich/*/company/`: 50 requests

* [Lead search](/api-reference/endpoint/search/realtime-leads) — `POST /search/*/leads/`: 50 requests

* [Lead enrichment](/api-reference/endpoint/enrich/enrich-realtime-lead) — `POST /enrich/*/lead/`: 500 requests

* [Preview](/api-reference/endpoint/preview/preview-leads) — `POST /preview/leads/` and `POST /preview/leads/count/`: 100 requests

## Recommended timeouts

* [Company search](/api-reference/endpoint/search/realtime-companies): 300 seconds

* [Company enrichment](/api-reference/endpoint/enrich/enrich-realtime-company): 60 seconds

* [Lead search](/api-reference/endpoint/search/realtime-leads): 300 seconds

* [Lead enrichment](/api-reference/endpoint/enrich/enrich-realtime-lead): 100 seconds

## Which endpoints are rate-limited

The parallel-request limits above apply to **search**, **enrich**, and **Preview** endpoints. **Email Finder, Email Validation, Phone Finder, bulk jobs, search count endpoints, and account/webhook endpoints have no parallel-request cap** — they are bounded only by your balance and, for bulk jobs, the [50-item limit per request](/use-cases/api/bulk-processing).

Both Preview endpoints share one 100-request budget, including the free `POST /preview/leads/count/`.

Limits are enforced per **API token + source IP**, per operation type. Exceeding one returns HTTP `429` — see [Errors](/api-reference/errors) — so retry with **exponential backoff**.

## Batch size caps

* **Bulk jobs** (enrich bulk, email find bulk, phone find bulk): up to **50 items** per request; a larger array is rejected with `400`.
* **`POST /email/validate/`** has no fixed array cap, but it is a synchronous endpoint — response time grows with batch size. Keep batches to **\~50 emails** per request and parallelize, matching the bulk-endpoint convention.

Responses do not currently include `X-RateLimit-*` or `Retry-After` headers — on a `429`, apply exponential backoff (see [Errors](/api-reference/errors)).

## Capacity limits on live data

Real-time single-lead enrichment and real-time search can also return `429` during exceptionally high live-source load — a temporary capacity guard, separate from the parallel limits above. Handle it the same way: back off and retry.

<Info>Limits apply per operation type and cover both database and realtime modes. They can be increased upon request.</Info>


# Migration Guide
Source: https://docs.generect.com/api-reference/migration-guide

Moving from Apollo, Hunter, or ZoomInfo — or from our own legacy endpoints — to the Generect API

Already integrated with another data provider? Most concepts map directly onto Generect endpoints. Start here, then open the matching endpoint reference for request and response details.

## Before you map endpoints

A few things work differently on Generect — knowing them up front makes the mapping obvious:

* **Authentication** uses an `Authorization: Token <your_token>` header (the `Token` prefix is required). See [Authentication](/api-reference/authentication).
* **Pricing is pay-as-you-go credits**, not seats or monthly contact caps. You are billed per returned result, and [no data is never charged](/billing/pay-as-you-go).
* **Every search and enrich endpoint has two modes** — `database` (cached, sub-second, cheaper) and `realtime` (live lookup, freshest, costs more). You choose per call by swapping `database` ↔ `realtime` in the path. See [Database vs Real-time](/api-reference/database-vs-realtime).
* **Counts are free in database mode** and billable in real-time mode — size an audience with a free count before paying for results.

## From Apollo

| Apollo | Generect |
| - | - |
| People Search (`mixed_people/search`) | [`POST /search/{database\|realtime}/leads/`](/api-reference/endpoint/search/database-leads) |
| People Enrichment / Bulk Match (`people/match`) | [`POST /enrich/{database\|realtime}/lead/`](/api-reference/endpoint/enrich/enrich-database-lead) |
| Organization Search | [`POST /search/{database\|realtime}/companies/`](/api-reference/endpoint/search/database-companies) |
| Organization Enrichment (`organizations/enrich`) | [`POST /enrich/{database\|realtime}/company/`](/api-reference/endpoint/enrich/enrich-database-company) |
| Email reveal (bundled into enrichment) | [`POST /email/find/`](/api-reference/endpoint/emails/email-finder) |

## From Hunter

| Hunter | Generect |
| - | - |
| Email Finder | [`POST /email/find/`](/api-reference/endpoint/emails/email-finder) |
| Bulk Email Finder | [`POST /email/find/bulk/`](/api-reference/endpoint/emails/email-finder-bulk) |
| Email Verifier | [`POST /email/validate/`](/api-reference/endpoint/emails/email-validation) |
| Domain Search (people at a company) | [`POST /search/{database\|realtime}/company-leads/`](/api-reference/endpoint/search/database-company-leads), then `POST /email/find/` |
| Company / Person Enrichment | [`POST /enrich/{database\|realtime}/company/`](/api-reference/endpoint/enrich/enrich-database-company) · [`/lead/`](/api-reference/endpoint/enrich/enrich-database-lead) |

## From ZoomInfo

| ZoomInfo | Generect |
| - | - |
| Contact Search | [`POST /search/{database\|realtime}/leads/`](/api-reference/endpoint/search/database-leads) |
| Contact Enrich | [`POST /enrich/{database\|realtime}/lead/`](/api-reference/endpoint/enrich/enrich-database-lead) |
| Company Search | [`POST /search/{database\|realtime}/companies/`](/api-reference/endpoint/search/database-companies) |
| Company Enrich | [`POST /enrich/{database\|realtime}/company/`](/api-reference/endpoint/enrich/enrich-database-company) |
| Phone append | [`POST /phone/find/`](/api-reference/endpoint/phone/phone-finder) |

<Tip>
  Records carry a stable `id` across Preview, Search, and Enrich. Find leads with a cheap [Preview](/api-reference/endpoint/preview/preview-leads) or database search, then pass the `id` into Enrich or Email Finder instead of re-sending name and company.
</Tip>

## Migrating from our legacy endpoints

This section maps all legacy `api` endpoints to their `api/v1` replacements.

* **Base URL** — unchanged: `https://api.generect.com` (only the path structure changed)
* **Auth** — unchanged: header `Authorization: Token <your_api_token>`

<Warning>
  The four legacy `by_icp` search endpoints are already marked `deprecated` in the API spec. They still work today, but migrate these first.
</Warning>

General changes across all endpoints:

1. Old paths were under `/api/...`. New paths are versioned under `/api/v1/...` and grouped by resource (`email`, `enrich`, `search`, `accounts`).
2. Every new response is wrapped in a top-level object:
   ```json theme={null}
   { "data": { ... }, "meta": { "amount_charged": 0.02 } }
   ```
   Previously the payload was returned flat (no `data`/`meta` wrapper). Update your response parsing to read from `response.data` and `response.meta`.
3. Billing/pricing behavior is unchanged: you're only charged when a valid result is found (`meta.amount_charged = 0` otherwise).
4. New endpoints accept multiple identifier types in one endpoint (send only ONE per request) instead of separate endpoints per identifier type.

### Auth & Account

<AccordionGroup>
  <Accordion title="1. Token login — retired, no v1 equivalent">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | *(none)* |
    | Path | `/api/auth/token/login/` | *(none)* |

    v1 has no login flow — every request authenticates with a static API key from [account settings](https://app.generect.com/settings/billing), sent as `Authorization: Token <key>`. Drop the login call and store the key directly.
  </Accordion>

  <Accordion title="2. Get account profile">
    | | Old | New |
    | - | - | - |
    | Method | `GET` | `GET` |
    | Path | `/api/auth/users/me/` | `/api/v1/accounts/me/` |

    **Response field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `email` | `data.email` | Unchanged. |
    | `full_name` | `data.name` | Renamed. |
    | `subscription` | `data.plan` | Renamed. |
    | `balance_platform`, `max_credits`, `blocked_balance_platform` | `data.credits.{balance, used_this_month, monthly_limit}` | Dozens of per-operation `balance_*` fields collapse into one `credits` object. |
    | `balance_leads_by_icp`, `balance_email_finder`, etc. | — | Removed — see [Usage](/api-reference/endpoint/accounts/get-account-usage) instead. |
    | — | `data.id` | New: stable account identifier. |
    | — | `data.preview_tier` | New: `true` while Preview is free for the account — total spend in the current calendar month has reached \$2,000. Not an access flag. |

    **Example — before / after:**

    <CodeGroup>
      ```json Before (legacy) theme={null}
      {
        "email": "admin@example.com",
        "full_name": "",
        "subscription": "Business",
        "balance_platform": 8531,
        "max_credits": 10000,
        "balance_leads_by_icp": -1719,
        "balance_email_finder": 0
      }
      ```

      ```json After (v1) theme={null}
      {
        "data": {
          "id": "usr_8f2a1c",
          "email": "admin@example.com",
          "name": "",
          "plan": "Business",
          "credits": { "balance": 8531, "used_this_month": 1719, "monthly_limit": 10000 },
          "preview_tier": true
        }
      }
      ```
    </CodeGroup>

    Full reference: [Get Account](/api-reference/endpoint/accounts/get-account-me)
  </Accordion>

  <Accordion title="3. List transactions">
    | | Old | New |
    | - | - | - |
    | Method | `GET` | `GET` |
    | Path | `/api/auth/transactions/` | `/api/v1/accounts/transactions/` |

    **Response field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `results[].id` | `data.transactions[].id` | Unchanged. |
    | `results[].created_at` | `data.transactions[].timestamp` | Renamed. |
    | `results[].amount` | `data.transactions[].credits` | Renamed. |
    | `results[].balance_type` | `data.transactions[].type` | Renamed. |
    | `results[].status` | `data.transactions[].details.status` | Nested. |
    | `results[].updated_at`, `description`, `after_balance` | — | Removed. |
    | `count`, `limit`, `offset`, `next`, `previous` | — | Pagination params changed — see full reference. |

    Full reference: [List Transactions](/api-reference/endpoint/accounts/get-account-transactions)
  </Accordion>

  <Accordion title="4. Spent credits → Usage">
    | | Old | New |
    | - | - | - |
    | Method | `GET` | `GET` |
    | Path | `/api/auth/transactions/spent_credits/` | `/api/v1/accounts/usage/` |

    **Response field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `spent_credits[date][old_endpoint_path]` | `data.breakdown{operation_type: credits}` | Keyed by operation type instead of a raw legacy path; one `period` per call instead of a full multi-period map. |
    | `total_spent_credits` | `data.total_credits` | Renamed, now positive. |

    Full reference: [Usage](/api-reference/endpoint/accounts/get-account-usage)
  </Accordion>
</AccordionGroup>

### Search (ICP)

<AccordionGroup>
  <Accordion title="5. Search leads by ICP">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/leads/by_icp/` | `/api/v1/search/{database\|realtime}/leads/` |

    **Request** — most filters keep their name: `locations`, `personas`, `company_locations`, `company_headcounts`, `company_types`, `limit_by`, `offset_by`, `exclude_names`, `exclude_ids`, `filter_empty_vars`, `company_link`, `company_id`.

    New: `job_titles`, `seniorities`, `exclude_locations`, `exclude_company_locations`, `exclude_company_industries`, `exclude_company_headcounts`, `strict`, `company_name` (any mode) and `keywords`, `functions` (realtime mode only) — not required for a straight migration, but available if useful.

    **Request field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `lead_industries` | `company_industries` | Renamed. |
    | `without_company` | — | Removed — omit all company identifiers instead. |
    | `mentioned_in_news` | — | Removed — no v1 equivalent in either mode. |
    | `changed_jobs`, `posted_on_linkedin`, `groups`, `schools`, `linkedin_filter_link`, `years_in_company`, `years_in_position`, `past_company_names` | same names | Realtime mode only — no longer accepted in `database` mode. |

    **Response:** item field names largely match [Enrich lead](#enrich) (`title`, nested `company` object, etc.), but each item's identifier is returned as `lead_id`, not `id`. `amount` → `meta.amount_charged` (positive now); `status` removed.

    Full reference: [Search leads](/api-reference/endpoint/search/database-leads) · [Realtime](/api-reference/endpoint/search/realtime-leads)
  </Accordion>

  <Accordion title="6. Count leads by ICP">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/leads/by_icp/get_count/` | `/api/v1/search/{database\|realtime}/leads/count/` |

    Same request filters as Search leads. `results_count`/`status` → `data.results_count`. Database-mode counts are always free; realtime counts are billable.

    Full reference: [Count leads](/api-reference/endpoint/search/count-database-leads) · [Realtime](/api-reference/endpoint/search/count-realtime-leads)
  </Accordion>

  <Accordion title="7. Search companies by ICP">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/companies/by_icp/` | `/api/v1/search/{database\|realtime}/companies/` |

    **Request** — most filters keep their name: `company_types`, `headcounts`, `industries`, `keywords`, `locations`, `num_of_followers`, `limit_by`, `offset_by`. New: `exclude_industries`, `exclude_locations`, `exclude_ids`, `exclude_domains`, `technologies`, `company_names`, `strict` (any mode) and `revenues_range`, `department_headcount`, `headcount_growth`, `hiring_on_linkedin`, `linkedins_links` (realtime mode only).

    **Request field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `get_max_companies` | — | Removed, no v1 equivalent. |
    | `revenues_range` | `revenues_range` | Same `{min, max}` shape, but now realtime mode only. |
    | `website_blacklist` | — | Removed, no v1 equivalent. |

    **Response:** item field names largely match [Enrich company](#enrich), but each item's identifier is returned as `linkedin_id`, not `id`. `amount` → `meta.amount_charged` (positive now); `time_cached` removed.

    Full reference: [Search companies](/api-reference/endpoint/search/database-companies) · [Realtime](/api-reference/endpoint/search/realtime-companies)
  </Accordion>

  <Accordion title="8. Count companies by ICP">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/companies/by_icp/get_count/` | `/api/v1/search/{database\|realtime}/companies/count/` |

    Same request filters as Search companies. `results_count` → `data.results_count`. Database-mode counts are always free; realtime counts are billable.

    Full reference: [Count companies](/api-reference/endpoint/search/count-database-companies) · [Realtime](/api-reference/endpoint/search/count-realtime-companies)
  </Accordion>
</AccordionGroup>

### Enrich

<AccordionGroup>
  <Accordion title="9. Enrich company by URL">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/companies/by_link/` | `/api/v1/enrich/{database\|realtime}/company/` |

    **Request** — send exactly ONE identifier field (was: LinkedIn company URL / company website):

    | Old input | New field |
    | - | - |
    | LinkedIn company URL | `linkedin_url` |
    | Company website | `domain` |

    The new endpoint also accepts `id` (Generect internal company ID) or `name` (fuzzy match) — extra options, not required for migration.

    **Response:** the v1 payload is much slimmer than the legacy one — only `name`, `domain`, `industry` carry over unchanged, plus two renames and one new field. Everything else legacy returned (`website`, `description`, `headcount_range`, `founded_year`, `company_type`, `hq_city`, `hq_state`, `hq_country`, and internal fields like `hashtags`, `groups`, `tagline`) is dropped.

    | Old field | New field | Notes |
    | - | - | - |
    | `name`, `domain`, `industry` | same names | Unchanged. |
    | `linkedin_link` | `linkedin_url` | Renamed. |
    | `headcount_exact` | `headcount` | Renamed. |
    | `linkedin_id` | — | Removed. |
    | `website`, `description`, `headcount_range`, `founded_year`, `company_type`, `hq_city`, `hq_state`, `hq_country` | — | Removed — not part of the v1 response. |
    | — | `id` | New: Generect internal company identifier — not the same value as the old `linkedin_id`. |

    **Example — before / after:**

    <CodeGroup>
      ```json Before (legacy) theme={null}
      {
        "amount": -1,
        "company": {
          "name": "Microsoft",
          "domain": "microsoft.com",
          "website": "https://microsoft.com",
          "industry": "Software Development",
          "headcount_exact": 150,
          "headcount_range": "51-200",
          "founded_year": 1975,
          "company_type": "Public Company",
          "linkedin_link": "https://www.linkedin.com/company/microsoft/",
          "hq_city": "Redmond",
          "hq_state": "WA",
          "hq_country": "US"
        }
      }
      ```

      ```json After (v1) theme={null}
      {
        "data": {
          "id": 1035,
          "name": "Microsoft",
          "domain": "microsoft.com",
          "linkedin_url": "https://www.linkedin.com/company/microsoft/",
          "industry": "Software Development",
          "headcount": 150
        },
        "meta": { "amount_charged": 0.04 }
      }
      ```
    </CodeGroup>

    All fields stay top-level inside `data` — unlike the lead endpoint below, nothing here moves into a sub-object.

    **Note:** there's also a [`/enrich/database/company/`](/api-reference/endpoint/enrich/enrich-database-company) variant (same request shape) that returns cached data instead of a fresh live lookup — cheaper/faster if slightly-stale data is acceptable. `realtime` is the direct successor to the old behavior.

    Full reference: [Enrich company (realtime)](/api-reference/endpoint/enrich/enrich-realtime-company)
  </Accordion>

  <Accordion title="10. Enrich lead by LinkedIn URL">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/leads/by_link/` | `/api/v1/enrich/{database\|realtime}/lead/` |

    **Request:**

    ```json theme={null}
    { "linkedin_url": "https://www.linkedin.com/in/jordan-ellis" }
    ```

    (unchanged input — LinkedIn profile URL). The new endpoint also accepts `id` (Generect lead ID) or `email` (reverse lookup) as alternative identifiers.

    **Response:** the v1 payload is slimmer than the legacy one — `headline` and `location` are dropped entirely, and only `id`/`name`/`domain` carry over into the new `company` object (`company_industry` is dropped, not nested).

    | Old field | New field | Notes |
    | - | - | - |
    | `first_name`, `last_name`, `linkedin_url` | same names | Unchanged. |
    | `job_title` | `data.title` | Renamed. |
    | `company_name` | `data.company.name` | Now nested inside `company` object. |
    | `company_website` | `data.company.domain` | Now nested inside `company` object. |
    | `headline`, `location`, `company_industry` | — | Removed — not part of the v1 response. |
    | — | `data.company.id` | New: Generect internal company ID. |
    | — | `data.work_history`, `data.education`, `data.skills` | New: arrays, empty unless populated. |

    **Example — before / after:**

    <CodeGroup>
      ```json Before (legacy) theme={null}
      {
        "amount": -2,
        "lead": {
          "first_name": "Jordan",
          "last_name": "Ellis",
          "job_title": "CEO",
          "headline": "CEO at Microsoft",
          "linkedin_url": "https://www.linkedin.com/in/jordan-ellis",
          "location": "Seattle, WA",
          "company_name": "Microsoft",
          "company_website": "microsoft.com",
          "company_industry": "Software Development"
        }
      }
      ```

      ```json After (v1) theme={null}
      {
        "data": {
          "id": "ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9",
          "first_name": "Jordan",
          "last_name": "Ellis",
          "title": "CEO",
          "linkedin_url": "https://www.linkedin.com/in/jordan-ellis",
          "company": {
            "id": 1035,
            "name": "Microsoft",
            "domain": "microsoft.com"
          },
          "work_history": [],
          "education": [],
          "skills": []
        },
        "meta": { "amount_charged": 0.04 }
      }
      ```
    </CodeGroup>

    **Note:** there's also a [`/enrich/database/lead/`](/api-reference/endpoint/enrich/enrich-database-lead) variant (cached data, cheaper) — `realtime` is the direct successor to the old behavior.

    Full reference: [Enrich lead (realtime)](/api-reference/endpoint/enrich/enrich-realtime-lead)
  </Accordion>
</AccordionGroup>

### Email

<AccordionGroup>
  <Accordion title="11. Find email by name and domain">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/email_finder/` | `/api/v1/email/find/` |

    **Request** — same 3 fields, unchanged:

    ```json theme={null}
    {
      "first_name": "Jack",
      "last_name": "Kennedy",
      "domain": "platformscience.com"
    }
    ```

    The new endpoint also supports finding an email by `lead_id` or `linkedin_url` instead of name + domain — not required for a straight migration, but available if useful.

    **Response field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `valid_email` | `data.valid_email` | `null` if not found. |
    | `result` | `data.result` | `"valid"` / `"invalid"` / `"unknown"`. |
    | `catch_all` | `data.catch_all` | Now a real boolean, not the string `"true"`/`"false"`. |
    | `email_format` | `data.email_format` | Unchanged. |
    | `exist` | `data.result` | Merged into `result` — a separate boolean is no longer returned. |
    | `mx_domain` | `data.mx_domain` | Unchanged. |
    | `first_name`, `last_name`, `domain` | — | No longer echoed back — you already have them from the request. |
    | `error`, `logs` | — | Removed. |
    | — | `meta.amount_charged` | New: cost of this call in USD. |

    **Example — before / after:**

    <CodeGroup>
      ```json Before (legacy) theme={null}
      [{
        "first_name": "Jack",
        "last_name": "Kennedy",
        "domain": "platformscience.com",
        "result": "valid",
        "catch_all": "true",
        "error": null,
        "valid_email": "jkennedy@platformscience.com",
        "source": "name2email",
        "email_format": "flast",
        "mx_domain": "pphosted.com",
        "logs": "get mx_record: pphosted.com",
        "exist": "yes"
      }]
      ```

      ```json After (v1) theme={null}
      {
        "data": {
          "valid_email": "jkennedy@platformscience.com",
          "result": "valid",
          "catch_all": false,
          "source": "name2email",
          "email_format": "flast",
          "mx_domain": "pphosted.com"
        },
        "meta": { "amount_charged": 0.02 }
      }
      ```
    </CodeGroup>

    **Note:** legacy accepted a batch array in one call; v1 is single-item — use the [bulk endpoint](/api-reference/endpoint/emails/email-finder-bulk) for batches instead of looping.

    Full reference: [Email Finder](/api-reference/endpoint/emails/email-finder)
  </Accordion>

  <Accordion title="12. Validate emails">
    | | Old | New |
    | - | - | - |
    | Method | `POST` | `POST` |
    | Path | `/api/linkedin/email_validator/` | `/api/v1/email/validate/` |

    **Request** — legacy took a bare array of email strings; v1 requires an object wrapper:

    <CodeGroup>
      ```json Before (legacy) theme={null}
      ["jkennedy@platformscience.com"]
      ```

      ```json After (v1) theme={null}
      { "emails": ["jkennedy@platformscience.com"] }
      ```
    </CodeGroup>

    **Response field mapping:**

    | Old field | New field | Notes |
    | - | - | - |
    | `email` | `data[].email` | Unchanged. |
    | `result` | `data[].result` | Unchanged. |
    | `catch_all` | `data[].catch_all` | Unchanged. |
    | `exist` | `data[].exist` | Unchanged. |
    | `error` | `data[].error` | Unchanged, `null` on success. |
    | `source`, `mx_domain`, `logs` | — | Removed. |
    | — | `meta.amount_charged` | New: cost of this call, billed per email validated. |

    **Example — before / after:**

    <CodeGroup>
      ```json Before (legacy) theme={null}
      [{
        "result": "valid",
        "catch_all": "true",
        "error": null,
        "source": "name2email",
        "mx_domain": "pphosted.com",
        "exist": "yes",
        "email": "jkennedy@platformscience.com"
      }]
      ```

      ```json After (v1) theme={null}
      {
        "data": [
          { 
            "email": "jkennedy@platformscience.com", 
            "result": "valid", 
            "exist": "yes", 
            "catch_all": false, 
            "error": null
          }
        ],
        "meta": { "amount_charged": 0.01 }
      }
      ```
    </CodeGroup>

    Full reference: [Email Validation](/api-reference/endpoint/emails/email-validation)
  </Accordion>
</AccordionGroup>

### Quick reference

| # | Old endpoint | New endpoint |
| - | - | - |
| 1 | `POST /api/auth/token/login/` | *(retired — use a static API key)* |
| 2 | `GET /api/auth/users/me/` | [`GET /api/v1/accounts/me/`](/api-reference/endpoint/accounts/get-account-me) |
| 3 | `GET /api/auth/transactions/` | [`GET /api/v1/accounts/transactions/`](/api-reference/endpoint/accounts/get-account-transactions) |
| 4 | `GET /api/auth/transactions/spent_credits/` | [`GET /api/v1/accounts/usage/`](/api-reference/endpoint/accounts/get-account-usage) |
| 5 | `POST /api/linkedin/leads/by_icp/` | [`POST /api/v1/search/{database\|realtime}/leads/`](/api-reference/endpoint/search/database-leads) |
| 6 | `POST /api/linkedin/leads/by_icp/get_count/` | [`POST /api/v1/search/{database\|realtime}/leads/count/`](/api-reference/endpoint/search/count-database-leads) |
| 7 | `POST /api/linkedin/companies/by_icp/` | [`POST /api/v1/search/{database\|realtime}/companies/`](/api-reference/endpoint/search/database-companies) |
| 8 | `POST /api/linkedin/companies/by_icp/get_count/` | [`POST /api/v1/search/{database\|realtime}/companies/count/`](/api-reference/endpoint/search/count-database-companies) |
| 9 | `POST /api/linkedin/companies/by_link/` | [`POST /api/v1/enrich/{database\|realtime}/company/`](/api-reference/endpoint/enrich/enrich-realtime-company) |
| 10 | `POST /api/linkedin/leads/by_link/` | [`POST /api/v1/enrich/{database\|realtime}/lead/`](/api-reference/endpoint/enrich/enrich-realtime-lead) |
| 11 | `POST /api/linkedin/email_finder/` | [`POST /api/v1/email/find/`](/api-reference/endpoint/emails/email-finder) |
| 12 | `POST /api/linkedin/email_validator/` | [`POST /api/v1/email/validate/`](/api-reference/endpoint/emails/email-validation) |

### Error handling

Every v1 endpoint uses the same [error envelope](/api-reference/errors):

```json theme={null}
{
  "status": "error",
  "status_code": "...",
  "detail": "..."
}
```

| Code | Meaning |
| - | - |
| `400` | Validation error or insufficient account balance. |
| `401` | Missing or invalid API token. |
| `403` | Account/plan doesn't have access to this endpoint. |
| `429` | Rate limit exceeded. |

### Migration checklist

<Steps>
  <Step title="Get a static API key">
    If you're still calling `/api/auth/token/login/`, stop — grab a key from [account settings](https://app.generect.com/settings/billing) and send it as `Authorization: Token <key>` on every request.
  </Step>

  <Step title="Swap paths">
    Replace each legacy path with its `/api/v1/...` equivalent from the [Quick reference](#quick-reference) table above.
  </Step>

  <Step title="Update response parsing">
    Read results from `data` and cost from `meta.amount_charged` instead of a flat payload or a negative root-level `amount`.
  </Step>

  <Step title="Update nested field reads">
    Change flattened reads like `lead.company_name` to `data.company.name` — see each endpoint's field mapping table above.
  </Step>

  <Step title="Prioritize the deprecated search endpoints">
    Migrate the four `by_icp` endpoints first — they're already flagged `deprecated` in the API spec.
  </Step>

  <Step title="Test in database mode, then go live">
    Validate with a free `database` count, then read [Limits](/api-reference/limits) and [Errors](/api-reference/errors) before production.
  </Step>
</Steps>

## Renamed search controls

Several search controls were renamed to say what they do. **The old spellings keep
working** — the API accepts both and treats them identically, so nothing breaks if
you do nothing. New integrations should use the names on the right, and existing
ones can switch whenever convenient.

| Old | New | Why |
| - | - | - |
| `get_max_leads`, `get_max_companies` | `include_total_count` | It never returned "more leads" — it adds `results_count` to the response. One name now covers both searches. |
| `search_emails` | `include_emails` | Was one character away from `emails`, which meant the opposite (addresses you send *in*). |
| `emails` | `find_by_emails` | Reads as "return emails"; it actually finds the people behind addresses you supply. |
| `full_data` | `include_full_profile` | Says which data, and matches the `include_*` convention. |
| `max_investigated_leads` | `max_profiles_scanned` | "Investigated" was internal jargon. |
| `skip_1_symbol_name` | `skip_truncated_names` | Describes the case (LinkedIn-abbreviated names) rather than a character count. |
| `website_blacklist` | `apply_domain_blocklist` | A boolean needs a verb — the old noun read as if it took a list. |

If you send both spellings of the same control in one request, the old one wins and
the new one is ignored, so migrate a control in a single step rather than leaving
both in place.

## A typical migration path

1. Swap your auth to the `Authorization: Token` header.
2. Replace your search call with `database` mode first — it's the cheapest, fastest equivalent — and only move specific calls to `realtime` when you need live freshness or [advanced filters](/api-reference/database-vs-realtime).
3. Replace enrichment and email/phone lookups with the endpoints above, and remove any "charged on no-match" handling — Generect doesn't bill empty results.
4. Read [Limits](/api-reference/limits) and [Errors](/api-reference/errors) before going to production.

Need a mapping for a provider not listed here? Contact [support@generect.com](mailto:support@generect.com).


# Quickstart
Source: https://docs.generect.com/api-reference/quickstart

Your first leads and a verified email in five minutes

Grab your API token from [Settings → API](https://app.generect.com/settings/api), then run the three calls below: size the audience for free, pull real leads from the cached database, and reveal a verified email.

<Tip>
  Not ready to spend anything? Create a **test key** instead and run the same three calls against the same URLs. Same shapes, same speed, same reported prices, nothing charged. See [Test mode](/api-reference/test-mode).
</Tip>

## 1. Size your audience — free

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.generect.com/api/v1/search/database/leads/count/ \
    -H "Authorization: Token YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"job_titles": ["marketing manager"], "locations": ["Germany"]}'
  ```

  ```python Python theme={null}
  import requests

  BASE = "https://api.generect.com/api/v1"
  HEADERS = {"Authorization": "Token YOUR_API_TOKEN"}

  count = requests.post(
      f"{BASE}/search/database/leads/count/",
      headers=HEADERS,
      json={"job_titles": ["marketing manager"], "locations": ["Germany"]},
  ).json()
  print(count)  # database counts are free
  ```

  ```javascript Node.js theme={null}
  const BASE = "https://api.generect.com/api/v1";
  const HEADERS = {
    Authorization: "Token YOUR_API_TOKEN",
    "Content-Type": "application/json",
  };

  const count = await fetch(`${BASE}/search/database/leads/count/`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ job_titles: ["marketing manager"], locations: ["Germany"] }),
  }).then((r) => r.json());
  console.log(count); // database counts are free
  ```
</CodeGroup>

## 2. Pull the leads

Same filters against [`/search/database/leads/`](/api-reference/endpoint/search/database-leads) — sub-second, billed per returned result (\$0.02 each, see [Pricing](/billing/pricing)). Every response tells you what it cost in `meta.amount_charged`.

<CodeGroup>
  ```python Python theme={null}
  resp = requests.post(
      f"{BASE}/search/database/leads/",
      headers=HEADERS,
      json={"job_titles": ["marketing manager"], "locations": ["Germany"], "limit_by": 10},
  ).json()

  leads = resp["data"]["leads"]
  print(len(leads), "leads for", resp["meta"]["amount_charged"], "USD")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(`${BASE}/search/database/leads/`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ job_titles: ["marketing manager"], locations: ["Germany"], limit_by: 10 }),
  }).then((r) => r.json());

  const leads = resp.data.leads;
  console.log(leads.length, "leads for", resp.meta.amount_charged, "USD");
  ```
</CodeGroup>

## 3. Reveal a verified email

Pass a lead from step 2 into [`/email/find/`](/api-reference/endpoint/emails/email-finder). You are billed **only when a valid email is found** — a miss is free.

<CodeGroup>
  ```python Python theme={null}
  lead = leads[0]
  email = requests.post(
      f"{BASE}/email/find/",
      headers=HEADERS,
      json={"lead_id": lead["id"]},
  ).json()
  print(email)
  ```

  ```javascript Node.js theme={null}
  const email = await fetch(`${BASE}/email/find/`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ lead_id: leads[0].id }),
  }).then((r) => r.json());
  console.log(email);
  ```
</CodeGroup>

<Tip>Need fresher-than-cache data or advanced filters? Swap `database` → `realtime` in any path — same request shape. See [Database vs Real-time](/api-reference/database-vs-realtime).</Tip>

## Use it from Postman or Insomnia

Import the whole API in one step — every endpoint, schema, and example:

1. **Postman:** *Import* → *Link* → paste `https://docs.generect.com/api-reference/openapi.yaml`
2. Set a collection-level `Authorization` header: `Token YOUR_API_TOKEN`

The same [OpenAPI 3.0 spec](https://docs.generect.com/api-reference/openapi.yaml) works with Insomnia, code generators, and AI agents. Building with LLMs? There's also a [remote MCP server](/integrations/mcp/remote-mcp).

## Before production

* [Errors](/api-reference/errors) — one envelope, retry semantics
* [Limits](/api-reference/limits) — parallel caps, batch sizes, timeouts
* [Pricing](/billing/pricing) — what each call costs, No Data No Charge
* [Migration Guide](/api-reference/migration-guide) — coming from Apollo, Hunter, ZoomInfo, or the legacy API


# Reliability
Source: https://docs.generect.com/api-reference/reliability

Uptime, status page, and how the API behaves under failure

## Live status & uptime

Current availability, **90-day uptime history**, and incident post-mortems are public at [status.generect.com](https://status.generect.com) — subscribe there for incident notifications.

Contractual SLAs are available on Enterprise agreements — [contact sales](https://calendly.com/andrii-kolpakov/_sales_api_insight).

## What to expect from each mode

* **Database (cached)** operations answer from Generect's own infrastructure — sub-second, independent of live sources.
* **Real-time** operations depend on live upstream sources: latency is seconds to a minute (see [recommended timeouts](/api-reference/limits)), and under exceptional upstream load they can return `429` — back off and retry.

## Failure semantics

* Errors use one JSON envelope with predictable status codes — see [Errors](/api-reference/errors).
* `429` and `5xx` are transient: retry with exponential backoff. Other `4xx` mean the request must change.
* Credits are **reserved when a request or bulk job is accepted** — a failed request is refunded automatically, and an accepted bulk job always runs to completion even if your balance later hits \$0 (see [Pricing](/billing/pricing)).
* Bulk jobs report `error` status instead of hanging; results are retained for 24 hours.


# Test mode
Source: https://docs.generect.com/api-reference/test-mode

Build and rehearse an integration without spending anything

Test mode gives you a key that answers every endpoint with fictional data, at the speed the real endpoint runs, showing the price the real call would have cost — and charges nothing.

There is **no separate host and no separate base URL**. `https://api.generect.com` serves both modes and the key decides which one you get. Moving an integration from test to live is a change of credential, nothing else.

## Get a test key

Create one over the API with the key you already have:

```bash theme={null}
curl -X POST https://api.generect.com/api/auth/api_tokens/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "sandbox", "mode": "test"}'
```

The response carries the new key. Test keys start with `test_`, so you can tell one from a live key at a glance, in a log line or in a support ticket.

<Note>
  Picking **Test** when creating a key in the app is rolling out. Until it reaches your account, use the call above.
</Note>

## Your first test call

```bash theme={null}
curl -X POST https://api.generect.com/api/v1/search/database/leads/ \
  -H "Authorization: Token test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_titles": ["marketing manager"], "locations": ["Germany"], "limit_by": 3}'
```

Identical to the live call in every respect but the key. The response carries a header:

```
X-Generect-Mode: test
```

Check that header in your integration tests. It is the one signal that is present on every endpoint, including the older `/api/linkedin/*` ones that have no `meta` envelope.

## What is real, and what is not

<CardGroup>
  <Card title="Real: validation" icon="circle-check">
    An unknown filter is still a `400`, with the same message. A sandbox that accepted anything would teach you that a broken payload is fine.
  </Card>

  <Card title="Real: response shapes" icon="circle-check">
    Fixtures are generated through the same serializers that build live responses, so every field a live row has, a test row has.
  </Card>

  <Card title="Real: timings" icon="circle-check">
    Each endpoint waits about as long as it really takes, drawn from production percentiles. Write your timeouts against these.
  </Card>

  <Card title="Real: prices" icon="circle-check">
    `meta.amount_charged` is computed by the live pricing code against your own tier. Nothing is debited.
  </Card>

  <Card title="Not real: the data" icon="circle-xmark">
    Fictional people at fictional companies. Nothing is fetched from LinkedIn or any provider.
  </Card>

  <Card title="Not real: the ledger" icon="circle-xmark">
    No transaction is written and your balance never moves. Test calls do not appear in billing history.
  </Card>
</CardGroup>

### Recognising a fixture

Test data is meant to be unmistakable:

| Field | What you get | Why |
| - | - | - |
| Company domains | `*.example.com` | Reserved by RFC 2606 — the domain can never be registered |
| Phone numbers | `+1 555 01xx` | The block reserved for fictional use |
| Names | Invented surnames — Testwell, Mockridge, Stubbs | No real person carries them |
| `source` | `test_mode` | Machine-readable on every row that has the field |

<Warning>
  One exception worth knowing. The email finder builds its address on **the domain you asked for**, because that is what the live endpoint does and your integration needs to check it. Ask for `ada.testwell` at `microsoft.com` and you get `ada.testwell@microsoft.com` — a synthetic address that looks real. It is not deliverable, and the row is marked `"source": "test_mode"`. Never feed test-mode output into a sending pipeline.
</Warning>

## Magic inputs: reproduce a failure on demand

The paths worth rehearsing are the ones you cannot ask production for. You cannot request a `402` without actually running out of money, so test mode gives you reserved values that force an outcome.

Put one in any identity field — an email, a LinkedIn URL, a company name:

| Magic value | What happens |
| - | - |
| `not-found@example.com`, `.../in/sandbox-not-found` | The endpoint's genuine "no data" outcome: an empty result for a search, a `400 Person does not exist` for an enrich. Nothing is charged. |
| `insufficient-funds@example.com` | `402 Payment Required`, the same body a real empty balance produces |
| `rate-limited@example.com` | `429 Too Many Requests` with `Retry-After: 1` |
| `upstream-error@example.com` | `502` — the data source is unavailable |
| `slow@example.com` | The endpoint's 90th-percentile response time, for testing timeouts |

The fragment has to be a whole segment, so `slowik@example.com` is an ordinary address and does not trigger anything.

```bash theme={null}
curl -X POST https://api.generect.com/api/v1/enrich/database/lead/ \
  -H "Authorization: Token test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "insufficient-funds@example.com"}'
```

### The header form

Searches have no single subject to hide a magic value in, so the same behaviours are available as a request header:

```bash theme={null}
curl -X POST https://api.generect.com/api/v1/search/database/leads/ \
  -H "Authorization: Token test_YOUR_TEST_KEY" \
  -H "X-Generect-Test-Behaviour: rate_limited" \
  -H "Content-Type: application/json" \
  -d '{"job_titles": ["ceo"]}'
```

Accepted values: `not_found`, `insufficient_funds`, `rate_limited`, `upstream_error`, `slow`, and `latency=<seconds>` to force a specific delay.

The header is ignored by live keys.

## Determinism

The same request body returns the same fictional people every time. You can assert on a name or a count in your own test suite and it will keep passing, and a retry after a timeout returns what the first attempt would have.

Change the query and you get different people.

## Page size

Test mode honours the `limit_by` you send, up to a ceiling on how many rows it will fabricate for one response. Every fixture row is generated through the same serializers that build live responses, so a page has a real cost.

Ask for more than the ceiling and you get the ceiling, not an error, and `results_count` still reports the full population so your pagination logic has something to page through. **Assert `<=` on the page size rather than `==`** and your tests keep passing when the ceiling moves.

Nested criteria are read where the live endpoint reads them. For company-leads, the page comes from `lead_search_criteria.limit_by`, not from a top-level `limit_by`.

## Bulk jobs

Bulk endpoints behave like bulk endpoints: the submit returns `pending` with a `job_id`, the first poll returns `processing`, and the second returns `completed` with the rows. That is deliberate — a job that is already finished on the first poll would let you ship a client that never handles the waiting state.

```bash theme={null}
# submit
curl -X POST https://api.generect.com/api/v1/enrich/database/leads/bulk/ \
  -H "Authorization: Token test_YOUR_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"leads": [{"linkedin_url": "https://www.linkedin.com/in/sandbox-ada"}]}'

# poll — first call: processing, second: completed
curl https://api.generect.com/api/v1/enrich/leads/bulk/JOB_ID/ \
  -H "Authorization: Token test_YOUR_TEST_KEY"
```

## Coverage

Supported: search (leads, companies, company-leads, and their counts), enrich (leads and companies, database and realtime, single and bulk), email finder and validation, phone finder, preview, and the legacy `/api/linkedin/*` endpoints.

`/api/v1/accounts/*` works normally with a test key and returns **your real account** — that is what you want when you are checking a balance or a tier.

Not yet supported: the datahub gateway (`/api/v1/data/…`) and webhook management. A test key on an endpoint without fixtures returns:

```json theme={null}
{
  "status": "error",
  "status_code": 501,
  "detail": "This endpoint does not support test mode yet. Use a live API key."
}
```

That refusal is deliberate. An endpoint we have not covered will not quietly answer a test key with real data.

## Going live

Swap the key. Nothing else changes — same URL, same payloads, same response shapes.

<Steps>
  <Step title="Check the header is gone">
    Assert `X-Generect-Mode` is absent in production. If it says `test`, you shipped the wrong key.
  </Step>

  <Step title="Fund the account">
    See [Pay as you go](/billing/pay-as-you-go). Test mode reports prices but never debits, so a live key is the first thing that will meet an empty balance.
  </Step>

  <Step title="Keep the test key">
    It costs nothing to keep and it is the cheapest way to rehearse the next change.
  </Step>
</Steps>


# Billing FAQ
Source: https://docs.generect.com/billing/faq

Frequently asked questions about billing and pricing

<AccordionGroup>
  <Accordion title="What happens if my balance reaches 0?">
    Paid operations – API, Email Finder, Email Validation, and Exports – will temporarily pause.\
    Once you top up your balance, all services resume automatically.
  </Accordion>

  <Accordion title="Can I switch to an invoice-based plan or get a custom pricing model?">
    Yes. Use the **Contact Sales** button in the Billing section – our team will help you choose a payment model that fits your needs.
  </Accordion>

  <Accordion title="Are there any usage limits?">
    There are no hard limits – you can run as many searches and requests as you need.\
    The only limitation is your available balance.
  </Accordion>

  <Accordion title="Why might a top-up take longer to appear?">
    Sometimes Stripe may take a few minutes to process a transaction – this is normal for payment systems.\
    As soon as the payment is confirmed, your Generect balance updates automatically.
  </Accordion>

  <Accordion title="Can I request a refund?">
    Refunds are possible in exceptional cases (duplicate charges, technical issues, etc.).\
    Contact our support team – we'll always help you resolve the situation.
  </Accordion>
</AccordionGroup>


# Managing Your Billing
Source: https://docs.generect.com/billing/managing-billing

Payment methods, top-ups, and billing settings

The **Billing & Usage** page is your central hub for everything related to payments.\
Here you can:

* add or update your payment card
* make a one-time top-up
* enable automatic top-ups
* view your pricing tier and discounts
* contact the Sales team for custom pricing or invoice-based billing

Everything is transparent – you always know how your costs are calculated and how to control them.

## Payment Method Management

### Managing your payment card

Your payment card is used for both one-time and automatic top-ups. All transactions are securely processed through Stripe.

### Adding a card

When you first open **Profile → Billing → Payment method**, you'll see the message *"No payment method"*.

To add a card:

1. Click **Add**
2. A secure Stripe window will open
3. Enter your card details
4. After submitting, Stripe returns you to Generect
5. Your card instantly appears as **Active** (showing the last 4 digits)

### Updating a card

If your card has changed:

1. Click **Edit**
2. You will be redirected to Stripe
3. Update the payment details
4. Return to Generect — the new card will appear immediately

### Error handling

If something goes wrong, the system notifies you:

* Stripe rejects the card → an error message appears, no changes are saved
* You close Stripe without updating → nothing changes in Generect

Stripe ensures full security and correct operation of all payment processes.

## One-Time Top-Up

### How to top up your balance

A one-time top-up is ideal if you prefer manual control of your spending or are not yet using Auto Top-Up.

To add credits:

1. Open **Profile → Billing**
2. Click **Buy credits**
3. Enter the amount
4. If a card is already added – it will be used automatically
5. If not – the system will ask you to add one through Stripe
6. Confirm the payment
7. After returning to Generect, your balance updates instantly and you'll see a success message

It works just like a typical online checkout – fast and simple.

### Validation

To prevent mistakes:

* the **Continue** button stays disabled until the amount is valid
* incorrect values are highlighted
* you cannot complete the payment without an active card

## Auto Top-Up (Automatic Balance Refill)

### What Auto Top-Up is

Auto Top-Up ensures your access to Generect never stops because of a zero balance.\
You set the rules – the system does the rest.

**Example:**\
**when balance \< \$50 → top up to \$100**

This is especially useful for teams actively using API or search workflows.

### How to enable Auto Top-Up

1. In **Billing**, find the block **Auto-recharge off**
2. Click **Enable**
3. In the popup, set:
   * the balance threshold ("when balance goes below")
   * the amount to refill to
4. Save your settings

The changes apply instantly.

### How Auto Top-Up works

Once enabled:

* when your balance drops below the threshold
* the system automatically charges your card
* your balance is refilled
* the status changes to **Auto-recharge on**

### Editing Auto Top-Up

To modify thresholds or amounts:

1. Click **Edit**
2. Update the values
3. Save — the banner updates immediately

### Turning Auto Top-Up off

Open the popup and switch the toggle off → the system returns to **Auto-recharge off**.

<Tip>
  We recommend enabling Auto Top-Up to avoid any service interruptions — especially if your processes rely on API or continuous access to fresh data.
</Tip>

## Contact Sales — Custom Pricing & Invoice Plans

The **Contact Sales** button in Billing provides a direct way to request personalized pricing or invoice-based billing.

When you click it:

* a Calendly page opens in a new tab
* you can choose a convenient time to speak with our team

Link:\
[https://calendly.com/andrii-kolpakov/\_sales\_api\_insight](https://calendly.com/andrii-kolpakov/_sales_api_insight)

During the call, you can:

* request a personalized discount
* switch to an invoice-based billing model
* negotiate custom pricing for high-volume workloads
* receive recommendations on cost optimization

This is ideal for growing teams or companies with advanced billing requirements.

## Spend & Save Tiers (Pricing Model)

The Spend & Save model is simple: the more you use the platform, the cheaper each action becomes.\
This lets you scale without unnecessary costs while always knowing your exact pricing level.

### What you see on the Billing page

Your Billing page instantly shows:

* your current **tier**
* how much you've spent in the current cycle
* the **discount percentage** you are receiving right now
* current pricing for:\
  Email Finder, Email Validation, Export, UI Search, API
* how much is left until you reach the next, more favorable tier

This makes it easy to understand:\
**How much have I saved already? When does the next discount unlock?**

### Switching between tiers

Using the buttons:

* **To the previous tiers**
* **To the next tiers**

You can explore:

* upcoming tiers with higher discounts
* previous tiers
* detailed pricing for each level

Your current tier is always highlighted.

### Automatic tier upgrades

When you reach the threshold of the next tier:

* your tier updates automatically
* new pricing applies instantly
* no approvals or actions needed — the system adjusts by itself


# How Pay-as-you-go Works
Source: https://docs.generect.com/billing/pay-as-you-go

Understanding the transparent pricing model

Generect uses a transparent Pay-as-you-go model — you only pay for what you actually use.

No subscriptions, no hidden fees — just real consumption.

## Core principles of the model

1. **You pay only for results.**\
   For example, Email Finder charges only for a *valid* found email, and enrichment charges only when data is found.
2. **No monthly plans.**\
   You're not locked into subscriptions — use the platform at your own pace.
3. **Pricing decreases as you grow.**\
   The higher your lifetime spend, the better your pricing tier becomes, and the cheaper each future action costs.
4. **A positive balance is required.**\
   Email Finder, API usage, exporting data, and email validation all require a positive balance.\
   If your balance reaches zero, you won't be able to use these features until you top up.

## Where to see your prices

Your exact price for each action depends on your pricing tier and is shown in your billing settings.

<Tip>The more you use Generect, the better your pricing tier becomes. [Check your current tier and pricing →](https://app.generect.com/settings/billing)</Tip>


# Pricing
Source: https://docs.generect.com/billing/pricing

What each API operation costs, and how billing is calculated

Your account balance is held in **US dollars**. Every billable result deducts a small dollar amount from that balance. Throughout the docs you may see the word *credit* — read it as **one billable result**, priced in USD as shown below.

## Standard prices

These are the per-result prices every account starts on (see [Spend & Save tiers](/billing/managing-billing) for the volume discounts). Your effective price never goes **up**; your current rate is always shown in your [billing settings](https://app.generect.com/settings/billing).

| Operation | Endpoints | Price (USD) | Billed |
| - | - | - | - |
| Real-time search & enrich | `POST /search/realtime/*`, `POST /enrich/realtime/*` | **\$0.04** | per returned result |
| Database (cached) search & enrich | `POST /search/database/*`, `POST /enrich/database/*` | **\$0.02** | per returned result |
| Email Finder | `POST /email/find/` (+ `/bulk/`) | **\$0.02** | per **valid** email found |
| Email Validation | `POST /email/validate/` | **\$0.005** | per email checked |
| Preview | `POST /preview/leads/` | **\$0.002** | per returned (masked) result — free for the rest of the month once your spend that month reaches \$2,000 |
| Phone Finder | `POST /phone/find/` (+ `/bulk/`) | **\$0.40** | per **found** phone |

<Info>Prices above are the Tier 0 (standard) rate, and they are what **every API account pays until its lifetime spend reaches \$20,000**. API discounts begin at that threshold and then deepen with each tier; the platform (UI) operations start discounting much earlier, at \$500. Your current rate is always the one in your [billing settings](https://app.generect.com/settings/billing) — and in `meta.amount_charged` on every response. See [Spend & Save tiers](/billing/managing-billing).</Info>

<Note>**Preview** is the one API price that never moves with your tier — it stays at \$0.002 per returned result on every tier. What does move is the monthly free tier: once your account's total spend within the current calendar month reaches \$2,000, `POST /preview/leads/` is free for the rest of that month, and the counter restarts on the 1st (UTC). The `preview_tier` flag on [`GET /accounts/me/`](/api-reference/endpoint/accounts/get-account-me) reports the current state. Preview inside the Generect web app is always free — \$0.002 is the API price.</Note>

## How a charge is calculated

```
amount charged (USD) = billable results × operation price × your tier multiplier
```

Every API response reports exactly what it cost in `meta.amount_charged` (USD), so you never have to guess after the fact.

```json theme={null}
{
  "data": [ ... ],
  "meta": { "amount_charged": 0.0400 }
}
```

## What's free

* **Database (cached) count** endpoints (`POST /search/database/*/count/`) — a cached count, no charge.
* **Preview count** (`POST /preview/leads/count/`) — sizing a Preview audience is free, always.
* **Preview in the Generect web app** — the \$0.002 Preview price applies to API calls only.
* **Account, status, and webhook** endpoints.
* **Not-found results** on enrich, phone, and email find (see below).

<Warning>**Real-time count** endpoints (`POST /search/realtime/*/count/`) are **not** free — each costs \$0.04, the real-time rate, because they hit live sources. Use the free database count to size an audience before paying.</Warning>

## No Data, No Charge — exactly where it applies

You are not billed for results we don't return:

| Operation | If nothing is found |
| - | - |
| Enrich lead / company | **Not charged** — the reserved amount is refunded automatically |
| Search (database or real-time) | Billed **per returned row** — zero rows costs \$0 |
| Email Finder | Charged **only for valid emails found** |
| Phone Finder | Charged **only for phones found** |
| Email Validation | Charged **per email checked** — a verdict (valid, risky, catch-all, invalid) is the result you paid for |
| Preview | Billed **per returned row** — zero rows costs \$0 |
| Real-time count | Flat \$0.04 per request (even if the count is 0) |

<Note>Email Validation is the one case where every submitted address is billed: validation *is* the deliverable, so each checked email costs \$0.005 regardless of its verdict.</Note>

## Worked example

You enrich 100 leads in real time; 92 are found, 8 are not.

* 92 × \$0.04 = **\$3.68** charged
* 8 not-found → **\$0.00** (refunded)
* `meta.amount_charged` returns `3.68`

## When your balance hits \$0

The exact sequence, so production behavior is predictable:

1. Credits are **reserved up front** when a request or bulk job is accepted — anything already accepted **runs to completion** and is never interrupted mid-flight.
2. A submitted bulk job keeps processing even if your balance reaches \$0 afterwards — its cost was reserved at submit time.
3. **New** billable requests are rejected with `402` and `"Insufficient funds in the account."` (standard [error envelope](/api-reference/errors)) until you top up.
4. Free endpoints (database counts, `POST /preview/leads/count/`, account, status polling, webhooks) keep working at \$0.

Enable [Auto Top-Up](/billing/managing-billing) to make this state unreachable in production.

## Testing without spending

There is no separate sandbox environment — the live API is safe to evaluate for free:

* **Database count** endpoints are free — size any audience at \$0.
* **Preview** returns real (masked) leads at \$0.002 per result — and is free for the rest of the calendar month once your spend that month reaches \$2,000.
* New accounts start with a **free starter credit**, and not-found results are never billed — a failed experiment costs nothing.
* Every response tells you what it actually cost (`meta.amount_charged`), so a \$1 test budget goes a long way.

## Keeping a positive balance

API usage requires a positive balance. If it reaches \$0, requests stop until you top up. Enable [Auto Top-Up](/billing/managing-billing) so production traffic never halts. New accounts start with free credit to try the API — your current balance is shown in your [billing settings](https://app.generect.com/settings/billing).


# Usage History
Source: https://docs.generect.com/billing/usage-history

View your transaction history and track spending

The **Usage** page is your transparent financial activity log.\
Here you can see every transaction related to your balance in a clear, structured format.

## What you'll find in Usage

* **full transaction history** – balance top-ups, charges for Email Finder, API requests, exports, and other actions
* **date & exact time** of each operation
* **type of charge** (which tool or feature triggered the cost)
* **amount** for each transaction
* **time-period filters** – quickly view charges for:
  * past 1 day
  * past 7 days
  * past 30 days
  * a custom date range

The history updates automatically after every operation, so you always see real-time data with no delay.

This is your complete financial log – it helps you control spending, track price changes, and analyze your team's activity.

<Card title="Billing & Usage" icon="credit-card" href="/billing/managing-billing">
  Learn how to manage your billing settings
</Card>


# How the Generect API Works
Source: https://docs.generect.com/docs/api-overview

Why you need it and what it enables

The Generect API allows you to integrate the platform's capabilities directly into your products, internal systems, or automated workflows.\
In simple terms, it's a way to work with Generect data without manual actions in the UI, at scale and with full cost control.

The API is designed for companies that want to:

* automate lead and company search
* display data inside their own products
* enrich CRM systems with up-to-date information
* pay only for real value, not for "empty" results

## Key Principles of the Generect API

### Cheap preview → pay only for revealed data

You can show masked search results for \$0.002 each through the API — free inside the Generect app — and pay the full price only when you decide to reveal an email, phone number, or full profile.

### Database or Realtime — depending on your task

Use fast and cost-efficient data for large-scale workflows, or ultra-fresh data for precise outreach.

### No Data, No Charge

If data is not found, no credits are charged.

## Core API Capabilities and Business Scenarios

### Preview Search for Contacts and Companies

**What this gives you**
The Preview API lets you find relevant contacts and companies and display basic information without revealing sensitive data (email, phone, LinkedIn URL, company domain).

You can:

* find contacts and companies by role, industry, and location
* display name, job title, company, and industry
* browse masked results at \$0.002 per lead shown
* reveal detailed data only when it's truly needed

**Ideal for:**

* SaaS platforms
* internal CRM or admin panels
* AI SDR and automation tools
* preview → reveal business models

<Card title="Use Case: Preview Search for SaaS Platforms" icon="lightbulb" href="/use-cases/preview-search-saas-platform">
  Learn how SaaS platforms use preview search
</Card>

### ICP-Based Search and Segmentation

**What this gives you**\
The Generect API allows you to automatically build lists of companies and contacts based on your Ideal Customer Profile.

You can segment by:

* industry
* company size
* location
* roles and seniority

The API supports two modes:

**Database Mode — fast and cost-efficient**\
Best for large lists and recurring workflows.

**Realtime Mode — maximum data freshness**\
Best for targeted searches and time-sensitive signals.

<Card title="Use Case: ICP-Based Search for Sales Teams" icon="lightbulb" href="/use-cases/icp-search-sales-team">
  Learn how sales teams use Database and Realtime modes
</Card>

### Contact and Company Enrichment

**What this gives you**\
If you already have partial or outdated data, the API allows you to enrich and refresh contact and company profiles.

You can:

* keep your CRM up to date
* enrich profiles before outreach
* work with LinkedIn URLs, domains, or internal IDs

Available options:

* fast enrichment from cache (Database)
* ultra-fresh data retrieval (Realtime)

<Card title="Use Case: Contact Enrichment for Customer Success" icon="lightbulb" href="/use-cases/contact-enrichment-customer-success">
  Learn how Customer Success teams keep CRM data up-to-date
</Card>

### Email Finding and Validation

**What this gives you**\
The API allows you to:

* find corporate email addresses
* validate deliverability
* reduce bounce rate and sender reputation risks

You only pay if a valid email is found.

<Card title="Use Case: Email Finding for Marketing Campaigns" icon="lightbulb" href="/use-cases/email-finding-marketing">
  Learn how marketing teams generate and validate emails
</Card>

### Phone Number Discovery

**What this gives you**
For workflows where direct contact matters, the API allows you to find phone numbers for contacts.
You are charged only if a phone number is found.

<Card title="Use Case: Phone Number Discovery for Recruiting" icon="lightbulb" href="/use-cases/phone-discovery-recruiting">
  Learn how recruiting teams find direct contact numbers
</Card>

### Usage and Cost Control

**What this gives you**
The API provides transparent control over:

* account balance
* credit usage
* transaction history

This is useful for financial oversight and team scaling.

<Card title="Use Case: Usage and Cost Control for Managers" icon="lightbulb" href="/use-cases/usage-control-manager">
  Learn how managers track and optimize API spending
</Card>

### Webhooks for Async Workflows

**What this gives you**
The API can notify your application when async jobs complete, so your workflow can continue without polling.

You can:

* register webhook URLs
* subscribe to bulk job events
* test webhook delivery
* verify signed webhook requests

<Card title="Use Case: Automations and Integrations" icon="lightbulb" href="/use-cases/api/automations-and-integrations">
  Learn how teams connect async API workflows
</Card>

## What's Next

This section helps you understand the business capabilities and usage scenarios of the Generect API.\
For technical implementation details, your engineering team can proceed to the **API Reference**.

<Card title="API Reference" icon="square-code" href="/api-reference/authentication">
  Full parameter lists, request formats, and response examples
</Card>


# Cached Databases
Source: https://docs.generect.com/docs/cached-databases

How Generect's own database powers instant, cheaper searches

## What it is

The cached database is Generect's own continuously growing dataset of lead and company profiles, accumulated and refreshed by the live searches running across the platform. Searching it returns results instantly and at a lower cost than a live search, because no new data collection happens at request time.

## When to use it

* when you need a large list of contacts or companies quickly, without waiting
* when your query uses standard filters (titles, seniority, location, industry, headcount)
* when you want to reduce costs — database results are cheaper than Live Search
* lead records in the database are kept no older than 12 months — fine for most list-building

## How it works

* You choose the mode explicitly: in the API these are the `database` endpoints, while `realtime` endpoints run a live search ([full comparison](/api-reference/database-vs-realtime)).
* A database search only returns what is already in the dataset. If nothing matches, you get 0 results and pay nothing — it never silently switches to a live search.
* Need fresher data or deeper filters? Run the same request against the realtime endpoint — it collects up-to-the-moment results for a higher price.

<Tip>
  Cached databases are perfect for large-scale workflows where data freshness is less critical than speed and cost efficiency.
</Tip>


# Catch-All Email Validation
Source: https://docs.generect.com/docs/catch-all-validation

Advanced validation for catch-all email domains

## What Is a Catch-All Email and Why Validation Matters

**Definition:**\
A *catch-all* domain is configured to accept **any** email address, even if the mailbox does not actually exist.\
This means the server always replies "accepted", making standard SMTP validation unreliable.

**Example:**

```
info@company.com        → accepted    
sales@company.com       → accepted    
anyname@company.com     → accepted    
randomtext@company.com  → also accepted  
```

In catch-all domains, an SMTP check cannot determine whether a specific mailbox is real because the server confirms every possible address.

## Why this matters

* It's impossible to confirm real mailbox existence using standard validation
* High risk of bounce rate
* Potential negative impact on your sender reputation
* Harder to filter high-quality contacts for outreach
* Increases campaign risk, especially at scale

## Why additional validation is needed

Generect applies enhanced intelligence signals to estimate whether a catch-all email is *likely* to be deliverable.

The system provides a **confidence score**, helping you decide whether to include such emails in your outreach.

## How Generect Validates Catch-All Emails

Generect uses a combined, multi-layered approach to evaluate catch-all emails more accurately than a standard SMTP check.

### Validation Process

#### SMTP Check (baseline validation)

Checks whether the server accepts emails.\
On catch-all domains the response is always "accepted" → therefore insufficient on its own.

#### Pattern Analysis (AI-driven)

The system analyzes:

* whether the email matches the company's known email pattern
* similarity to other confirmed valid emails from the same domain
* frequency of this email format in previous validations

#### Historical Data Review

Generect checks:

* past successful deliveries to similar addresses
* whether similar formats previously resulted in bounces
* patterns observed across the domain

#### Public Records Matching

Generect searches for external signals verifying the address, including:

* corporate websites
* email signatures
* mentions in public documents
* references in social profiles (e.g., LinkedIn)

#### Deliverability Score (final result)

Every email receives a predicted deliverability score:

* **Low (30–50%)**
* **Medium (50–75%)**
* **High (75–95%)**

This is not a guarantee but provides a realistic risk assessment for catch-all domains.

<Tip>
  Use catch-all validation confidence scores to prioritize your outreach. High confidence scores (75%+) are generally safer to include in campaigns.
</Tip>

<Warning>
  Even with high confidence scores, catch-all emails carry more risk than standard validated emails. Consider this when planning large-scale campaigns.
</Warning>


# Choose the Right Workflow
Source: https://docs.generect.com/docs/choose-the-right-workflow

Generect supports multiple ways to find, verify, and enrich B2B contact data. Pick the workflow that matches what you're trying to accomplish.

# I want to...

## Build a target account list

Use ICP Search to define your ideal customer profile by industry, company size, location, revenue, technology stack, and more. Generect returns a list of matching companies in real time.

* [https://docs.generect.com/docs/icp-search](https://docs.generect.com/docs/icp-search)

## Find decision-makers

Search for specific contacts by role, title, seniority, or department within target companies. Get verified emails and direct phone numbers for the people who matter.

* [https://docs.generect.com/use-cases/saas/find-contacts](https://docs.generect.com/use-cases/saas/find-contacts)

## Get verified emails

Use the Email Finder to generate and validate corporate email addresses from a first name, last name, and company domain. Every email is automatically validated — no extra step required.

* [https://docs.generect.com/docs/email-finder](https://docs.generect.com/docs/email-finder)

## Verify a campaign list

Upload your existing list and use bulk email validation to check deliverability before sending. Remove invalid, disposable, and catch-all addresses to protect your sender reputation.

* [https://docs.generect.com/docs/email-validation](https://docs.generect.com/docs/email-validation)
* [https://docs.generect.com/use-cases/api/bulk-processing](https://docs.generect.com/use-cases/api/bulk-processing)

## Enrich my CRM

Push verified contact and company data directly into your CRM (HubSpot, Salesforce, Pipedrive). Keep records accurate and up to date without manual data entry.

* [https://docs.generect.com/use-cases/api/data-enrichment](https://docs.generect.com/use-cases/api/data-enrichment)
* [https://docs.generect.com/use-cases/api/automations-and-integrations](https://docs.generect.com/use-cases/api/automations-and-integrations)


# Create an Account
Source: https://docs.generect.com/docs/create-account

Step-by-step guide to get started with Generect

Follow these steps to create your Generect account and start discovering leads.

## Step-by-Step Guide

1. Go to [https://generect.com](https://generect.com)
2. Click **"Sign Up"** in the top-right corner
3. Register using Google, Microsoft, or your work email

<Tip>
  Personal email domains like gmail.com or outlook.com are not recommended
</Tip>

4. If you choose to sign up with your work email, create a secure password (minimum 8 characters)
5. After logging in, you automatically receive \$5 in free credits to test the platform

## Checklist After Registration

<AccordionGroup>
  <Accordion title="Run your first test search">
    Use the free \$5 credits to explore the platform and find your first leads
  </Accordion>

  <Accordion title="Validate a few email addresses">
    Try the Email Validation feature to see **How it works**
  </Accordion>

  <Accordion title="Export sample data">
    Export sample data to integrate it with your CRM
  </Accordion>

  <Accordion title="Review the API documentation">
    Check out the API Reference to understand programmatic access
  </Accordion>

  <Accordion title="Top up your balance">
    Add \$20–50 to continue using the platform without interruptions
  </Accordion>
</AccordionGroup>


# What Data Does Generect Provide?
Source: https://docs.generect.com/docs/data-coverage

Geographic coverage and data types

Generect covers the world's major business regions and gives you access to extensive datasets on companies and decision-makers. Our database is continuously expanding as we add new markets and improve data quality.

## Geographic Coverage

Generect supports lead and company search across most global business markets. Key regions include:

* **North America**: United States, Canada
* **Europe**: United Kingdom, Germany, France, Netherlands, Italy, Spain, Denmark, Norway, Sweden, Finland, Central & Eastern Europe
* **Asia–Pacific**: Singapore, Hong Kong, Japan, South Korea, Australia
* **Other Regions**: Latin America, Middle East, Africa

We support search in a very broad list of countries, and flexible filters help you find the right data in any region.

## Data Types

* **Company Data**: name, industry, size, location, tech stack, website status
* **Contact Data**: full name, job title, corporate email, direct phone number, LinkedIn profile, location

## Data Volume

* Tens of millions of companies
* Hundreds of millions of contacts worldwide
* Continuous updates and coverage expansion


# AI Corporate Email Finder
Source: https://docs.generect.com/docs/email-finder

Generate and validate corporate email addresses using AI

## How the AI Corporate Email Finder Works

In Generect, the Email Finder is a tool that:

1. Generates a corporate email address based on a person's name and company domain.
2. Uses AI-driven pattern prediction to build the most likely email format.
3. Automatically validates the generated email via SMTP.

**How it works:**

You provide a full name and a company domain.\
The system generates an email using the most common corporate patterns:

* [firstname.lastname@company.com](mailto:firstname.lastname@company.com)
* [firstname@company.com](mailto:firstname@company.com)
* [f.lastname@company.com](mailto:f.lastname@company.com)
* [firstnamelastname@company.com](mailto:firstnamelastname@company.com)

The email is then checked via SMTP – the company's mail server confirms whether the address is deliverable.

The result returns with one of the following statuses:

* **Valid**
* **Invalid**
* **SMTP** (server does not provide full validation, but address structure is correct)

**What you get:**

* A ready-to-use corporate email address
* A validation status (Valid / Invalid / SMTP)
* The result saved in your **Finder History**

## How to Use Email Finder in Search Mode

### Finding emails directly from ICP Search results

Inside the ICP Search results (Leads table), you can generate corporate emails instantly.

Simply click **Find Emails** next to any lead.\
Generect automatically:

* extracts the lead's first and last name
* identifies their company domain
* builds the most likely email pattern
* validates it via SMTP

All generated results appear immediately in the same table – no extra steps required.

### Bulk generation inside ICP Search results

You can click **Find Emails** for as many leads as you like.

After generation, every lead receives a status:

* **Valid**
* **Invalid**
* **Not opened** (email hasn't been revealed yet)

You can filter results using **Email status** and export only leads with valid corporate emails.

### How to Use Email Finder in separeted tab

1. Go to **Email Finder** in Side-Bar
2. Enter the lead's full name and email domain
3. Click **Find Email**
4. The result will appear in the table

<img alt="Email Finder" />

## Bulk Email Finder

If you need to find many email addresses at once:

1. Go to **Bulks → Bulk email finder**
2. Upload a CSV or XLSX file containing:
   * *First name*
   * *Last name*
   * *Company domain*
3. The system processes each row (pricing is shown in the interface).
4. Results appear as a structured table.

For each entry, Generect returns:

* a generated corporate email
* a status: **Valid / Invalid / Catch-all / Unknown / SMTP**

You can export the full results file with one click.

<Tip>
  Email Finder only charges when a valid email is found. Invalid results are free.
</Tip>


# Email Validation
Source: https://docs.generect.com/docs/email-validation

Validate existing email addresses for deliverability

The Email Validation module is designed to check *existing* email addresses and determine whether they are valid, invalid, or belong to catch-all domains.\
Unlike the **Email Finder**, this tool does not generate an email – it only validates the one you already have.

## How Generect Validates Emails

Generect performs a multi-layered validation process to ensure maximum accuracy for every email address.

**Validation process:**

<img alt="Validation Process" />

### Syntax Check

Verifies whether the email is written correctly (presence of "@", domain format, allowed characters, etc.).

### SMTP Verification (core step)

Generect sends a request to the email server to determine:

* whether the mailbox exists
* whether the server accepts mail
* whether the domain is configured as catch-all

The server returns a confirmation or rejection response.

### Catch-All Detection

If a domain accepts all emails – even for non-existing addresses – Generect marks it as **Catch-All**.

### Additional Signals

The system also analyzes:

* historical deliverability data
* previous validation results
* domain behavior patterns

This helps improve accuracy when servers use strict anti-spam or anti-bot protection.

## Possible validation statuses

* **Valid** – the address exists; the server confirmed mail acceptance.
* **Invalid** – the mailbox does not exist or the server rejected it.
* **SMTP** – the server does not provide a clear response (common on protected domains).
* **Catch-all** – the domain accepts any email, real or not; true deliverability is uncertain.
* **Unknown** – the server did not respond or provided an ambiguous response.

## What the user receives

* A clear validation status (Valid / Invalid / Catch-All / SMTP / Unknown)
* Technical verification details
* Automatic logging in **Validation History**
* Ability to export, filter, and clean lists based on validation results

## How to Validate a Single Email (Email Validator)

The **Email Validator** section allows you to manually check one email at a time.

**How it works:**

1. Go to **Email Validator**.
2. Enter an email address into the form.
3. Click **Validate email**.
4. The system performs an SMTP check and displays the result.

**Results appear in a table showing:**

* Email
* Status (Valid / Invalid / Catch-all / SMTP / Unknown)
* Validation date

All validated emails are saved in your **Validation History**.

## Bulk Email Validation

This module is used when you already have a list of email addresses and want to validate them all at once.

**How to run Bulk Validation:**

1. Go to **Bulks → Bulk email validation**.
2. Upload a CSV or XLSX file containing:
   * **Email**
3. Click **Upload file**.
4. The system processes each email individually.
5. Results appear in the table and are available for export.

**What Generect returns**

For each email:

* Status: **Valid / Invalid / Catch-all / Unknown / SMTP**
* Validation source
* Date of validation

Summary statistics:

* % of valid emails
* count of catch-all addresses
* count of invalid addresses
* number of unknown / SMTP results

You can download the cleaned list using the **Export** button.

<Card title="Catch-All Email Validation" icon="envelope" href="/docs/catch-all-validation">
  Learn about advanced validation for catch-all domains
</Card>


# Exclude Lists
Source: https://docs.generect.com/docs/exclude-lists

Filtering out unwanted companies and leads from your searches

## What Are Exclude Lists and Why They Matter

**Definition:**\
Exclude Lists are lead or company lists that should be *hidden* from your search results. Anything added to an Exclude List will not appear in ICP Search results and will not be included in exports.

You can create Exclude Lists in two ways:

* directly from your search results
* by uploading ready-made files in the **Exclusions** section

**Why this matters:**

* avoid re-contacting leads that were already processed
* hide existing customers from new outbound searches
* filter out competitors, internal domains, or irrelevant companies
* save credits and team time by working only with relevant data

## How to Access and Use Exclude Lists

### Create an Exclude List from ICP Search results

1. Run your ICP Search.
2. Select the leads or companies you want to hide.
3. Add them to an Exclude List – either create a new list or choose an existing one.

### Upload a ready-made list in the Exclusions section

<img alt="Exclusions" />

1. Go to **Exclusions** in the sidebar.

2. Click **Upload data**.

3. Choose the type of list:
   * **Leads List** – must contain at least one of the following columns:\
     *Email, LinkedIn Lead Link, LinkedIn Lead ID*
   * **Companies List** – must contain at least one of the following columns:\
     *Company Name, Website, LinkedIn Company Link, LinkedIn Company ID*

4. Upload a CSV or XLSX file.

5. The list will appear in your Exclusions library immediately after uploading.

6. Open **Search**.

7. In **General filters**, find the **Excluded lists** section.

8. Select one or multiple exclude lists.

All leads or companies included in these lists will automatically be removed from your ICP Search results and exports.

<Card title="Use Cases for Exclude Lists" icon="lightbulb" href="/use-cases/exclude-lists-use-cases">
  See practical examples of using exclude lists to improve search quality
</Card>

<Tip>
  Regularly update your exclude lists to keep them current and effective
</Tip>


# FAQ for New Users
Source: https://docs.generect.com/docs/faq

Frequently asked questions about Generect

<AccordionGroup>
  <Accordion title="How much does Generect cost?">
    We operate on a pay-as-you-go model. Searching is free. You only pay \$0.03 for each revealed contact and \$0.02 for exported leads.\
    The minimum top-up is \$20.\
    There are no monthly subscriptions.
  </Accordion>

  <Accordion title="Where does your data come from?">
    We aggregate data from 100+ public and private sources, including LinkedIn, official company websites, public registries, and job boards.\
    Our system updates data in real time to ensure accuracy and freshness.
  </Accordion>

  <Accordion title="Do you guarantee email accuracy?">
    Yes. All emails are verified before being returned.\
    Our deliverability rate is 95%+.\
    If an email turns out to be invalid, we automatically refund the credits.
  </Accordion>

  <Accordion title="How long does lead search take?">
    Generect works in real time. Most searches take only a few seconds, depending on filters and query complexity.\
    API queries return results almost instantly.
  </Accordion>

  <Accordion title="Can Generect integrate with our CRM?">
    Yes. We support native integrations with HubSpot, Salesforce, and any custom workflow through our API.
  </Accordion>

  <Accordion title="Are there any search limits?">
    No limits.\
    You can run as many searches as you want – you only pay for revealed or exported contacts.
  </Accordion>

  <Accordion title="Do you offer a trial?">
    Yes. Every new user receives \$5 in free credits to test the platform – enough to try lead search, email validation, and phone reveal.
  </Accordion>

  <Accordion title="What if I cannot find the contacts I need?">
    Try adjusting or expanding your filters, using different roles or locations, or searching by a specific LinkedIn profile (company or person) for more precise results.
  </Accordion>
</AccordionGroup>


# How Generect Works
Source: https://docs.generect.com/docs/how-generect-works

Core workflow from ICP definition to outreach

A typical end-to-end workflow looks like this:\
**Define your ICP → Find companies or leads → Get contact data → Validate emails → Export/Integrate → Start outreach**

```mermaid theme={null}
graph TD
    A[Define ICP] --> B[Find Companies/Leads]
    B --> C{Get Data}
    C --> D[Reveal Contacts]
    C --> E[Enrich Existing]
    D --> F[Validate Emails]
    E --> F
    F --> G[Export/Integrate]
    G --> H[Start Outreach]
```

## Step-by-Step Breakdown

### Build Your ICP (Ideal Customer Profile)

Define the attributes of your target customer.\
You can specify:

* Industry
* Company size
* Location
* Technology stack (optional but useful)
* Job titles, skills, and other criteria

### Find Target Companies and Leads

Use your ICP to run a company or lead search.\
You can:

* Apply additional filters to narrow down results
* Exclude unwanted audiences (for example, existing customers) using exclude lists

### Get Contacts for Decision-Makers

Select relevant roles such as CEO, CTO, VP Sales, Head of Marketing, etc.\
Generect will automatically:

* Identify contacts that match your criteria
* Provide verified emails and direct phone numbers
* Use AI Corporate Email Finder to generate corporate emails when necessary

### Validate Before Sending

Ensure your emails are deliverable.\
Generect provides:

* Standard email validation
* Detection of fake or disposable emails
* Catch-All Email Validation with confidence scoring

### Export or Integrate Your Data

You can:

* Download results in CSV/XLSX for email tools
* Sync your data directly with your CRM

### Start Personalized Outreach

Use your verified contact data to:

* Create tailored outreach sequences
* Improve reply rates with accurate, up-to-date information

<Card title="Learn More About ICP Search" icon="magnifying-glass" href="/docs/icp-search">
  Deep dive into building effective ICP searches
</Card>


# ICP Search
Source: https://docs.generect.com/docs/icp-search

Finding companies and contacts that match your Ideal Customer Profile

## What Is ICP Search and **How it works**

**Definition:**\
ICP Search is a tool for finding companies and contacts that perfectly match your Ideal Customer Profile. It allows you to build a highly targeted dataset based on real company and contact attributes.

**How it works:**

1. You define criteria for companies or leads using filters.
   * **Company filters include:**\
     Industry, Location, Headcount, Company Name, Founded Year, Website Status
   * **Lead filters include:**\
     Job Title, Personas, Skills, Location, Number of Leads per Company, Number of Connections, Data Accuracy Period
2. Generect searches through cached databases or live data depending on availability.
3. The system returns a refined list of companies or contacts that match your ICP.
4. You receive a set of verified leads ready for outreach.

**Key Benefits:**

* **Accurate targeting:** results match your ICP parameters as closely as possible.
* **Flexible filtering:** combine multiple criteria to shape an exact company or contact profile.
* **Fresh data:** Generect returns cached or live results depending on what's available.
* **Exclude lists:** remove unwanted companies or existing clients from your results.
* **Custom Search:** use your own LinkedIn profiles, domains, or company lists.

## How to Build an ICP Search Query

### Step 1: Start a New Search

<img alt="ICP Search step 1" />

In the Search section, click **New filter**.\
This opens the full list of filters you can use to build your ICP.

### Step 2: Choose your filters

All filters are universal and they work for both companies and leads.

* **Job Title** – search for specific roles
* **Personas** – predefined role templates (Executive, Sales, Engineering, Marketing) that speed up ICP setup
* **Skills** – find people with specific expertise (Python, SalesOps, Product Management, etc.)
* **Number of leads per company** – limit contact volume per company
* **Number of connections** – helpful for B2B outreach (more active profiles)
* **Data accuracy period** – filter by freshness of data
* **Company name** – useful for competitor lists or known targets
* **Location** – for companies or contacts
* **Industry** – narrow down your market segment
* **Headcount** – company size
* **Founded year** – young or mature companies
* **Specialities** – company expertise areas (Legal Services, IT Consulting, Manufacturing)
* **Website status** – active/inactive sites

You can apply one filter or combine several – the system supports any configuration.

### Step 3: Run the search

<img alt="ICP Search step 3" />

* Start the search
* Review your results
* Adjust filters as needed
* Reveal contacts to get verified emails and phone numbers

### Step 4: Choose Leads or Companies view

You can view your results in two modes:

<img alt="ICP Search step 4" />

* **Leads** – a list of contacts that match your criteria
* **Companies** – a list of companies that match the same filters

Both use the same ICP filters, and switching between them keeps your configuration intact.

<Card title="Use Case: Finding Engineering Leads in German IT Services" icon="lightbulb" href="/use-cases/icp-search-engineering-leads">
  See a real-world example of building an ICP search
</Card>

## Advanced Filters for ICP Search

Advanced filters allow you to build a more precise ICP, narrow your dataset to the most relevant companies and leads, and reuse your configurations later.

### Personas (Reusable Role Templates)

A **persona** is more than a set of job titles – it's a **saved role template** you can use in any ICP Search.

A persona may include:

* **Functions:**\
  Sales, Marketing, Technology, IT, HR, Education, Business Development, Manufacturing, or custom functions.
* **Seniorities:**\
  President, Owner, Founder, VP, C-Level, Head, Director, Manager, Specialist.
* **Keywords (include/exclude):**\
  For fine-tuning profile descriptions or job titles.

**Examples of personas:**

* "Sales Leadership EU"
* "Technical Founders US"
* "HR Directors Global"

<img alt="ICP Search step 5" />

<Card title="Use Case: Using Personas for SDR Workflows" icon="lightbulb" href="/use-cases/personas-sdr-workflow">
  Learn how SDRs save time with reusable persona templates
</Card>

### Skills & Specialities (Expertise-Based Filtering)

Search by skills of individuals or by the specialisation of companies.

**Skill examples:** Python, Cloud, Prospecting, SQL, DevOps, SalesOps\
**Specialities examples:** IT Consulting, Legal Services, Education, Manufacturing

Useful when searching for contacts with specific expertise.

### Profile & Data Quality Filters

* **Data accuracy period:** how fresh the data should be
* **Number of connections:** approximate activity level of the profile
* **Number of leads per company:** control dataset density

Helps improve result quality and reduce noise.

### Exclude Lists

Exclude companies or leads you don't want to see in your results.

You can upload a CSV with:

* existing customers
* competitors
* unwanted segments

The system automatically removes them from your dataset.

<Card title="Learn More About Exclude Lists" icon="list" href="/docs/exclude-lists">
  Deep dive into using exclude lists effectively
</Card>

### Custom Search (Advanced Manual Targeting)

Use your own data sources:

* LinkedIn profiles
* Domains
* Company names

Perfect for enrichment workflows, CRM data processing, or validating segments from Sales Navigator.


# Platform Overview
Source: https://docs.generect.com/docs/platform-overview

Understanding the SaaS Interface and API access

Generect offers two ways to work with the platform – through the SaaS Interface or via API.

## SaaS Interface

A no-code interface designed for fast, intuitive lead search.

**What you can do in the SaaS Interface:**

* Run company and contact searches using ICP-based filters
* Use visual filters and saved filter presets
* Export data to CSV/XLSX
* Integrate your results with your CRM directly from the UI

**Where everything is located in the SaaS Interface:**

* **Search**: Find companies and contacts based on your ICP
* **Email Finder / Validation**: Generate corporate emails and check deliverability
* **API Keys**: Create and manage your API keys
* **Integrations**: Connect Generect to your CRM or other tools
* **Billing**: View your balance, transaction history, top up your account, and track discount tiers

<Card title="SaaS Interface Screenshot" icon="browser">
  <img alt="SaaS Interface" />
</Card>

## API Access

For teams looking to automate workflows or integrate Generect directly into their systems.

**Features available via API:**

* RESTful API for full automation
* Programmatic access to all platform functionality
* Webhooks for real-time updates
* MCP (Model Context Protocol) for AI-powered data processing

### Key API Concept: Preview & Pay

You can search and preview results showing basic info — free in the Generect app, \$0.002 per result through the API. You only pay the full price when you decide to **reveal** full contact details, including email or phone.

* **Preview**: free in the app, \$0.002 per result via the API (Name, Company, Title)
* **Reveal**: Paid (Verified Email, Phone, Full Profile, Social Links)

<Card title="API Documentation" icon="square-code" href="/api-reference/introduction">
  Learn how to use the API
</Card>


# Security & Compliance
Source: https://docs.generect.com/docs/security-compliance

How Generect handles your data, privacy, and legal agreements

## Data protection & GDPR

Generect operates in line with the **GDPR**. Our public legal terms:

* [Privacy Policy](https://generect.com/privacy) — what we collect and why, including US state privacy rights
* [Terms of Service](https://generect.com/terms)
* [Legal Notices](https://generect.com/legal) and [Cookie Policy](https://generect.com/cookie-policy)

## Data Processing Agreement (DPA)

Our [Data Processing Agreement](https://generect.com/dpa) covers personal data processed through the API and the app. It is accepted together with the [Terms of Service](https://generect.com/terms), so there is nothing to sign — send the link straight to your legal or security team.

It includes the processing details (Annex I), the technical and organisational measures (Annex II) and the current sub-processor list with hosting locations (Annex III), which is usually what a security review asks for next.

Need a **countersigned copy**, or have another data-protection question? Write to [dpa@generect.com](mailto:dpa@generect.com).

## Infrastructure & security practices

* **Hosting:** the application and database run in **EU data centers**; static web assets are served from our provider's US location.
* **In transit:** all API traffic is encrypted over HTTPS/TLS.
* **Payments:** processed entirely by **Stripe** — card data never touches Generect servers.
* **API keys:** scoped per token; every key can be paused, renamed, or revoked instantly from [your settings](https://app.generect.com/settings/api), and usage and transaction history are visible via the [account endpoints](/api-reference/endpoint/accounts/get-account-usage).
* **Billing transparency:** every charge is itemized (`meta.amount_charged`, transactions, invoices) — see [Pricing](/billing/pricing).

## Certifications

We do not currently hold SOC 2 or ISO 27001 certification. If your security review needs a completed questionnaire (CAIQ/SIG or your own), contact [dpa@generect.com](mailto:dpa@generect.com) — the same address as the DPA, so the whole review stays in one thread.

## Uptime & incidents

Live status, 90-day uptime history, and incident reports are public at [status.generect.com](https://status.generect.com). See also [Reliability](/api-reference/reliability).


# What Is Generect
Source: https://docs.generect.com/docs/what-is-generect

The Lead Search Engine for Real-Time B2B Lead Generation

**Generect** is a platform for real-time B2B lead discovery and verification. It helps teams find verified contacts in seconds instead of spending hours on manual research.

## Quickstart

<CardGroup>
  <Card title="Create Account" icon="user-plus" href="/docs/create-account">
    Start finding verified leads in minutes
  </Card>

  <Card title="Platform Overview" icon="layer-group" href="/docs/platform-overview">
    Explore our SaaS interface and features
  </Card>

  <Card title="Find Leads" icon="magnifying-glass" href="/docs/icp-search">
    Search by industry, role, and more
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Automate your workflow with our API
  </Card>
</CardGroup>

## What Generect Does

* Finds verified corporate email addresses and direct phone numbers
* Validates email deliverability before sending to reduce bounce rates
* Builds targeted lead lists based on your ICP (industry, company size, location, role, tech stack, and more)
* Enriches existing company and contact data (LinkedIn profiles, domains, industries, technologies, key profile attributes)
* Integrates with your CRM and internal tools via API
* Detects company growth signals (hiring, funding, job openings - available in company profiles)

## Who Generect Is For

* **Founders**: Quickly discover the right potential customers without heavy manual work
* **Lead Generation teams**: Get accurate, verified contacts without extra validation steps
* **Early-stage teams**: Launch outbound with high-quality data from day one
* **Sales managers**: Spend less time cleaning lists and more time closing deals

## Our Mission

Achieve a 60% reply rate by providing the highest-quality data possible.\
Less spam - more meaningful conversations with genuinely interested prospects.


# Why is Generect
Source: https://docs.generect.com/docs/why-is-generect



# Who Is Generect For?

Generect is built for anyone who needs accurate, verified B2B contact data — without the overhead of enterprise contracts or stale databases.

* **Founders** — Discover potential customers quickly without hiring a research team or spending hours on manual prospecting.
* **Sales teams** — Get verified emails and direct phone numbers so your outreach actually reaches decision-makers instead of bouncing.
* **Lead generation agencies** — Deliver higher-quality leads to your clients with real-time data, built-in validation, and bulk processing.
* **Marketing agencies** — Help clients reach the right audience with targeted, verified contact lists based on real ICP criteria.
* **Revenue operations** — Keep CRM data accurate and up to date with enrichment workflows and API integrations.
* **Developers and infrastructure teams** — Automate lead discovery, enrichment, and validation inside your own tools via the Generect API or MCP.

# What Problems Does Generect Solve?

### Outdated contact data

Most B2B databases rely on cached information that decays over time. Titles change, people switch companies, emails stop working.Generect offers two data modes: a fast database with regularly updated records, and a real-time search option for maximum freshness when it matters most.

### Unverified emails killing deliverability

Sending to unverified addresses hurts your sender reputation and wastes your team's effort. Generect validates every email before you export it, helping you maintain high deliverability and reduce bounce risk. You can also validate your existing lists in bulk.

### Wasted time on manual research

Sales reps spend hours searching for the right contact on LinkedIn, guessing email formats, and copying data into spreadsheets. Generect consolidates this into a single workflow: search by ICP, find contacts, verify, enrich, and export.

### Paying for leads you can't use

Many tools lock you into monthly subscriptions where you pay for a fixed number of credits — whether you use them or not. Generect uses “pay-as-you-go pricing”: you only pay for the contacts you actually get.

### CRM data going stale

CRM records decay fast when no one updates them. Generect's enrichment tools and API integrations help teams keep contact and company data current without manual effort.

# How Generect Compares to Alternatives

### Generect vs. Apollo

*Apollo* primarily works with a cached contact database. *Generect* offers both regularly updated database search for speed and scale, and a real-time search option for the freshest available data. *Generect* also includes built-in email validation, exclude lists, direct HubSpot integration, and pay-as-you-go pricing with no subscription lock-in.

### Generect vs. Hunter.io

*Hunter.io* is primarily an email finder with a limited database. *Generect* goes beyond email search with a larger, ICP-based contact base, regularly updated and real-time data options, built-in email validation, exclude lists to filter out irrelevant contacts, a more capable API (not just email search), and direct CRM integration without manual imports.

### Generect vs. ZoomInfo

*ZoomInfo* charges premium subscription prices for data that is often outdated. *Generect* focuses on fresh, verified data with regularly updated database search and real-time options, and pay-as-you-go flexibility — no lengthy contracts or minimums.

### Generect vs. Lusha

*Lusha* focuses on contact data but lacks real-time verification and robust enrichment capabilities. *Generect* adds regularly updated and real-time search options, automatic email validation, company enrichment (revenue, tech stack, industry), and API/MCP integrations for automated workflows.

### Generect vs. Kaspr

*Kaspr* is limited to LinkedIn contact extraction. *Generect* provides a broader approach with ICP-based search, regularly updated and real-time data options, email validation, company enrichment, bulk processing, and direct API access for building automated pipelines.

# Where Generect Is Especially Strong

* **Real-time prospecting** — when you need fresh data, not outdated
* **Regularly updated database** — fast search with current records
* **High-volume outbound** — bulk verification and enrichment at scale
* **API-driven workflows** — automate lead discovery and CRM sync
* **Cost-conscious teams** — pay only for what you use, no subscription waste
* **CRM hygiene** — keep contact and company records accurate over time
* **AI and automation stacks** — Generect MCP connects live lead data to AI tools

# Why Try Generect?

* **Built-in email validation** for high deliverability
* **Real-time data**, when maximum freshness matters
* **Fresh, regularly updated database**
* **Pay-as-you-go** — no subscription required
* **API + MCP** for automation and AI integration
* **Bulk processing** for lists of any size

**Start finding verified leads in minutes:**\
Create a free account: [https://app.generect.com/](https://app.generect.com/)

or

Book a demo: [https://generect.com/book-demo](https://generect.com/book-demo) to see it in action.


# Agent Builder
Source: https://docs.generect.com/integrations/agent-builder/agent-builder



As we already know from [About MCP](/integrations/mcp/about-mcp) — MCP allows to LLM use API by just asking AI. This approach is especially useful for connecting tools like Generect, which provides live company and lead data, to OpenAI's Agent Builder, which orchestrates multi-step workflows.

# What Generect does

Generect Live API delivers real-time business and contact data from verified sources like LinkedIn, Crunchbase, and company websites. Unlike static databases, it doesn't rely on outdated snapshots – every request fetches live information.

What makes it useful:

* **Fresh data**: Always current, no batch updates needed.
* **AI email finder**: Predicts and validates emails with a proprietary system.
* **Catch-all validation**: Detects risky addresses with far higher accuracy.

MCP endpoint (what you connect Agent Builder to): `https://mcp.generect.com/mcp`

REST API base URL (for direct HTTP calls, not for the MCP node): `https://api.generect.com`

## Why combine Generect + OpenAI Agent Builder

OpenAI's **Agent Builder** lets you visually design, debug, and deploy multi-step AI workflows.\
By integrating Generect into it via MCP, you can create agents that **search live company data**, **find leads**, **validate emails**, and **summarize results**, all in one conversational flow.

Imagine typing this into a chat: "Find 5 leads from Google and 5 from Microsoft, then compare their recent hires."

The agent automatically:

1. Calls Generect through MCP to fetch live data.
2. Compares results.
3. Returns a clear summary.

## How the integration works

Connecting Generect to OpenAI's Agent Builder through **MCP** only takes a few minutes. Once it's connected, your agents can directly call Generect's live API (fetching company data, finding leads, and validating emails) all from within your workflow.

Follow these steps:

### Step 1. Add an MCP Node

In your workflow canvas inside **Agent Builder**, click **"Add Node"** and select **MCP** from the list.

<img alt="Agent builder step 1" />

This node acts as the bridge between your agent and the Generect API.

### Step 2. Click "+ Server"

In the MCP node settings panel, click the "+ Server" button to add a new server connection.

<img alt="Agent builder step 2" />

This tells Agent Builder which external service you want to connect to.

### Step 3. Enter the Generect MCP URL

In the *Server URL* field, enter the MCP endpoint:

```
https://mcp.generect.com/mcp
```

<img alt="Agent builder step 3" />

<Warning>
  This is the **MCP** endpoint, not the REST API base URL. `https://api.generect.com/`
  is the REST API and does not speak MCP — an MCP node pointed at it will fail to
  list any tools.
</Warning>

### Step 4. Choose authentication type

From the authentication dropdown, choose Access Token.
Generect uses a simple Bearer Token (API key) system for secure access.
Now you'll need to generate that token.

#### Step 4.1. Log In to Generect

Go to [https://app.generect.com/](https://app.generect.com/) and sign in with your account.

#### Step 4.2. Open the API section

In the top navigation bar, find the API option and click it.

<img alt="Agent builder step 4.2" />

#### Step 4.3 Create a new key

Click "+ New Key" to generate a new access token.

<img alt="Agent builder step 4.3" />

#### Step 4.4 Paste the key

After creation, copy your new key and return to Agent Builder.

In the MCP server connection window:

* Paste the key into the *Access Token* field.
* Review your settings.
* Click *Connect*.

Once connected, you'll see your Generect MCP server appear in the list.

<img alt="Agent builder step 4.4" />

### Step 5. Create your agent workflow

In **Agent Builder**, everything happens on a visual canvas. You'll build a workflow with a series of **nodes** that represent steps.

A simple workflow might look like this:

`User Input → Agent → MCP (Generect) → Transform → Output`

Here's what each node does:

* **Start Node:** Captures user input (e.g., "Find founders from biotech startups.")
* **Agent Node:** Interprets the query, decides what to fetch.
* **MCP Node:** Sends a request to the Generect API.
* **Transform Node:** Reshapes or filters the data.
* **Output Node:** Returns clean, readable results to the user.

### Step 6. Configure the MCP Node

When adding an MCP node in Agent Builder:

1. Choose your server: `generect`
2. Select the endpoint you want to use, for example:
   * `/companies/by_icp/`
   * `/leads/by_icp/`
   * `/emails/email_validation/`

Add parameters. You can use variables from previous nodes, like:

```json theme={null}
{
 "industry": {{ user_input.industry }},
 "location": {{ user_input.location }},
 "limit": 5
}
```

3. Test your call using **Preview** to confirm the data looks correct.

### Step 7. Transform and display results

Once the MCP node fetches data, use a **Transform** node to shape it into an easy-to-read format.

For example, you might only want to show names, companies, and validated emails.

Sample transformation (pseudo-code):

```json theme={null}
{
  "leads": [
    {  
      "name": lead.full_name,
      "company": lead.company_name,
      "email": lead.valid_email
    }
  ]
}
```

Then pass that to your final **Agent node** to generate a summary like: "Here are 5 verified leads from biotech startups in San Francisco."


# What is MCP?
Source: https://docs.generect.com/integrations/mcp/about-mcp

About MCP in context of Generect

**MCP** (Model Context Protocol) is an open protocol that enables AI models to securely interact with local and remote resources through standardized server implementations.
This list focuses on production-ready and experimental MCP servers that extend AI capabilities through file access, database connections, API integrations, and other contextual services.

<img alt="mcp-example" />

<sup>You can read more about it in [this](https://glama.ai/blog/2024-11-25-model-context-protocol-quickstart) article</sup>

***

In the context of **Generect**, MCP enables you to chat with an LLM, and it can **query and search information from the Generect API** and process the data for you.\
You don't need to specify parameters for searches manually — **the LLM will determine them automatically**.

Instead of searching leads yourself, you can simply ask:

`Find 5 chief leads from Google and compare them with 5 chief leads from Microsoft.`

The LLM will use MCP, fetch all data and write a summary.

<img alt="response-example" />


# Common problems
Source: https://docs.generect.com/integrations/mcp/common-problems

This page describes common Problems you may encounter when using **MCP with Generect API**, and how to solve them.

***

## The agent spent more credits than I expected

**Cause:** search and enrich are billed **per returned row**, so an agent that
searches before sizing the audience pays for every row it looks at, including the
ones it then throws away.

**Solution:**

* Size the audience with `count_leads` / `count_companies` first — cached counts
  are **free** and also return the cost of the next step at your account's rates.
* Look at real people with `preview_leads` before paying for a full search.
* Keep `mode` on `auto` (the default) or `database`. `realtime` costs more per row,
  and a realtime *count* is billable.
* Check `cost.amount_charged_usd` in each response, and `get_balance` before and
  after a batch, to see exactly what was spent.
* If you are running an old local install, upgrade: builds before **0.7.0** have
  no free counting tools and no row cap. See [MCP tools and what they cost](tools).

***

## MCP Registry not found or connection failed

**Cause**: The client doesn't support MCP Registry, or the registry identifier is incorrect.

**Solution**:

* Ensure you're using a client that supports MCP Registry (e.g., latest Claude Desktop versions).
* Verify the registry identifier: `com.generect/generect-mcp`
* If your client doesn't support registry, use the [Local MCP (npx)](quick-start) method instead.

***

## 401 Unauthorized error

**Cause:** Your API key is invalid or missing.

**Solution:**

* Make sure you replaced `your-api-key` with your actual key.
* For **Local MCP**, set the env var to either `GENERECT_API_KEY="your-real-key"` or `GENERECT_API_KEY="Token your-real-key"` — both are accepted.
* For **Remote MCP** with a custom `Authorization` header, any of these forms work: `YOUR_API_KEY`, `Bearer YOUR_API_KEY`, `Token YOUR_API_KEY`, or `Bearer Token YOUR_API_KEY`.
* Verify the key is active in <a href="https://app.generect.com">app.generect.com</a>.

***

## Timeout error

**Cause:** The API request took longer than the default timeout (1 minute). For example, a lead search may take longer with very broad filters.

**Solution:**

* If you are using local MCP: increase the timeout limit in your MCP configuration (default: `60000` ms).

```json theme={null}
"GENERECT_TIMEOUT_MS": "180000"
```

* Try refining your query (e.g., add more filters for leads or companies).

***

## MCP server does not appear in the client

**Cause**: Configuration file is invalid, or the MCP server didn't start.

**Solution**:

* Double-check JSON syntax and content in your config (`claude_desktop_config.json`, Cursor config). NPM should be `generect-ultimate-mcp`
* Try setting MCP\_DEBUG=1 to see logs when starting the MCP.
* Restart your client after editing the configuration.

***

### LLM doesn't call MCP tools

**Cause**: The LLM decides when to call external tools — it may not always trigger them.

**Solution**:

* Rephrase your request in a way that makes tool usage more likely (e.g., explicitly ask to "search leads").
* Check that the MCP server is shown as active in the client's settings.


# Local MCP (npx)
Source: https://docs.generect.com/integrations/mcp/quick-start

Quick guide to use Generect MCP with local installation

Our MCP server provides integration between the **Generect Live API** and any Client that supports MCP (e.g., [Cursor](https://cursor.com/home), [Claude Desktop](https://claude.ai/download), [OpenAI's Responses API](https://platform.openai.com/docs/api-reference/responses)). This allows you to access **Generect's lead search, company search, email generation**, and other tools directly in **natural language workflows**.

<Note>
  <strong>Two integration methods available:</strong>

  * **[Remote MCP (Custom Connectors)](remote-mcp)** — No installation required, connect via URL or registry ID
  * **Local MCP (this page)** — Uses `npx` to run the MCP server locally
</Note>

The local MCP server runs on your machine via `npx generect-ultimate-mcp` and talks to the Generect API at `https://api.generect.com`. (The hosted remote MCP server lives at `https://mcp.generect.com/mcp` — see [Remote MCP](remote-mcp).) The configuration on different clients has some minor differences.

# Configuration

<Warning>
  In all configurations, don't forget to replace the placeholder API key with your actual key.
</Warning>

## How to use MCP with Claude Desktop?

For remote MCP (no installation), see [Remote MCP (Custom Connectors)](remote-mcp). This page covers local MCP via npx.

Use [Claude Desktop](https://claude.ai/download) and visit **Settings** (click your account icon → **Developer** tab → **Edit config**).

Visit **Settings** in the Claude Desktop app. You can find them in dropdown when click on your account icon. Then navigate to the **Developer** tab, click **Edit config** button

<img alt="claude-developer-settings" />

This will show your `claude_desktop_config.json` file:

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Next, add MCP Server configuration to this file. Replace `your-api-key` with your actual API key. The `Token` prefix is optional — both `your-api-key` and `Token your-api-key` are accepted.

```json theme={null}
{
  "mcpServers": {
    "generect-api": {
      "command": "npx",
      "args": ["-y", "generect-ultimate-mcp@latest"],
      "env": {
        "GENERECT_API_BASE": "https://api.generect.com",
        "GENERECT_API_KEY": "Token your-api-key",
        "GENERECT_TIMEOUT_MS": "60000",
        "MCP_DEBUG": "0"
      }
    }
  }
}
```

Restart Claude Desktop to apply changes. After that you will see `generect-api` MCP as active in `Search and tools` dropdown.

After some message where Claude decides to (for example) search leads, you will be prompted to allow the use of external tool.

<img alt="claude-prompt" />

Here is response of example, where Claude automaticlly analyzed LinkedIn profile (some sensitive information was hidden)

<img alt="response-example" />

***

## How to use MCP with Cursor?

Use this button to add MCP **directly to Cursor IDE**:

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=generect&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImdlbmVyZWN0LXVsdGltYXRlLW1jcEBsYXRlc3QiXSwiZW52Ijp7IkdFTkVSRUNUX0FQSV9CQVNFIjoiaHR0cHM6Ly9hcGkuZ2VuZXJlY3QuY29tIiwiR0VORVJFQ1RfQVBJX0tFWSI6IlRva2VuIDxhcGkta2V5PiIsIkdFTkVSRUNUX1RJTUVPVVRfTVMiOiI2MDAwMCJ9fQ%3D%3D">
  <img alt="Install MCP Server" />
</a>

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=generect&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImdlbmVyZWN0LXVsdGltYXRlLW1jcEBsYXRlc3QiXSwiZW52Ijp7IkdFTkVSRUNUX0FQSV9CQVNFIjoiaHR0cHM6Ly9hcGkuZ2VuZXJlY3QuY29tIiwiR0VORVJFQ1RfQVBJX0tFWSI6IlRva2VuIDxhcGkta2V5PiIsIkdFTkVSRUNUX1RJTUVPVVRfTVMiOiI2MDAwMCJ9fQ%3D%3D">
  <img alt="Install MCP Server" />
</a>

Read [Cursor Docs](https://docs.cursor.com/en/context/mcp) for more info.

# Available Tools

The MCP integration provides access to the following `Generect API` functions:

* `search_leads`: Search for leads by ICP filters
* `search_companies`: Search for companies by ICP filters
* `generate_email`: Generate an email using first/last name and domain
* `get_lead_by_url`: Get LinkedIn lead by profile URL
* `health`: Quick health check against the API


# Remote MCP (Custom Connectors)
Source: https://docs.generect.com/integrations/mcp/remote-mcp

Connect to Generect MCP via Custom Connectors - no local installation required

Remote MCP servers extend AI capabilities beyond your local environment, providing access to internet-hosted tools and data sources. By connecting to Generect's remote MCP server, you can access lead search, company search, and email generation directly in your AI conversations without any local installation.

<Note>
  Remote MCP works with Claude (web and Desktop) and other MCP-compatible
  clients. For local installation via npx, see
  <a href="quick-start">Local MCP (npx)</a>.
</Note>

***

## Server Information

| Property | Value |
| - | - |
| **Registry ID** | `com.generect/generect-mcp` |
| **Remote URL** | `https://mcp.generect.com/mcp` |
| **Transport** | Streamable HTTP |
| **Auth** | OAuth 2.1 or API Key |

***

## Claude Desktop — Custom Connectors

<Warning>
  Claude documentation states:
  **Custom connectors are available for users with paid plans (Pro, Max, Team, or Enterprise).**

  This may change in the future, but for now this restriction applies.
</Warning>

<Steps>
  <Step title="Navigate to Connector Settings">
    Open [Claude Desktop](https://claude.ai/download). Click on your profile icon and select **Settings** from the dropdown menu. Then click on **Connectors** in the sidebar.
  </Step>

  <Step title="Add a Custom Connector">
    Scroll to the bottom and click **Add custom connector**.

    Enter the Generect MCP server URL:

    ```
    https://mcp.generect.com/mcp
    ```

    Leave Advanced settings empty.

    <img alt="enter-url" />

    Click **Add** to proceed.
  </Step>

  <Step title="Complete Authentication">
    Then click on "Connect". You will be redirected to login page.

    <img alt="click-connect" />

    Get your API key from <a href="https://app.generect.com">app.generect.com</a> and enter it on the login page.

    <img alt="click-connect" />
  </Step>

  <Step title="Connector is ready">
    Now you can use Generect MCP server. Make sure that you have enabled it in Connectors tab.

    <img alt="response-example" />
  </Step>
</Steps>

***

## Other Clients (Cursor, OpenAI, etc.)

Integration with other MCP-compatible clients follows the same pattern:

1. **Find the MCP/Connector settings** in your client
2. **Add a remote MCP server** with URL: `https://mcp.generect.com/mcp`
3. **Configure authentication** with your API key (see formats below)

<Note>
  Each client has its own configuration method — look for "MCP", "Connectors",
  or "Tools" in settings. Some clients may require editing a config file, others
  provide a UI.
</Note>

### Supported `Authorization` header formats

If your client passes the API key directly via an `Authorization` header (no OAuth flow), the server accepts any of:

```
Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
Authorization: Token YOUR_API_KEY
Authorization: Bearer Token YOUR_API_KEY   (legacy, still supported)
```

Pick whichever format your client makes easiest. Example for `mcp-remote`:

```json theme={null}
{
  "mcpServers": {
    "generect": {
      "command": "mcp-remote",
      "args": [
        "https://mcp.generect.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

***

## Remote MCP vs Local MCP

| Feature | Remote MCP | Local MCP (npx) |
| - | - | - |
| Installation | None required | Requires Node.js & npx |
| Configuration | URL or registry ID | Command + args in config |
| Access | Any MCP-compatible client | Requires local setup |
| Offline access | Not available | Available (with cached data) |
| Updates | Automatic | Manual (`@latest`) |

Choose **Remote MCP** for simplicity and accessibility. Choose **Local MCP** if you need offline capabilities or have network restrictions.

***

## Available Tools

The MCP integration provides access to the following `Generect API` functions:

* `search_leads`: Search for leads by ICP filters
* `search_companies`: Search for companies by ICP filters
* `generate_email`: Generate an email using first/last name and domain
* `get_lead_by_url`: Get LinkedIn lead by profile URL
* `health`: Quick health check against the API

***

## MCP Registry

Generect MCP is registered in the official MCP Registry:

```
com.generect/generect-mcp
```

* **Registry**: `com.generect/generect-mcp`
* **Repository**: [github.com/generect/generect\_mcp](https://github.com/generect/generect_mcp)


# MCP tools and what they cost
Source: https://docs.generect.com/integrations/mcp/tools

Every tool the Generect MCP server exposes, whether it spends credits, and the order to call them in

The MCP server is a thin, honest wrapper over the Generect API. Two rules make it
safe to hand to an autonomous agent:

1. **Sizing an audience is free.** You can learn how many people match an ICP, and
   what pulling them would cost, without spending anything.
2. **Every response reports what it actually cost.** Each tool returns a `cost`
   block containing the API's own `meta.amount_charged`, so an agent telling a
   human what it spent is quoting the biller, not guessing.

<Info>
  Requires MCP server **0.9.0 or newer** for resources, prompts and the
  vocabulary guard; the tools themselves work from 0.7.0. Remote users
  (`https://mcp.generect.com/mcp`) are always on the deployed version. Local
  users should run `npx generect-ultimate-mcp@latest`.
</Info>

## Free tools

| Tool | What it gives you |
| - | - |
| `count_leads` | How many leads match, plus the cost of the next step at **your** account's rates |
| `preview_leads` with `count_only: true` | A second opinion on the count from the Preview index. Free — and the two indexes do disagree, so it is worth asking both |
| `count_companies` | The same, for companies |
| `get_balance` | Balance and your real per-operation prices. `include_usage` adds spend broken down by operation; `include_token_analytics` adds per-API-token request counts, which answers "which integration is making these calls?" |
| `get_bulk_job` | Status and results of a bulk job (the work was billed at submit time) |
| `manage_webhooks` | Register, list, update, delete or test a webhook endpoint |
| `health` | Liveness and credential check — touches no data endpoint, safe for monitors |

## Billable tools

| Tool | Billed |
| - | - |
| `preview_leads` | \$0.002 per returned row — the cheapest way to see real people |
| `search_leads` | per returned row |
| `search_companies` | per returned row |
| `enrich_lead` / `get_lead_by_url` | per record found (not found is free) |
| `enrich_company` | per record found (not found is free) |
| `generate_email` | per **valid** email found (a miss is free) |
| `validate_email` | per email **submitted** — every address, whatever the verdict |
| `find_phone` | per phone found — the most expensive operation |
| `start_bulk_job` | per record, and the worst case is **reserved at submit time** |

Exact per-operation prices for your account are in
[billing settings](https://app.generect.com/settings/billing), and `get_balance`
returns them too. See [Pricing](/billing/pricing) for the list rates.

## Filter values are matched exactly — and two of them are not validated

This is the most expensive thing to get wrong, so it is worth stating plainly.
The search endpoints do **not** validate all filters the same way:

| Filter | An unknown value |
| - | - |
| `locations`, `company_headcounts`, `company_types` | rejected with `400`, naming the field |
| `company_industries`, `seniorities` | **accepted — 0 results, no charge, no error** |

`company_industries: ["Fintech"]` is not a LinkedIn industry, so it matches
nothing and you get a perfectly successful count of **zero**. That is
indistinguishable from a real empty audience, and it is how an agent ends up
telling a user "there is nobody like that" when the truth is "that is not the
name of an industry".

From 0.9.0 the MCP server checks these values before it sends anything:

* an unknown **industry**, headcount bucket or company type is refused locally,
  with the closest valid names — `Fintech` → `Financial Services`,
  `50-200` → `51-200`. Nothing is sent and nothing is charged;
* a value that is merely mis-spelled or mis-cased is **corrected**
  (`software development` → `Software Development`), because matching is exact;
* an unknown **seniority** or job function is a warning rather than a refusal:
  the engine does match loosely (`Owner` finds people even though the canonical
  label is `Owner / Partner`);
* `allow_unlisted_values: true` overrides the check, for the case where the API
  has gained a value the server's snapshot does not have yet.

### Resources

The vocabularies are exposed as MCP resources, so a client can read the exact
list once instead of guessing:

| Resource | Contents |
| - | - |
| `generect://vocabulary/industries` | all 434 industry names, each with its parent |
| `generect://vocabulary/seniorities` | canonical seniority labels |
| `generect://vocabulary/functions` | job functions (realtime only) |
| `generect://vocabulary/company-types` | company types |
| `generect://vocabulary/headcounts` | headcount buckets |
| `generect://vocabulary/follower-ranges` | follower buckets (realtime only) |
| `generect://account/pricing` | your real per-operation prices |
| `generect://account/balance` | balance and month-to-date usage |

Reading a resource is free and touches no data endpoint.

### Prompts

The server also ships workflow prompts, which appear as slash commands in
clients that support them: `size_an_audience`, `build_prospect_list`,
`enrich_my_list`, `spend_report`. Each starts from the free step.

## Spend ceiling

A row cap bounds how many results you get, not how much you pay — the per-row
price depends on the mode and your tier. So any call whose worst case exceeds the
server's per-call ceiling (default **\$5**, `MCP_MAX_SPEND_PER_CALL`) is refused
with the exact figure, and has to be repeated with `confirm_spend_usd` set to at
least that amount.

This is checked **before** `start_bulk_job` submits, because a bulk job reserves
its whole cost at submit time and cannot be called back.

## Database or realtime

Every search and enrich exists in two modes — cached `database` (sub-second,
cheaper, **free counts**, core filters) and live `realtime` (5–60s, pricier,
billable counts, every filter). See
[Database vs Real-time](/api-reference/database-vs-realtime).

Tools take a `mode` parameter:

| `mode` | Behaviour |
| - | - |
| `auto` (default) | Tries the cheap cached path. Escalates to realtime **only** if the API reports that a filter you passed does not exist there — and says so in the response. |
| `database` | Never escalates. An unsupported filter comes back as an error, not a larger bill. |
| `realtime` | Goes straight to the live index. |

Counting is deliberately stricter: a realtime count costs money, so `count_leads`
and `count_companies` never run one implicitly. If your filters need the live
index, the tool returns the blocking filter names and the price, and waits for
you to ask again with `mode: "realtime"`.

## The order to call things in

```text theme={null}
read generect://vocabulary/industries   free            → get the filter names exactly right
count_leads                             free            → is this audience big enough to be worth anything?
preview_leads                           $0.002/row      → who is actually in it? keep the ids that fit
search_leads                            per row         → pull only the rows you decided to keep
generate_email                          per valid email → contact details for those ids only
get_balance                             free            → report the exact spend back to the user
```

Records carry a stable `id` across preview, search and enrich, so once a lead is
in your list you never have to search for them again — pass the `id` to
`enrich_lead`, `generate_email` or `find_phone` directly.

<Tip>
  For repeatable or scheduled work, submit up to 50 records with `start_bulk_job`
  and register a webhook with `manage_webhooks` instead of polling. A submitted
  job runs to completion even if your balance later hits zero, because its cost
  was reserved at submit time — so only submit lists that have been approved.
</Tip>

## When to use the REST API instead

MCP is the right surface when a model is choosing what to fetch. Call the
[REST API](/api-reference/introduction) directly when you need something MCP
deliberately does not do:

* pulling more than 100 rows in one request
* pipelines with no model in the loop (nightly syncs, CRM backfills)
* your own retry, concurrency and storage policy


# Account managment
Source: https://docs.generect.com/use-cases/api/account-managment



### 1. Real-time credit balance monitoring

**Who it's for**

Platform integrators, finance teams, admins managing API spend.

**Problem**

Teams using API at scale need to monitor credit balance to avoid service interruption or overspend. No visibility = budget surprises.

**What Generect enables**

`GET /accounts/me/` returns current credit balance, monthly usage, and plan details, including whether Preview is currently free for you (`preview_tier`).

**How it works**

1. Call `GET /accounts/me/`
2. Check `credits.balance` and `credits.used_this_month`
3. Set alerts in your system when balance drops below threshold

**Input data**

API key (authentication)

**Outcome**

* Real-time credit balance visibility
* Proactive alerts before credits run out
* Clear plan and tier information

***

### 2. API usage analytics by operation type

**Who it's for**

Product managers, data ops, finance teams optimizing API costs.

**Problem**

Teams don't know which API operations consume most credits. Can't optimize spend without breakdown.

**What Generect enables**

`GET /accounts/usage/` returns credit breakdown by operation type: search (database/realtime), enrich, email find.

**How it works**

1. Call `GET /accounts/usage/`
2. See breakdown: how many credits spent on search vs enrich vs email
3. Identify most expensive operations
4. Optimize: switch from realtime to database where freshness isn't critical

**Input data**

API key, period

**Outcome**

* Full cost transparency by operation type
* Data-driven optimization of API usage
* Clear ROI per API feature

***

### 3. Transaction history for financial reporting

**Who it's for**

Finance teams, admins, compliance officers.

**Problem**

Need detailed transaction history for invoicing, auditing, and reconciliation. Current tools don't provide per-operation granularity.

**What Generect enables**

`GET /accounts/transactions/` returns every credit transaction with timestamp, type, amount, and details.

**How it works**

1. Call `GET /accounts/transactions/`
2. Get chronological list of all operations
3. Export for accounting or reconciliation

**Input data**

API key, optional date range

**Outcome**

* Complete audit trail of all API charges
* Per-operation detail for accounting
* Easy reconciliation with billing


# Automations and integrations
Source: https://docs.generect.com/use-cases/api/automations-and-integrations



### 1. AI agent automatically processes new leads end-to-end

**Who it's for**

AI agent developers, automation builders, sales ops teams.

**Problem**

Sales teams manually process inbound leads: check if they match ICP, find emails, add to CRM. This takes hours and doesn't scale.

**What Generect enables**

Generect API becomes a data layer for AI agents — agent pulls leads, scores them, gets emails, pushes to CRM without human involvement.

**How it works**

1. Agent triggers on new lead signal (form fill, signup, etc.)
2. Calls `POST /preview/leads/` to check ICP match
3. Calls `POST /email/find/` for qualified leads only
4. Pushes enriched contact to CRM via their API
5. Notifies sales team in Slack

**Input data**

ICP filters, lead\_id, CRM credentials

**Outcome**

* Fully automated lead qualification pipeline
* No manual research needed
* Sales team gets only pre-qualified, enriched leads

### 2. AI agent pre-screens leads before spending credits (Preview API)

**Who it's for**

AI agent developers, automation builders, no-code platforms.

**Problem**

AI agents processing large ICP queries spend credits on every lead — including irrelevant ones. No way to "pre-screen" before committing budget.

**What Generect enables**

Agent calls Preview to get a broad list, applies its own logic (scoring, deduplication, CRM matching), then enriches only the best matches.

**How it works**

1. Agent sends broad ICP to `POST /preview/leads/`
2. Gets 100+ masked leads for free
3. Agent scores leads by title + seniority + industry match
4. Enriches only top 10-20 via `POST /enrich/database/lead/`

**Input data**

ICP filters, lead\_id for enrichment

**Outcome**

* 5-10x lower spend per qualified lead
* Agent autonomy in lead qualification
* No wasted credits on irrelevant contacts

### 3. No-code automation: new signup → enrichment → CRM

**Who it's for**

Growth teams, marketers, ops teams using Make, n8n, Zapier.

**Problem**

When a new user signs up, teams manually look them up to understand who they are. Slow, inconsistent, doesn't scale.

**What Generect enables**

Connect Generect to your automation platform via API. New signup triggers enrichment — and full profile lands in CRM automatically.

**How it works**

1. Trigger: new signup in your product
2. Make/n8n calls `POST /enrich/database/lead/` with email
3. Gets full profile: title, company, seniority, industry
4. Updates CRM record automatically
5. Routes to right sales rep based on company size

**Input data**

Email from signup form

**Outcome**

* Every new signup enriched in seconds
* CRM always up to date
* Automatic lead routing and scoring

### 4. Generect as a data source for outreach platforms

**Who it's for**

Outbound agencies, SDR teams using Instantly, Lemlist, Apollo, Smartlead.

**Problem**

Outreach platforms need fresh, verified lead lists. Teams manually export/import data between tools — error-prone and time-consuming.

**What Generect enables**

Build a pipeline: Generect API pulls targeted leads → validates emails → exports directly into your outreach tool via their API.

**How it works**

1. Call `POST /search/database/leads/` with ICP
2. Bulk validate emails via `POST /email/validate/`
3. Filter valid contacts
4. Push to outreach platform via their API
5. Launch campaign

**Input data**

ICP filters, outreach platform API credentials

**Outcome**

* Fresh, verified leads flowing directly into campaigns
* No manual CSV exports
* Higher deliverability from pre-validated emails

### 5. Enrich CRM contacts with phone numbers for Customer Success

**Who it's for**

Customer success teams, account managers.

**Problem**

Existing CRM contacts lack phone numbers. CS teams need direct lines for renewals and upsells but don't want to pay for numbers that can't be found.

**What Generect enables**

Use existing `lead_id` or name + company from CRM to find phone numbers. Only pay for successful lookups.

**How it works**

1. Export contacts from CRM
2. For each contact, call `POST /phone/find/` with available identifiers
3. Update CRM with found numbers
4. Zero cost for contacts where phone was not found

**Input data**

`lead_id`, or `first_name` + `last_name` + company

**Outcome**

* Enriched CRM with direct phone numbers
* Better reach rates for CS calls
* Cost-effective — no payment for missing data

### 6. Get notified when async jobs complete (Webhooks API)

**Who it's for**

Data ops teams, SaaS platforms, automation builders, and backend teams running bulk jobs.

**Problem**

Polling every bulk job wastes requests and adds delay. Teams need their systems to react as soon as a bulk job finishes.

**What Generect enables**

Register a webhook endpoint and receive async notifications when bulk email, bulk phone, or enrich jobs complete.

**How it works**

1. Register your endpoint with `POST /webhooks/`
2. Subscribe to events such as `email.find.bulk.completed` or `phone.find.bulk.completed`
3. Verify incoming requests with the webhook signature
4. Process completed job results in your system

**Input data**

Webhook URL, event list, and signing secret

**Outcome**

* No polling loops for async jobs
* Faster downstream automations
* Secure delivery with request signatures


# Bulk processing
Source: https://docs.generect.com/use-cases/api/bulk-processing



## How bulk jobs behave

All bulk endpoints (enrich, email find, phone find) share the same async contract:

1. **Submit** up to **50 items** per request. The response is `202 Accepted` with a `job_id` (a 51st item is rejected with `400`).
2. **Track** the job by polling `GET .../{job_id}/`, or [register a webhook](/api-reference/endpoint/webhooks/overview) to receive the results when it finishes.
3. `meta.status` moves through `pending` → `processing` → `completed` (or `error` on failure). **`data` stays `null` until `status` is `completed`** — poll on the status, not the body.
4. **Results are 1:1 with your input, in the same order.** An item we couldn't resolve is **returned with its profile set to `null`** (never dropped), so you can line results back up to inputs by position.
5. **Not-found items are not charged.** Credits are reserved for the whole batch on submit and the unfound ones are refunded — you pay only for results returned. The webhook payload's `meta` also reports `found` and `not_found` counts.

<Note>Jobs are retained for **24 hours**; after that the status endpoint returns `404`.</Note>

***

### 1. Bulk lead search by ICP from cached database (Search API - Database)

**Who it's for**

SDR teams, growth hackers, outbound agencies doing high-volume prospecting.

**Problem**

Teams need large lead lists fast and cheap. Realtime search is slow and expensive when freshness isn't critical — they just need volume.

**What Generect enables**

`/search/database/leads/` returns full lead data, including `linkedin_url` and company domain, from Generect's cached database — 10x cheaper and near-instant.

**How it works**

1. Define ICP: roles, industries, headcount, locations
2. Call `POST /search/database/leads/`
3. Get full lead profiles in \<1 sec
4. Export to CRM or outreach tool

**Input data**

Job titles, seniorities, locations, company industries, company headcount

**Outcome**

* Large lead lists at 0.2-0.1 credit/result
* Sub-second response time
* Full data including linkedin\_url and company domain

### 2. Bulk email find для large lists (Email API)

**Who it's for**

Outbound agencies, growth teams with large lead lists, data ops.

**Problem**

Finding emails one by one for 10K+ leads is too slow. Teams need async bulk processing with job tracking.

**What Generect enables**

`/email/find/bulk/` processes thousands of leads asynchronously. Check status via `job_id`.

**How it works**

1. Submit list of `lead_id` values or name+domain pairs to `POST /email/find/bulk/`
2. Get `job_id`
3. Either poll `GET /email/find/bulk/{job_id}/` for status, **or** [register a webhook](/api-reference/endpoint/webhooks/overview) once and we'll `POST` the full results to your callback URL when the job finishes — no polling
4. Use the results when complete

**Input data**

Array of lead\_id or first\_name + last\_name + domain

**Outcome**

* Process thousands of leads in one request
* Async with job tracking
* Focus on real, verified emails

### 3. Email list validation before sending (Email API)

**Who it's for**

Email marketers, outbound teams, anyone sending bulk emails.

**Problem**

Sending to invalid emails kills deliverability and sender reputation. Teams need to validate before sending.

**What Generect enables**
`/email/validate/` checks deliverability, catch-all, disposable, and risk score.

**How it works**

1. Submit email list to `POST /email/validate/`
2. Get per-email status: `VALID`, `RISKY`, `CATCH\_ALL`, `INVALID`
3. Filter out risky/invalid before sending

**Input data**

Array of email addresses

**Outcome**

* Protect sender reputation
* Reduce bounce rate
* Clear risk scoring per email

### 4. Bulk phone find for teams with large contact lists (Phone API)

**Who it's for**

Call centers, outbound agencies, sales teams scaling phone outreach.

**Problem**

Finding phones one by one doesn't scale. Need async bulk processing for large lists.

**What Generect enables**

`/phone/find/bulk/` submits thousands of leads and returns results asynchronously.

**How it works**

1. Submit lead list to `POST /phone/find/bulk/`
2. Get `job_id`
3. Either poll `GET /phone/find/bulk/{job_id}/`, **or** [register a webhook](/api-reference/endpoint/webhooks/overview) once and we'll `POST` the full results to your callback URL when the job finishes — no polling
4. Pay only per found phone

**Input data**

Array of `lead_id` values or name + company pairs

**Outcome**

* Scale phone prospecting to thousands
* Async processing with tracking
* "No Data, No Charge" per result


# Data discovery
Source: https://docs.generect.com/use-cases/api/data-discovery



### 1. SaaS platform displays search results to users for \$0.002 a result (Preview API)

**Who it's for**

SaaS platforms (Clay, n8n, AI SDR tools), developers building lead discovery features.

**Problem**

SaaS platforms want to show search results to their users, but paying the full enrichment price for every displayed lead — before the user decides to buy contact data — makes "browse → decide → reveal" flows too expensive to build.

**What Generect enables**

Preview API returns masked cached lead data, such as name, title, company, location, industry, and seniority, with a unique lead ID. Browsing costs \$0.002 per lead shown — a tenth of the database enrichment price — and the full price is paid only when a user reveals a profile or contact data.

**How it works**

1. Your app sends ICP filters to `POST /preview/leads/`
2. Generect returns masked cached data: name, title, company, location, industry, seniority, and lead ID
3. Your users browse and select leads
4. Call `POST /enrich/database/lead/` with `id` for selected leads
5. Pay \$0.002 per lead shown in step 2, and the enrichment price only for the ones your users select

**Input data**

Job titles, seniorities, locations, company industries, company headcount

**Outcome**

* Cheaper browsing for end users (cached data)
* Pay only for actionable data (email, phone, or full profile)
* Higher conversion from "browse" to "purchase"

### 3. Real-time lead search with advanced filters (Search API - Realtime)

**Who it's for**

Account-based sales teams, recruiters, enterprise sales targeting niche personas.

**Problem**

Cached data may be outdated or lack granular filters. Teams targeting specific personas (e.g., "VP Engineering who changed jobs in last 6 months at Series B startups") need realtime LinkedIn-grade filtering.

**What Generect enables**

`/search/realtime/leads/` searches live data with advanced filters: keywords, past companies, schools, years in position, functions.

**How it works**

1. Define precise ICP with advanced filters
2. Call `POST /search/realtime/leads/`
3. Get fresh, highly-targeted results (5-60 sec)
4. Use for personalized outreach

**Input data**

All database filters + keywords, personas, past companies, schools, groups, years in position, functions

**Outcome**

* Up-to-date lead data
* Hyper-targeted lists for ABM campaigns
* Advanced filters not available in database mode

### 4. Find companies and their contacts in a single request (Search API)

**Who it's for**

B2B sales teams, partnerships managers, investors doing market mapping.

**Problem**

Teams need both company and decision-maker data in one flow. Currently requires two separate searches and manual matching.

**What Generect enables**

`/search/database/company-leads/` or `POST /search/realtime/company-leads/` returns companies matching your ICP together with their key contacts in a single request.

**How it works**

1. Define company ICP: industry, headcount, location
2. Add lead filters: target roles, seniority
3. Call `POST /search/database/company-leads/`
4. Get matched companies with their relevant contacts

**Input data**

Company filters (industry, headcount, location, type) + lead filters (roles, seniority)

**Outcome**

* Company + contact data in one call
* No manual matching needed
* Faster account-based prospecting

### 5. Quickly estimate audience size before launching a campaign (Preview API)

**Who it's for**

Marketing teams, growth leads, campaign managers.

**Problem**

Before launching an outbound campaign, teams need to know: "How many leads match this ICP?" Without a free count, they either guess or pay to find out.

**What Generect enables**

`POST /preview/leads/count/` returns the total number of matching leads — always free.

**How it works**

1. Define ICP filters
2. Call `POST /preview/leads/count/`
3. Get total count instantly, no charge
4. Adjust filters until the audience size is right
5. Proceed to search/enrich

**Input data**

Job titles, seniorities, locations, industries, headcount

**Outcome**

* Free audience sizing before any spend
* Better campaign planning and budget estimation
* Faster ICP iteration


# Data enrichment
Source: https://docs.generect.com/use-cases/api/data-enrichment



### 1. Reveal full lead profile after Preview (Enrich API)

**Who it's for**

SaaS platforms, AI agents, sales teams who use Preview → Enrich flow.

**Problem**

After browsing leads via Preview, teams need full profiles (linkedin, work history, skills) before outreach. They need a simple way to "unlock" a lead.

**What Generect enables**

One endpoint, multiple input options: Generect ID, LinkedIn URL, or email. No data found = no charge.

**How it works**

1. Take lead\_id from Preview results
2. Call `POST /enrich/database/lead/` or `POST /enrich/realtime/lead/`
3. Get full profile: linkedin\_url, work history, education, skills, company details
4. If lead not found — 0 credits charged

**Input data**

Generect ID, OR LinkedIn URL, OR email (reverse lookup)

**Outcome**

* Full lead profile with work history and skills
* Flexible input — use whatever identifier you have
* "No Data, No Charge" — zero risk

### 2. Reverse email lookup — find a person by email (Enrich API)

**Who it's for**

Sales teams, customer success, recruiters who have an email but need full context.

**Problem**

You received an inbound email or have a list of emails — but don't know who these people are, their role, company size, or seniority.

**What Generect enables**

`/enrich/realtime/lead/` accepts email as input and returns the full lead profile via reverse lookup.

**How it works**

1. Call `POST /enrich/realtime/lead/` with:
   ```json theme={null}
   {
     "email": "jordan.ellis@microsoft.com"
   }
   ```
2. Get full profile: name, title, company, LinkedIn, work history
3. If not found — 0 credits

**Input data**

Email address

**Outcome**

* Full context on any email contact
* Better lead qualification for inbound
* Enrich existing email lists with profile data

### 3. Enrich company data by domain or name (Enrich API)

**Who it's for**

CRM admins, data ops teams, marketing automation builders.

**Problem**

CRM records often have just a company name or domain. Teams need full company data (industry, headcount, LinkedIn page) for segmentation and routing.

**What Generect enables**

`/enrich/database/company/` or `/enrich/realtime/company/` accepts domain, name, LinkedIn URL, or internal ID — returns full company profile.

**How it works**

1. Pass company domain (e.g., `microsoft.com`) to `POST /enrich/database/company/`
2. Get full profile: industry, headcount, location, LinkedIn URL, website
3. Update CRM record automatically

**Input data**

Domain, OR company name, OR LinkedIn URL, OR internal id

**Outcome**

* Complete company profiles for CRM enrichment
* Multiple input options for flexibility
* Automated data hygiene

### 4. Find a work email after Preview (Email API)

**Who it's for**

SDR teams, outbound automation, AI sales agents.

**Problem**

You found the right lead via Preview or Search — now you need their email for outreach.

**What Generect enables**

`/email/find/` gets an email by `lead_id` from Preview/Search or by `first_name` + `last_name` + `domain`.

**How it works**

1. Take the lead ID from Preview/Search results
2. Call `POST /email/find/` with:
   ```json theme={null}
   {
     "lead_id": "ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9"
   }
   ```
3. Get verified email with confidence score

**Input data**

`lead_id`, or `first_name` + `last_name` + `domain`

**Outcome**

* Verified work email with deliverability check
* "No Data, No Charge" — pay only for results
* Confidence score and catch-all detection included

### 5. Find mobile number for cold calling (Phone API)

**Who it's for**

Inside sales, BDR teams, call centers.

**Problem**

Email outreach has low response rates. Direct phone contact converts better, but finding verified mobile numbers is hard and expensive.

**What Generect enables**

`/phone/find/` finds a phone by `lead_id` or by name + company. Credits are charged only when a phone is found.

**How it works**

1. Call `POST /phone/find/` with `lead_id` or name + company
2. Get phone number with type, country, and status
3. Not found? No charge.

**Input data**

`lead_id`, or `first_name` + `last_name` + company

**Outcome**

* Verified phone numbers for direct outreach
* Mobile vs office type detection
* Zero-risk pricing model


# Account Sourcing
Source: https://docs.generect.com/use-cases/mcp/account-sourcing



**Who it's for**

Sales teams building pipeline based on ICP. Business analysts conducting market research. Partnership managers looking for potential partners. Investors screening companies.

**Problem**

Finding companies that truly match your ICP is difficult. Generic databases often contain outdated data and lack precise filtering by company size or industry. Manual research across multiple sources is inefficient and incomplete.

**What Generect enables**

Through MCP, an AI agent can identify companies based on precise ICP parameters — industry, size, location — and return structured, up-to-date data including company name, domain, employee count, and headquarters.

**How it works**

1. The user defines criteria: "Find 20 fintech companies in the US with 50-200 employees”
2. The AI sends filters via MCP to the Generect API
3. Generect searches across its database using up-to-date data
4. The AI returns a structured list of companies with key metrics
5. Results are ready for CRM import or further enrichment

**Input data**

* Industry (e.g. "Fintech”)
* Location / region (e.g. "US”)
* Company size (e.g. 50-200 employees)
* Additional filters: revenue range, funding stage, technologies

**Outcome**

* Targeted list of companies matching your ICP
* Data includes: company name, industry, employee count, HQ, domain
* Faster market segmentation for strategic decision-making
* More efficient pipeline — fewer cold companies, more relevant prospects


# Email Generation
Source: https://docs.generect.com/use-cases/mcp/email-generation



**Who it's for**

SDRs and sales reps preparing cold outreach. Marketing teams running email campaigns. Recruiters who need direct contact with candidates. Anyone who knows a person's name and company but doesn't have their email.

**Problem**

You know who you want to reach out to, but you don't have their email. Manually searching for contacts is time-consuming, and guessing email formats is unreliable. Invalid emails lead to high bounce rates and damage your domain reputation.

**What Generect enables**

Through MCP, an AI agent generates the most likely email address based on company-specific patterns. Generect analyzes email formats within the organization and returns a predicted address — ready for verification and outreach.

**How it works**

1. The user submits a request: "Generate a professional email address for Olivia Brown from Stripe”
2. The AI sends the name and company via MCP to the Generect API
3. Generect analyzes company email patterns (e.g. first.last@, f.last@, etc.)
4. Returns the most likely email address
5. Optionally, the email can be verified before use

**Input data**

* Full name of the contact (e.g. "Olivia Brown”)
* Company name or domain (e.g. "Stripe” or "stripe.com”)

**Outcome**

* Email generated based on real company patterns
* Ready for verification and cold outreach
* Lower bounce rates compared to manual guessing
* Scalable — generate emails for hundreds of contacts in minutes


# Profile Lookup
Source: https://docs.generect.com/use-cases/mcp/profile-lookup



**Who it's for**

HR teams and recruiters evaluating candidates. Sales teams qualifying leads before outreach. Account managers building relationship intelligence. Marketing teams personalizing communication.

**Problem**

LinkedIn profiles contain a lot of information, but analyzing them manually is slow. Reviewing 50 candidates or leads can take hours. What’s needed is not just raw data, but insights — whether the person is a good fit, their strengths, and how to personalize communication.

**What Generect enables**

Through MCP, an AI agent analyzes a LinkedIn profile and returns structured insights — including experience, skills, and key highlights. Instead of scrolling through profiles, you get a ready-to-use summary tailored to your use case (hiring, sales, partnerships).

**How it works**

1. The user provides a LinkedIn URL: "Analyze this LinkedIn profile: linkedin.com/in/sophiawright”
2. The AI sends the URL via MCP to the Generect API
3. Generect parses and structures profile data
4. The AI analyzes the data and generates insights based on the user’s goal (hiring / sales / research)
5. Returns a summary with key highlights and recommendations

**Input data**

* LinkedIn profile URL (e.g. "[https://www.linkedin.com/in/sophiawright”](https://www.linkedin.com/in/sophiawright”))
* Optional: context (hiring, sales qualification, research)

**Outcome**

* Structured profile analysis: experience, skills, background
* Key insights tailored to the use case (hiring, lead qualification)
* Personalized outreach based on real profile data
* Reduced screening time from 10–15 minutes to seconds per profile


# Target prospects
Source: https://docs.generect.com/use-cases/mcp/target-prospects



**Who it's for**

Sales teams, SDRs, and growth marketers at B2B SaaS companies. Recruiters sourcing candidates based on specific criteria. Marketers building targeted outreach lists.

**Problem**

Manual lead search across LinkedIn and other sources takes hours. Data quickly becomes outdated, contacts are often unverified, and building a list of 50+ leads turns into repetitive manual work. Existing tools require copy-paste workflows or complex integrations.

**What Generect enables**

Through MCP integration, an AI agent can retrieve verified B2B leads with full profiles from a single prompt — including name, job title, company, location, and LinkedIn URL. No manual search, no tab switching.

**How it works**

1. The user sends a prompt to an AI agent: "Find 10 growth marketing managers in Berlin working at SaaS companies”
2. The AI sends a request via MCP to the Generect API with filters (role, location, industry)
3. Generect searches and verifies contacts in real time
4. The AI returns a structured list of leads
5. Results can be exported to a CRM or outreach tool

**Input data**

* Job title / role (e.g. "Growth Marketing Manager”)
* Location (e.g. "Berlin”)
* Industry / company type (e.g. "SaaS”)
* Number of results
* Additional filters: company size, revenue, tech stack

**Outcome**

* Ready-to-use list of verified leads in seconds
* Full profiles: name, title, company, location, LinkedIn URL
* Prospecting time reduced from hours to minutes
* Higher conversion rates through precise targeting


# Company search
Source: https://docs.generect.com/use-cases/saas/company-search



# Discovering companies that match ICP

**Who it's for**

Sales teams, founders, business development, strategy.

**Problem**

Teams often don't have a clear list of companies to target. ICP exists "in theory” but not as real data:

* hard to define which companies are actually relevant
* difficult to scale across a team
* unclear where to focus sales efforts

**What Generect enables**

Company Search allows you to turn an abstract ICP into a concrete, data-backed and verifiable list of companies to target.

**How it works**

You define your ICP at the company level: industries, size, locations, and other attributes
Generect generates a list of companies that match these criteria
You analyze results, refine filters, and see the real structure of your target market
You use this list as a foundation for lead search or account-based sales

**Input data**

* industries
* company size
* geography
* additional company attributes

**Outcome**

* clear list of target companies
* transparent understanding of your actual ICP
* foundation for systematic sales and growth

***

# Market and segment analysis

**Who it's for**

Founders, leadership, strategy, growth teams.

**Problem**

Market decisions are often made intuitively without real data:

* how many companies exist in a segment
* where they are located
* which segments are worth focusing on

**What Generect enables**

Generect allows you to explore markets through real companies and their data, not abstract reports.

**How it works**

You define segment parameters (industry, size, region, etc.)
You get a list of companies in that segment
You compare different segments by adjusting criteria
You identify where most potential customers are and which segments have the highest potential

**Input data**

* segment parameters
* geography
* company attributes

**Outcome**

* realistic view of market size and structure
* data-driven strategic decisions
* clear priorities for sales and marketing

***

# Identifying new accounts for expansion

**Who it's for**

Sales leadership, growth teams, business development.

**Problem**

When entering new markets or verticals, it's hard to quickly understand:

* which companies to target
* where to start
* how to avoid chaotic account discovery

**What Generect enables**

Company Search helps quickly build a list of new accounts for expansion.

**How it works**

You define criteria for a new market or vertical
Generect finds companies that match these criteria
You get a structured list of accounts
Sales teams use this list to systematically enter a new segment

**Input data**

* new market criteria
* company attributes
* regions or industries

**Outcome**

* faster entry into new markets
* clear list of target accounts without manual research
* controlled and structured scaling process


# Find Contacts
Source: https://docs.generect.com/use-cases/saas/find-contacts



# Finding verified work emails for outbound campaigns

**Who it's for**

Marketing teams, sales teams, growth teams.

**Problem**

Outbound campaigns fail because:

* emails are outdated or incorrect
* bounce rates increase
* manual verification takes time

**What Generect enables**

Generect allows you to find and verify corporate emails before outreach.

**How it works**

You upload a list or use existing leads
Generect finds emails based on name and domain
Emails are validated instantly
Risky or invalid emails are filtered out

**Input data**

* full name
* company or domain
* contact list (optional)

**Outcome**

* lower bounce rates
* protected sender reputation
* higher response rates
* faster campaign launch

***

# Completing contact profiles with missing email data

**Who it's for**

Sales ops, RevOps, marketing teams.

**Problem**

CRM data is incomplete and lacks emails.

**What Generect enables**

Generect enriches contact profiles with corporate emails.

**How it works**

You select contacts
Run email search
Emails are validated
Profiles are updated

**Input data**

* contact profiles
* full name
* company

**Outcome**

* more usable contacts
* less manual work
* complete profiles
* outreach-ready data

***

# Finding direct phone numbers for high-value leads

**Who it's for**

Recruiting teams, sales teams working with high-value leads.

**Problem**

Email is not always effective. Finding phone numbers manually is slow and unreliable.

**What Generect enables**

Generect allows you to find direct phone numbers for faster contact.

**How it works**

You work with contacts
Generect finds phone numbers
Numbers are returned only if available
You pay only for successful results

**Input data**

* full name
* company or LinkedIn

**Outcome**

* faster contact
* fewer delays
* direct communication channel
* pay only for results

***

# Enabling multi-channel outreach (email + phone)

**Who it's for**

Sales teams, SDR, recruiters, growth teams.

**Problem**

Using only one channel reduces response rates. Teams often lack full contact data.

**What Generect enables**

Generect provides both emails and phone numbers for multi-channel outreach.

**How it works**

You upload or find contacts
Generect finds emails and phone numbers
Emails are validated
Contacts are ready for outreach

**Input data**

* full name
* company or domain
* LinkedIn (optional)

**Outcome**

* higher response rates
* faster contact
* flexible outreach strategies
* ready-to-use contact data

***

# Finding emails from LinkedIn URL

**Who it's for**

Sales teams, SDR, marketing, growth teams using LinkedIn or Sales Navigator.

**Problem**

Teams have LinkedIn profiles but no contact data. Manual search is slow and unreliable.

**What Generect enables**

Generect converts LinkedIn profiles into verified corporate emails.

**How it works**

You add LinkedIn URLs
Generect identifies the person and company
Email is generated
Email is validated
Invalid emails are filtered out

**Input data**

* LinkedIn URL or list
* optional filters

**Outcome**

* LinkedIn profiles converted into verified emails
* faster outreach preparation
* less manual work
* ready-to-use leads


# Introduction
Source: https://docs.generect.com/use-cases/saas/introduction



Generect designed to deliver fast search, analysis, and preparation of B2B leads and companies for real outreach.\
The following pages are describe the main use cases that will help you understand how the platform solves your needs.


# Lead search
Source: https://docs.generect.com/use-cases/saas/lead-search

How Customer Success teams keep CRM data up-to-date with Generect

# Finding target leads based on ICP

**Who it's for**

Sales teams, SDR, marketing, founders, growth teams.

**Problem**

Most teams spend hours on manual research to find the "right” contacts. As a result:

* leads don't match the ICP
* outreach efforts are ineffective
* teams work with noise instead of focus

**What Generect enables**

Generect allows you to build lead search based on your Ideal Customer Profile and work only with a relevant audience.

**How it works**

You define your ICP: roles, industries, company size, locations, and other attributes
You run a lead search
You get a list of contacts that match your criteria
You start working with leads without additional cleaning

**Input data**

* roles and/or personas
* industry
* company size
* location
* additional filters such as data freshness or number of contacts per company

**Outcome**

* clearly focused list of leads
* less noise, more replies
* clear understanding of who to target right now

***

# Leads by domain / website

**Who it's for**

Account-based sales, founders, sales managers.

**Problem**

You already know which companies you want to work with, but you don't have contacts within those companies or the data is outdated.

**What Generect enables**

Generect allows you to find contacts of people working at specific companies using a domain or website as a starting point.

**How it works**

You enter a domain or a list of company websites
You choose who you are looking for (role, location)
You get relevant contacts within those companies

**Input data**

* domain or list of domains
* roles / personas
* location or other filters (optional)

**Outcome**

* direct access to decision-makers
* ideal for account-based sales
* less guesswork, more accuracy

***

# Speeding up SDR workflows with personas

**Who it's for**

SDR, sales managers, teams with a high volume of searches.

**Problem**

SDRs repeatedly set up the same filters, wasting time and making mistakes.

**What Generect enables**

Personas allow you to save typical role configurations and reuse them in any search.

**How it works**

A persona is created (for example, "Sales Leadership”)
SDR selects a persona instead of manually setting filters
The search is launched instantly

**Input data**

* functions
* seniority
* keywords (include / exclude)

**Outcome**

* faster search
* consistent team standards
* fewer human errors

***

# Refreshing and cleaning searches with exclude lists

**Who it's for**

Sales, RevOps, marketing.

**Problem**

Teams repeatedly contact:

* existing customers
* already processed leads
* irrelevant or "no-go” accounts

**What Generect enables**

Exclude lists allow you to automatically remove unwanted contacts and companies from search results.

**How it works**

You create an exclude list (CRM customers, competitors, etc.)
You apply it to your search
You work only with relevant data

**Input data**

* lists of contacts or companies
* exclusion rules

**Outcome**

* clean lists
* reduced risks
* more professional outreach

***

# Monitoring new leads in target segments

**Who it's for**
Sales teams, SDR, growth teams, and founders tracking dynamic markets.

**Problem**
New potential leads constantly appear as people change roles, join new companies, or enter your target segment.
Without continuous monitoring:

* teams miss fresh opportunities
* outreach happens too late
* competitors reach leads first

**What Generect enables**
Generect allows you to continuously monitor your target segments and identify new leads as they appear.

**How it works**

1. You define your ICP and target segment
2. Generect continuously updates data within that segment
3. New matching leads are identified automatically
4. You review and act on fresh leads without running new searches from scratch

**Input data**

* ICP criteria
* segment filters (industry, roles, location, etc.)

**Outcome**

* continuous flow of new leads
* faster response to market changes
* higher chances to reach prospects early
* more proactive outbound strategy


# Verify emails
Source: https://docs.generect.com/use-cases/saas/verify-emails



# Verify emails before sending campaigns

**Who it's for**

Marketing Ops teams before outbound campaigns, SDR/BDR teams preparing cold outreach, RevOps teams working with CRM and email campaigns.

**Problem**

Outbound campaigns often perform poorly because:

* email addresses are outdated, invalid, or incorrect
* higher risk of spam placement and domain damage
* teams spend time manually verifying emails before campaigns

**What Generect enables**

Generect allows you to verify email addresses before sending outbound campaigns to filter out invalid and risky contacts, reduce bounce rates, and protect sender reputation.

**How it works**

You upload an email or a list of contacts before launching a campaign
Generect instantly checks deliverability for each address
The system assigns a status (valid / invalid / risky)
Invalid and risky emails are excluded or separated

**Input data**

* email address or list of emails
* segment or company (optional)

**Outcome**

* lower bounce rates
* protected sender reputation
* higher deliverability and response rates
* faster campaign launch without manual checks

***

# Detect fake, risky, or non-corporate emails

**Who it's for**

Agencies and lead generation teams working with large datasets, RevOps and CRM owners responsible for data quality, SDR/BDR teams before cold outreach.

**Problem**

Outbound campaigns often include emails that appear valid but are:

* fake or temporary
* personal or non-corporate domains
* reducing campaign effectiveness

**What Generect enables**

Generect allows you to detect fake, risky, and non-corporate emails before launching campaigns.

**How it works**

You upload emails or a list of contacts
Generect analyzes domain type and email patterns
The system assigns a status (valid / risky / fake)
Fake, risky, and non-corporate emails are filtered out

**Input data**

* email address or list of emails
* contact list (optional)

**Outcome**

* cleaner, corporate-only email lists
* lower bounce and spam risks
* more relevant campaigns
* higher response rates

***

# Process large contact lists in bulk

**Who it's for**

Lead generation agencies, teams running large outbound campaigns, sales teams.

**Problem**

Working with large contact lists is difficult because:

* no efficient way to validate emails at scale
* manual verification takes too long
* campaigns are launched with unclean data

**What Generect enables**

Generect allows bulk validation of large email lists to quickly prepare clean, campaign-ready data.

**How it works**

You upload a file (CSV or XLSX)
Generect processes each email
The system assigns a status (valid / invalid / risky)
Results are available for review and export
Invalid and risky emails can be excluded

**Input data**

* file with email list (CSV / XLSX)
* contact list or database

**Outcome**

* fast validation at scale
* clean, structured email databases
* lower bounce rates
* protected sender reputation
* time saved

***

# Continuous email validation for growing databases

**Who it's for**

Sales teams with long deal cycles, companies with large CRM databases, CRM owners.

**Problem**

Contact data quickly becomes outdated:

* people change roles or companies
* emails become inactive
* CRM accumulates outdated contacts
* manual checks don't scale

**What Generect enables**

Generect allows ongoing validation of emails in growing databases.

**How it works**

You periodically upload updated contact lists
Generect checks the current status of each email
The system identifies invalid or risky contacts
Results are used to update CRM or exclude contacts

**Input data**

* email data from CRM or internal database
* contact lists or segments
* file or export (CSV / XLSX)

**Outcome**

* up-to-date contact data
* cleaner CRM
* no manual checks
* stable sender reputation