Provided List Contact Subtraction

Turn authorized business-site contact arrays into unique email addresses absent from your own explicitly supplied email list. This is one bounded comparison step for agencies that already hold an Apify Dataset and a CRM email export. It retains source provenance for human review.

Try the original demo

The default input is:

{
  "mode": "demo"
}

The original CC0 fixture contains sales@client-owned.example, a blank value, a duplicate sales address and ops@client-owned.example. The provided list contains the sales address. The result is one useful ops@client-owned.example contact, with matchedProvided=1, sourceBlank=1, duplicateDropped=1 and unmatchedUnique=1. The domains are reserved examples, not customer data. The demo has $0 custom contact fees. A configured platform start fee may still apply.

Demo mode accepts only mode; {} is equivalent to the original demo. Remove custom fields when switching back to demo. Adding customer data to demo mode is rejected.

Use your own inputs

Set mode to subtract, set rightsConfirmed to true, and provide exactly one source: a same-account sourceDatasetId selected in the read-only picker, or an inline sourceRows array. This example uses inline data:

{
  "mode": "subtract",
  "sourceRows": [
    {
      "domain": "client-owned.example",
      "originalStartUrl": "https://client-owned.example",
      "emails": [
        "sales@client-owned.example",
        " ",
        "sales@client-owned.example",
        "ops@client-owned.example"
      ]
    }
  ],
  "providedEmailsCsv": "Email\nsales@client-owned.example\n",
  "providedEmailColumns": [
    "Email"
  ],
  "comparisonPolicy": "exact",
  "rightsConfirmed": true
}

The useful contact in this custom mode is eligible for the custom contact fee, even though this example uses fictional addresses. sample-custom-input.json contains this input. For a Dataset, replace sourceRows with sourceDatasetId containing the Dataset ID; do not include both. The Dataset must belong to the running Apify account. The Actor reads it in bounded pages and checks metadata before and after the read. Missing ownership, inaccessible resources, incomplete pages or a changed Dataset abort the run.

providedEmailsCsv must be present in custom mode. An explicitly empty string or whitespace-only string means an intentionally empty provided list. A header-only CSV also has no supplied addresses. For nonempty CSV, every header named in providedEmailColumns must exist exactly once; the runtime default is ["Email"]. CSV headers are exact and case-sensitive. Duplicate selected headers, bad CSV or any unusable nonblank supplied email value abort before subtraction. An omitted list is never treated as an empty list.

Include all relevant email columns, including secondary addresses. Declare multiValueSeparator when one cell contains several addresses; for example, ";". Without it, each cell is one value. There is no automatic CRM header translation or delimiter inference. CSV quoting follows RFC 4180; text values stay strings.

Comparison and interpretation

Only strings in top-level emails[] arrays are read from source rows. Blank, nonstring and unusable source values are counted rather than exported. Rows without an emails field, or with an incorrectly shaped emails field, are counted. Boundary whitespace is trimmed. The default comparisonPolicy is exact; case_insensitive_full_address lowercases the entire address when explicitly selected. Plus tags and dots are preserved.

Each comparison key is exported once. Repeated source keys count as duplicateDropped; matching supplied keys count as matchedProvided. The retained email is the first usable trimmed value. Original email strings, domains, originalStartUrls and zero-based sourceRowRefs are combined within the provenance caps. Source domains and URLs are unverified strings, not fetched or enriched.

decision="not_in_provided_list" and scope="provided_only" mean only that the declared matching key was absent from the addresses you supplied. This does not establish mailbox validity, deliverability, consent, a new person, complete suppression coverage or permission to contact someone. Missing columns or unlisted secondary addresses cannot be inferred. Source metadata timestamps are reported where available; they do not establish when a website was collected or whether an address is current.

Outputs

The default Dataset contains one kind="summary" row and zero or more kind="contact" rows. Summary counts distinguish source values, rejected/blank values, unique keys, matched keys, duplicates, unmatched candidates and saved contacts. Contact rows include email, comparisonKey, decision, originalEmails, domains, originalStartUrls, sourceRowRefs, provenanceTruncated, comparisonPolicy, scope and a billing reference.

The default Key-value store also contains:

• REPORT.json: all funded saved contacts, counts, coverage, declared policy, schema profile, generation time, source metadata, limits, truncation and custom billing state.
• REVIEW.csv: the same funded contacts; provenance arrays are JSON-encoded in quoted cells. Potential spreadsheet formula cells receive an apostrophe guard, so spreadsheet display text can differ from raw JSON.

The Actor Output schema links the Dataset and both files. Read REPORT.json and the native event ledger for confirmed charges; Dataset rows point to these and do not assert a settled fee. A link alone does not prove that a run completed.

If budget capacity limits the result, status is budget_truncated, and counts.budgetSkipped identifies skipped unmatched contacts. If the contact output cap limits it, status is output_limit_truncated, and counts.outputLimitSkipped identifies the omitted candidates. The complete report means the complete funded saved set, not every unmatched candidate. Coverage remains provided_only. The supplied list is never silently truncated.

Price and budget

The proposed Pay-per-event price is $0.0005 per contact_exported event, one unique useful unmatched contact stored across the Dataset, REPORT.json and REVIEW.csv. There is no default Dataset-item charge and no manual custom start event. One thousand useful custom contacts cost $0.50 in custom contact events, plus a platform-managed $0.00005 Actor start fee if configured. This local pricing specification has not yet been applied to a native Actor.

Original demo, matched addresses, duplicate addresses, unusable source values, and invalid or failed inputs incur no custom contact fee. A run with no useful unmatched contacts has no custom contact fee. The configured platform start fee is separate. Set the maximum run charge to bound custom output: the Actor determines whole funded contact capacity before writing useful output to any storage or checkpoint and reserves startup allocation separately. A partial contact fee cannot fund a contact. Local execution outside Pay-per-event does not demonstrate native billing.

Outputs are stored before custom charging. A completed checkpoint with the same input returns the saved report without repeating output or contact events. Any incomplete checkpoint refuses automatic replay because previous output or a charge may have completed before a lost response. pending or ambiguous billing states require review; they are not confirmed charges and are not retried blindly.

Bounds and authorization

Bound	Maximum
Source records	10,000
Email values across source	50,000
Provided CSV data rows and selected email values	50,000 each
UTF-8 bytes of each source/provided side	10 MiB each
CSV columns / selected headers	200
Output contacts	10,000, further bounded by charge capacity
Distinct values per provenance list per contact	20

Input byte, row and value limits fail before useful output; selected results are limited only by the disclosed output/budget caps. provenanceTruncated is true when an email, domain, URL or row-reference list exceeds its cap.

Custom mode requires authorization for the source websites and records and for the supplied CRM/email export. No Google Maps, LinkedIn, social-source or person-enrichment preset is provided. Processing uses your Actor inputs and Apify storage. No scraping, upstream Actor execution, DNS/SMTP checks, message sending, webhook, LLM, database or external contact enrichment is performed. The sole optional upstream read is the explicitly selected same-account Apify Dataset.

Implementation and status

Native JavaScript Set/Map comparison uses Apify SDK 3.7.2 and csv-parse 7.0.2 (MIT), with pinned package and lock files. The container uses Node.js 24.22.1. The original fixture is dedicated under CC0-1.0. No third-party scraper code or customer data is included. Shipping hashes and local test evidence are maintained separately in the implementation evidence directory. Native create, push, build, run and publication remain separate gated operations.

Resource-picker and output-link shapes were checked against the official Apify input schema specification, Actor permissions, Dataset schema specification, and Actor Output schema on 2026-10-12. Platform build and runtime recognition must still be verified at release.