crm-enricher

CRM Enricher

Overview

This skill takes a CRM export with holes in it and returns the same rows with gaps filled under written rules, an update file and a create file mapped to the user's CRM, and a report that accounts for every field it touched or could not fill and dates the next refresh.

The mistake it prevents is the "enrich everything, overwrite everything" import. A rep typed a direct dial and a nickname into a record last month; an enrichment job replaces both with a switchboard and a legal name, the import runs, and the team cannot tell which values changed. This skill treats every CRM value as owner-entered until proven stale, writes found values to empty fields only unless a field rule says otherwise, keeps the prior value in an audit column whenever it does replace one, and refuses to auto-write a low-confidence match.

It also prevents paying twice. The Lead Database lookup runs first because it is included on Growth and Scale plans; Email Finder ($0.05 per email found) and Mobile Finder ($0.25 per number found) run only on the rows the database could not fill.

When to Use

• "Here's our HubSpot export, 40% of contacts have no email. Fill what you can."
• "Append job titles and company size to these Pipedrive people."
• "Add mobiles for our open opportunities before the call blitz."
• "Our Salesforce leads are stale. Which ones changed jobs?"
• "Clean up this GoHighLevel import before we load it."

Use a different skill when:

Prerequisites

Authoritative Foundations

Details and the routing table for this skill's files: references/framework-notes.md.

Workflow

1. Profile the export

Read the header and count, per field: present, blank, malformed. Also count the identifiers each row carries, because they decide which tool can fill it:

Derive company_domain from the website field, or from the email when the email is not a freemail address (gmail.com, outlook.com, yahoo.com, icloud.com, hotmail.com, aol.com, proton.me). Normalize per references/list-quality-standard.md section 3. Do not merge duplicate CRM records; flag them DUPLICATE_IN_CRM and let the CRM's own merge tool handle them. Skip test and placeholder records (JUNK_RECORD) and the user's own employees (INTERNAL_RECORD) before counting gaps, so fill rates describe prospects only.

2. Write the field rule sheet

Every field gets a fill precedence, one overwrite policy from this vocabulary, and the segments allowed into each paid step (that list is the per-row spend cap). Show the sheet to the user and get a yes before any paid step.

Default precedence per field, and the full conflict matrix, are in references/field-precedence-and-overwrite-rules.md.

3. Route each row by its strongest identifier

4. Count, estimate, confirm

Compute the expected cost and the ceiling (every paid lookup hits). Use the formulas in ScraperCity Implementation below. Run check_wallet. Show the table and wait for a go-ahead. Mobiles are the expensive line: count them only for people in the accounts or stages the user named and at the seniority levels and departments reps will dial, read from the Lead Database's seniority and department on the refreshed record. Contacts with no high match have no refreshed seniority, so they stay out of mobile scope unless the CRM title already names a buyer role the user listed.

5. Run lookups, cheapest first

Each field family runs its own ladder and a row leaves it at the first step that meets the stop condition, so no row pays twice for one field. Order: Lead Database (included on Growth and Scale) by socialUrl, then by companyDomain, then by companyName; then validate_emails on existing emails that have no validation date in the last 90 days; then find_emails for remaining blanks and for emails that came back invalid; then find_mobiles with LinkedIn URLs for in-scope rows, and a second run with the work email for the URL misses only; then scrape_website_finder for account-only rows. Email Finder, Mobile Finder and Website Finder bill only when they find something, so the price per hit is the list price at any hit rate; order is set by price per usable result after validation (references/waterfall-and-cost-control.md). The batch sizes, paging limits and REST loop are in references/enrichment-runbook.md. A call that fails is LOOKUP_ERROR in the retry file, never NOT_FOUND.

Two passes widen email coverage at no cost on a miss. First, Email Finder misses get one retry with a different input: company_name in place of a domain that came from the website field (the mail domain can differ from the web domain), and full_name for names that did not split. Only misses enter, so one person bills at most once; give the retry its own cost line. Second, when every validated address on a domain returns no mail exchanger (sc_mx_record empty), flag the domain DOMAIN_NO_MAIL, skip Email Finder there, and look the company up by companyName in the Lead Database: a different current domain means the company moved or was acquired, and its contacts rerun on the new domain.

6. Score each match and apply the rules

Company size is compared by band (1-10, 11-50, 51-200, 201-500, 501-1,000, 1,001-5,000, 5,001+): same band keeps the CRM value, a different band is staged as SIZE_BAND_CHANGE; the user's freshness window decides whether an older CRM value is replaced after review.

A High match whose Lead Database company differs from the CRM company is a job change. Do not overwrite the company. Flag JOB_CHANGE, put the new company and title in enriched_company and enriched_title, and keep the old record out of sends at the old address. Then do two things: create the person at the new company (email from the Lead Database match, validated, or from Email Finder) and put every one who validates into the main campaign as its own "new role" segment, so the copy can name the move; and find a replacement at the old account from the Lead Database people at that domain with the departed person's title.

High matches also fill seniority and department when the CRM has them blank. Write them as properties so the campaign can be segmented by them and the mobile scope can be filtered on them.

7. Build the update and create files

Write the CRM-ready file with the CRM's record ID as the first column, only the fields being updated, and the audit columns. New contacts (job changes at the new company, buyers at account-only companies) go in a separate create file, deduped against the full CRM export on email, LinkedIn URL, then name plus domain (references/api-pipeline-and-sync.md section 6). Map column names with references/crm-import-mapping.md. Write every unfilled field's reason code to enrich_flags.

8. Test import, then full import

Import 10 rows in update-only mode, open 3 of them in the CRM, confirm nothing owner-entered changed and the audit columns are filled. Then import the rest. Keep the untouched original export as the rollback file.

9. Set the refresh schedule and the send gate

Contact data decays at roughly 1.3% to 2.3% of a list a month (planning range from BLS tenure data and the ZeroBounce 2026 decay report; measure your own). Schedule by segment: validation before any send when the last check is older than 90 days (ZeroBounce: verify at least once per quarter), a job-change sweep for open opportunities and customer champions, a title and company refresh for active accounts on the cadence the user sets, nothing paid for the rest until they enter a sequence. Build the send-gate view (valid email, validated within 90 days, no opt-out or JOB_CHANGE flag) as the only source for sequence enrollment. Catch-all addresses go to a separate lane that opens once the main campaign's first 200 sends bounce under 2% and pauses past 2% (Berman's bounce line; Instantly checks bounces after 200 sends). Dates, owners and costs go in the report's Refresh Schedule; the view definitions per CRM are in references/api-pipeline-and-sync.md sections 8 and 10. Then fill in templates/output-template.md and run scripts/check-output.py on it.

ScraperCity Implementation

Tools and prices (from references/scrapercity-catalog.md)

Calls

{"tool": "query_lead_database", "args": {"socialUrl": "https://www.linkedin.com/in/dana-okafor", "limit": 5}}
{"tool": "query_lead_database", "args": {"companyDomain": "ledgerline.example", "limit": 100, "after": "0"}}
{"tool": "query_lead_database", "args": {"companyDomain": "ledgerline.example", "limit": 1}}
{"tool": "query_lead_database", "args": {"companyName": "Ledgerline", "limit": 25}}
{"tool": "find_emails", "args": {"contacts": [{"first_name": "Dana", "last_name": "Okafor", "domain": "ledgerline.example"}]}}
{"tool": "find_mobiles", "args": {"inputs": ["https://www.linkedin.com/in/dana-okafor", "[email protected]"]}}
{"tool": "scrape_website_finder", "args": {"domains": ["brightpathhr.example", "shipwise.example"], "jobTitle": "Head of People"}}
{"tool": "validate_emails", "args": {"emails": ["[email protected]"]}}

The limit: 1 company call is enough to read company fields (industry, size, revenue, HQ) for a domain. The limit: 100 call lists people at the domain so you can match first and last name locally; the Lead Database has no name filter. Page with after only while the person is not yet found, and stop at 5 pages for one domain (large companies go to find_emails instead). companyDomain accepts several domains comma separated, but the 100 rows per call are then shared across them. Batch domains only when each company is small (under about 20 people), and send one domain per call otherwise.

Leave autoValidateEmails and autoFindMobiles off on scrape_website_finder. The catalog does not list a price for those flags; running validate_emails and find_mobiles separately keeps every charge at a known catalog price.

REST for loops over hundreds of domains: GET https://app.scrapercity.com/api/v1/database/leads?companyDomain=ledgerline.example&limit=100&after=0 with Authorization: Bearer $SCRAPERCITY_API_KEY; scrapers are POST /api/v1/scrape/email-finder, /mobile-finder, /website-finder, /email-validator, then GET /api/v1/scrape/status/{runId} and GET /api/downloads/{runId}.

Cost formulas

find_emails     expected = lookups x expected hit rate x $0.05     ceiling = lookups x $0.05
find_mobiles    expected = inputs x expected hit rate x $0.25      ceiling = inputs x $0.25
website_finder  ceiling  = domains x $0.0499 (one contact per domain per title)
validate_emails exact    = unique emails x $0.00169
Lead Database   $0 on Growth and Scale (counts against 100,000 new leads a day)

Hit rates depend on the list. Use the pilot method from references/enrichment-runbook.md: run 50 rows, measure, then extrapolate. Show both the expected cost and the ceiling.

Worked cost estimate

A 2,400-contact HubSpot export (the full run is in examples/worked-example.md): the Lead Database filled 211 missing emails for free, which left 479 first-pass Email Finder lookups (blanks it could not fill, invalid replacements, job changers) and a 120-row company-name retry; 2,112 emails to validate; 290 mobile inputs once the scope was cut to Director and above in Finance, HR and People on open deals; 38 account-only domains the database could not cover.

The table goes to the user before any paid call. Mobiles are 67% of the ceiling; if the user balks, narrow the seniority or department list first. In the report, these lines carry product names (Lead Database, Email Validator, Email Finder, Mobile Finder, Website Finder), never the tool ids.

Plan choice: Growth's $159 of monthly credits exceed its $149 price, so once a month's paid tool use reaches $159 the Lead Database comes at no extra cost over Starter. Below that, the $100 difference pays for itself when the database fills 2,000 or more emails a month that would otherwise go to Email Finder at $0.05. Funding, hiring, intent and SIC or NAICS codes are not in the catalog; flag them OUT_OF_CATALOG rather than filling them.

Build vs buy: how to run recurring enrichment

ScraperCity prices are the same in every mode; what changes is who runs the job and what breaks. Two inputs pick the mode: whether one person can review every staged row each month, and whether enrichment must run when a record is created. Count the records that need enrichment each month; total CRM size does not set the mode.

Limits that shape the API-first build: scrapercity.com/api-docs lists 100 API requests a minute per key and 10 concurrent scrapes, so 20,000 Lead Database lookups take at least 200 minutes at full speed. The Lead Database adds at most 100,000 new leads a day to the account; spread larger backfills across days. Stay with the cheaper mode until the review queue (stage_for_review rows) is the bottleneck, since an automated write-back cannot accept or reject a staged title.

Errors

Output Format

1. crm-writeback-[crm]-[date].csv: record ID first, only fields being written, audit columns, ready for update-only import.
2. crm-review-[crm]-[date].csv: Medium matches, job changes, title conflicts and size-band changes with enriched_* columns for a human to accept or reject.
3. crm-create-[crm]-[date].csv when new contacts were found: deduped against the full export, for a create-only import.
4. A report from templates/output-template.md, written for the team that will run it. Sections, in this order:

Small jobs (25 records or fewer, or a single "find this person's email"): skip the report. Return one table with record, field, value found or NOT_FOUND, source, confidence and email status, then one line with the cost and one line with what to do next.

• Each fact appears once. The email outcome lives in Email Position only; the field list lives in Summary only; the audit columns live in one Write-back Mapping row.
• Never in the report: tool ids (check_wallet, query_lead_database, find_emails and the rest), JSON tool calls, run IDs or wallet asides, skill names, file paths, sample-row tables, match-confidence tables, audit-column tables, framework lists, self-grading checklists, and sections the user did not ask for.

Quality Check

• Every field in scope has a policy from the five-value vocabulary and the user approved the sheet.
• No owner-entered value changed unless its policy is replace_if_invalid, and every replaced value sits in prior_<field>.
• For each field: filled + staged + unfilled equals the number missing before.
• Match tiers sum to the lookups attempted; no Low or None match wrote anything.
• Every unfilled field carries a reason code in enrich_flags.
• Every mobile is E.164 and sits in the mobile field, never the main phone field.
• The write-back file has the CRM record ID in every row and imports in update-only mode.
• A 10-row test import was checked in the CRM before the full import.
• New contacts sit in a separate create file with 0 matches against the full CRM export.
• No failed call is counted as NOT_FOUND; failures are LOOKUP_ERROR rows in the retry file.
• The Refresh Schedule gives each segment a date, an owner and a cost, and names the send-gate view.
• Mobiles were bought only for the accounts, seniority levels and departments the user named.
• Job changers with a valid email at the new company sit in the main campaign as a "new role" segment.
• Every decay, bounce or validation-age number in the report names its source on the same line.
• The Summary lists the fields after the run; every Next Step has a date and an owner.
• check_wallet ran and any paid step over $5 had a go-ahead.
• scripts/check-output.py report.md prints PASS.

Common Pitfalls

Execution Artifacts

Related Skills

• email-list-cleaner to validate a list without enriching it.
• mobile-appender when the job is a call list, with line-type, shared-number and suppression checks.
• decision-maker-finder to add buyers at accounts with no contacts.
• icp-list-builder to build net-new lists in the same schema.
• cold-email-list to turn enriched records into a send-ready file.
• scrapercity-lead-database for every Lead Database filter.
• scrapercity-integrations for HubSpot, Pipedrive, GoHighLevel, Zapier and n8n hookups.