# Contact Evidence Enricher (`forlab/contact-evidence-enricher`) Actor

Enrich your company list with public contact details from each website: emails, phones, social profiles and addresses, each with its source page. Every row comes back unchanged; misses get a plain reason. $0.003 per site.

- **URL**: https://apify.com/forlab/contact-evidence-enricher.md
- **Developed by:** [ForLab Digital](https://apify.com/forlab) (community)
- **Categories:** Lead generation, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 site checks

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Contact Evidence Enricher

Send a list of companies with their websites. Get every row back, unchanged and in the same order, with the public contact details found on each site: emails, phone numbers, social profiles (LinkedIn, Instagram, Facebook, X, YouTube, TikTok) and postal addresses. Every contact comes with the page it was found on, so you can check it.

- **Your data stays intact.** Your columns are kept as they are; new fields go under `enrichment`.
- **Evidence, not guesses.** Each email or phone has a `source_url` and the `method` it was read with. No guessed addresses, no pattern-generated emails.
- **A reason for every miss.** A site with no result gets a plain-language `note`: bot protection, robots.txt, a redirect to another domain, or no contact on the pages read.
- **Pay per site checked.** $0.003 per website, with a hard cost limit per run. An optional paid Google search finds emails for sites that block crawlers.

### Input

Supply exactly one of `records` (a JSON array of objects) or `csvText` (CSV with a header row):

```json
{
  "records": [
    {"lead_id": "A-001", "company": "Example Ltd", "website": "https://example.com"}
  ],
  "websiteField": "website",
  "requiredContact": "any",
  "maxPagesPerSite": 3,
  "concurrency": 2,
  "searchFallback": false
}
```

- `websiteField`: the column that holds the website. Values without a scheme use HTTPS.
- `requiredContact`: which contact makes a site count as found. `any` (an email, a phone or a social profile; the default), `either` (an email or a phone), `email` or `phone`. Every contact type found is returned in all modes.
- `maxPagesPerSite`: 1–5 page attempts per site (the home page plus likely contact pages). Robots.txt requests and redirect hops are extra requests.
- `concurrency`: 1–4 sites crawled at once.
- `searchFallback`: off by default; see "Paid search fallback".
- Limits: 1–200 records and 2 MiB input per run.

### Output

Each input record produces one dataset item in the original order. The original JSON values are kept under `input`, the zero-based position is `row_index`, and new fields are under `enrichment`:

```json
{
  "row_index": 0,
  "input": {"lead_id": "A-001", "company": "Example Ltd", "website": "https://example.com"},
  "enrichment": {
    "site": "https://example.com/",
    "status": "contact_evidence_found",
    "requested_contact_evidence_found": true,
    "emails": [{"value": "info@example.com", "source_url": "https://example.com/contact", "method": "mailto", "domain_matches_site": true}],
    "phones": [{"value": "+441234567890", "source_url": "https://example.com/contact", "method": "tel"}],
    "socials": [{"platform": "linkedin", "url": "https://www.linkedin.com/company/example", "source_url": "https://example.com/", "method": "link"}],
    "addresses": [],
    "pages": ["https://example.com/", "https://example.com/contact"],
    "errors": [],
    "ownership_verified": false,
    "mailbox_verified": false,
    "charged": true
  }
}
```

The values above are illustrative. The run also writes a summary to the key-value store `OUTPUT` record. Use the JSON output when you need the exact original values; Apify's CSV and Excel exports flatten nested fields.

#### What each field means

- `emails` and `phones`: `value`, `source_url` and `method` (`mailto`, `tel`, `visible_text` or `json_ld`). A contact found on several pages appears once per page, each with its own `source_url`. Phones come only from `tel:` links and schema.org `telephone`; no country code is inferred.
- `domain_matches_site` on each email: true when its domain equals the site's domain (ignoring `www.`) or is a subdomain of it. Use it as a filter; parent-company, registered e-mail (KEP) and agency addresses come back as false.
- `socials`: profile links found in page links or JSON-LD `sameAs`, each with `platform`, `url`, `source_url` and `method`. Share buttons and single posts are dropped.
- `addresses`: postal addresses from JSON-LD `address` (with `parts` and, when given, `geo`) or `<address>` elements. Free text is never parsed as an address.
- `status` and `note`: why a site gave no result. `no_requested_contact`, `robots_denied`, `robots_unavailable`, `fetch_failed`, `redirected_to_other_site` (the new address is in `errors[].redirect_to`), `crawl_delay_exceeds_limit`, `deadline_exceeded`, `internal_error`, `charge_limit_reached`, and `missing_website` or `invalid_url` for a row without a usable website. When the site answered 401, 403 or 429, the note says it blocks automated visitors.
- `charged`: whether this row's site was billed.

A source URL means the text appeared on that page. It does not prove that the contact belongs to the company, that the mailbox works, or that the company agreed to be contacted. Check the evidence before outreach.

#### Run summary (`OUTPUT` record)

`status_counts` per site status, `sites_blocked` (sites that answered 401, 403 or 429), `search_fallback` (`off`, `done` with `searched_sites` and `sites_found`, `skipped`, or `failed`), `charged_events` and `billing_mode` (`pay_per_event` or `off`).

### Pricing (pay per event)

- `site-checked`, $0.003: each website in your list that was visited, whether or not contact details were found. Blocked sites count: they were tried. Sites cut short by the run deadline or an error, rows without a usable website, and sites past your cost limit are not charged.
- `google-search`, $0.008: each site searched on Google, only with `searchFallback: true` and only on paid Apify plans. On the free plan the search runs on your own account instead, and apify/google-search-scraper bills you directly (about $0.0045 per site searched).
- The run never charges more than its maximum cost (`maxTotalChargeUsd`, $2.50 by default). Sites past it are not crawled and come back with status `charge_limit_reached` and a note; raise the limit and send them again. 200 sites cost $0.60, plus up to $1.60 if all are searched.
- Charges are sent after the results are saved. `summary.charged_events` and each row's `charged` list what is billed; a charge request that fails is logged as `charge_failed` and is not billed.

### Paid search fallback (`searchFallback`, off by default)

The crawl reads each site itself. Some sites block it or show none of the requested contact. Set `"searchFallback": true` to search those sites once on Google as `"@domain"` through apify/google-search-scraper.

- Cost: $0.008 per site searched on paid plans (see Pricing), about $0.0045 billed by apify/google-search-scraper on the free plan; charged even when nothing is found. Sites where the crawl found the requested contact are never searched; the search finds emails only. Phone-only runs (`requiredContact: "phone"`) never search.
- Result: emails on the site's domain seen in result titles or snippets are added with `method=search_snippet`, the result page as `source_url`, and `source_on_site`. They come from third-party pages (social profiles, app stores, registries, review sites) and may be stale or wrong.
- Yield varies: in a 61-site test it found an email for 22 sites, and a repeat search can return different results.
- Time: the crawl stops up to 5 minutes (never more than half the run) before the run deadline to leave the search its time.
- To keep only emails seen on the site itself, drop those with `source_on_site: false`.

### Use it from code or an AI agent

Start a run through the Apify API and read its dataset; no knowledge of this Actor's code is needed:

```bash
curl -X POST "https://api.apify.com/v2/acts/forlab~contact-evidence-enricher/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"website":"https://example.com"}]}'
```

The input schema, the dataset rows, the `OUTPUT` summary and the status codes above are the stable contract.

### How the crawl behaves

- It follows robots.txt and its crawl delays up to five seconds. A robots.txt 404 permits crawling; an unreadable robots.txt stops that site.
- It reads only the submitted site. Redirects within the same host (including `www` and HTTP to HTTPS) are followed; a redirect to another domain or subdomain stops the site with `redirected_to_other_site`.
- Rows sharing a website are crawled once and the result is copied to each row. `www` and bare hosts are separate sites and are charged separately.
- No JavaScript rendering, proxies, CAPTCHA solving, logins, mailbox verification or outreach. Some sites will therefore give no result; the `note` says why.
- Only public HTTP/HTTPS addresses on ports 80/443 are fetched. Private, loopback and cloud metadata addresses are rejected, TLS certificates are checked, and responses are capped at 2 MiB with at most three redirects.
- A run stops starting new requests 30 seconds before its timeout, so every row is still written; unfinished sites get `deadline_exceeded`.

# Actor input Schema

## `records` (type: `array`):

1-200 objects. Original fields are preserved under input. Supply records OR csvText, never both.

## `csvText` (type: `string`):

CSV with unique column names. Use instead of records.

## `websiteField` (type: `string`):

Name of the input field containing the website URL.

## `requiredContact` (type: `string`):

Which contact makes a site count as found (status contact_evidence_found). any: an email, a phone or a social profile (default). either: an email or a phone. email or phone: only that type. All contact types found are returned in every mode; this only sets the status and which sites the optional paid search covers.

## `maxPagesPerSite` (type: `integer`):

Pages tried per site: the home page plus likely contact pages on the same site. robots.txt requests and redirect hops are not counted.

## `concurrency` (type: `integer`):

How many websites are crawled at the same time.

## `searchFallback` (type: `boolean`):

Off by default. Turn it on only if you accept an extra cost. After the crawl, each site that could not be opened or showed none of the requested contact is searched once on Google as "@domain" through apify/google-search-scraper, charged $0.008 per site searched on paid Apify plans, even when nothing is found (on the free plan the search Actor bills your account directly instead, about $0.0045 per site). Sites where the crawl found the requested contact are never searched; the search finds emails only. Emails on the site's domain seen in result titles or snippets are added with method search_snippet and the result page as source_url; they come from third-party pages (social profiles, registries, review sites) and may be stale. Ignored when requiredContact is phone.

## Actor input object example

```json
{
  "records": [
    {
      "company": "Pinar",
      "website": "https://www.pinar.com.tr/"
    },
    {
      "company": "Haribo",
      "website": "https://www.haribo.com/"
    }
  ],
  "websiteField": "website",
  "requiredContact": "any",
  "maxPagesPerSite": 3,
  "concurrency": 4,
  "searchFallback": false
}
```

# Actor output Schema

## `results` (type: `string`):

One item per input record, in the original order, with the contacts found under `enrichment`.

## `summary` (type: `string`):

Status counts, blocked sites, search fallback result and charged events.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "records": [
        {
            "company": "Pinar",
            "website": "https://www.pinar.com.tr/"
        },
        {
            "company": "Haribo",
            "website": "https://www.haribo.com/"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("forlab/contact-evidence-enricher").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "records": [
        {
            "company": "Pinar",
            "website": "https://www.pinar.com.tr/",
        },
        {
            "company": "Haribo",
            "website": "https://www.haribo.com/",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("forlab/contact-evidence-enricher").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "records": [
    {
      "company": "Pinar",
      "website": "https://www.pinar.com.tr/"
    },
    {
      "company": "Haribo",
      "website": "https://www.haribo.com/"
    }
  ]
}' |
apify call forlab/contact-evidence-enricher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,forlab/contact-evidence-enricher"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MWiZSqb3unvtwXFdy/builds/f0OzwJdmSWByTIjp9/openapi.json
