Citation Builder v2.1 — Audit, Submit & Sync 45+ Directories

Audit your existing citations across 45+ directories (with industry-specific bonus directories), find NAP inconsistencies with AI-powered cross-validation, get Claude AI health scoring and correction suggestions, auto-submit to 15 free directories, and push to aggregator APIs (Data Axle, Yext, BrightLocal). Built for local SEO agencies managing multiple clients.

What It Actually Does

Mode	What Happens	Cost
audit	Searches 45+ directories for your business, extracts NAP (CSS + Firecrawl AI fallback), cross-validates, AI health scoring	$0.05/dir (~$2.25 base)
submit	Audit first, then auto-fills forms on 15 free directories + copy-paste data for login-required ones	+$0.25/submission (~$6.00 total)
full	Audit + Submit + pushes to Data Axle/Yext/BrightLocal aggregator APIs (BYOK) — these feed 100-200+ downstream directories each	+$0.50/API push (~$7.50 total)

Quick Start

Demo Mode (free)

{
  "demoMode": true
}

Returns sample v2.1 audit results showing the output structure — found_correct, found_incorrect (with specific NAP issues), missing directories, health scoring, and cross-validation.

Real Audit

{
  "mode": "audit",
  "businessName": "Joe's Pizza",
  "streetAddress": "456 Oak Avenue",
  "city": "Dallas",
  "state": "TX",
  "zipCode": "75201",
  "phone": "(214) 555-7890",
  "website": "https://joespizza.com"
}

Audit with AI Analysis

{
  "mode": "audit",
  "businessName": "Joe's Pizza",
  "streetAddress": "456 Oak Avenue",
  "city": "Dallas",
  "state": "TX",
  "zipCode": "75201",
  "phone": "(214) 555-7890",
  "website": "https://joespizza.com",
  "enableAiAnalysis": true,
  "enableCrossValidation": true,
  "anthropicApiKey": "sk-ant-...",
  "firecrawlApiKey": "fc-..."
}

Submit with CAPTCHA Auto-Solving

{
  "mode": "submit",
  "businessName": "Joe's Pizza",
  "streetAddress": "456 Oak Avenue",
  "city": "Dallas",
  "state": "TX",
  "zipCode": "75201",
  "phone": "(214) 555-7890",
  "website": "https://joespizza.com",
  "captchaSolverProvider": "capsolver",
  "captchaSolverApiKey": "CAP-..."
}

When a directory submission hits a CAPTCHA, the actor sends it to your solver instead of stopping. Supports reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and image CAPTCHAs (CapSolver only). If solving fails, falls back to screenshot + manual completion.

Audit + Submit with Industry Directories

{
  "mode": "submit",
  "businessName": "Joe's Pizza",
  "streetAddress": "456 Oak Avenue",
  "city": "Dallas",
  "state": "TX",
  "zipCode": "75201",
  "phone": "(214) 555-7890",
  "website": "https://joespizza.com",
  "email": "info@joespizza.com",
  "categories": ["Pizza", "Restaurant", "Italian Food"],
  "industry": "restaurant",
  "verifyAfterSubmit": true
}

Full Mode (with API keys)

{
  "mode": "full",
  "businessName": "Smith & Associates Law",
  "streetAddress": "100 Commerce St Suite 400",
  "city": "Dallas",
  "state": "TX",
  "zipCode": "75201",
  "phone": "(214) 555-7890",
  "website": "https://smithlaw.com",
  "categories": ["Attorney", "Law Firm"],
  "industry": "legal",
  "dataAxleApiKey": "your-key",
  "yextApiKey": "your-key"
}

Batch Mode (Agencies)

Process multiple businesses in a single run:

{
  "mode": "audit",
  "businesses": [
    {
      "businessName": "Joe's Pizza",
      "streetAddress": "456 Oak Avenue",
      "city": "Dallas",
      "state": "TX",
      "zipCode": "75201",
      "phone": "(214) 555-7890",
      "industry": "restaurant"
    },
    {
      "businessName": "Smith Law Firm",
      "streetAddress": "100 Commerce St",
      "city": "Dallas",
      "state": "TX",
      "zipCode": "75201",
      "phone": "(214) 555-4567",
      "industry": "legal"
    }
  ],
  "enableAiAnalysis": true,
  "anthropicApiKey": "sk-ant-..."
}

Each business is processed sequentially with its own audit, submissions, and results.

45+ Directories

Critical — Audit + Copy-Paste (6)

Google Business Profile, Yelp, Facebook, Bing Places, Apple Maps, BBB

High Priority — Audit + Copy-Paste (10)

Yellow Pages, Manta, MapQuest, SuperPages, TripAdvisor, Foursquare, LinkedIn, Angi, Nextdoor, Merchant Circle

Auto-Submittable — No Login Required (15)

Hotfrog, Brownbook, ShowMeLocal, EZLocal, ChamberOfCommerce, Tupalo, Cylex, n49, Cybo, FindUsLocal, USCity, WhereTo, GoLocal, Hub.biz, Fyple

These 15 directories accept free submissions without creating an account. The actor navigates to each submission form, auto-fills your NAP, and clicks submit. If a CAPTCHA appears, the actor will auto-solve it using your configured CAPTCHA solver (CapSolver, 2Captcha, or Anti-Captcha). Without a solver, it screenshots the page and reports verification_pending for manual completion.

Medium — Login Required (6)

Citysearch, Alignable, Trustpilot, CitySquares, LocalStack, Spoke

Low Priority — Audit Only (8)

Local.com, eLocal, 2FindLocal, iBegin, Kompass, DexKnows, YellowBot, Instagram

Industry-Specific Directories (auto-added based on industry/categories)

Industry	Directories Added
Home Services	HomeAdvisor, Porch (auto-submit), Thumbtack, Houzz
Legal	Avvo, FindLaw, Justia
Healthcare	Healthgrades, Zocdoc, Vitals
Real Estate	Zillow, Realtor.com
Restaurant	OpenTable, Zomato
Auto	CarGurus, RepairPal

Set industry or categories to activate these. They're added on top of the base 45 — a plumber gets 49 directories, a lawyer gets 48, etc.

Aggregator APIs — Full Mode (3, BYOK)

• Data Axle (/v3/places/claims) — creates/claims a listing that feeds Yellow Pages, SuperPages, DexKnows + 100+ downstream directories. Permanent citations — once in their database, downstream partners sync over 2-8 weeks.
• Yext (/v2/accounts/me/entities) — syncs to 200+ directories via PowerListings. Categories auto-mapped to Yext taxonomy IDs (40+ business types supported). Subscription-dependent — citations are active only while you maintain a Yext account. If you cancel, listings get suppressed or reverted.
• BrightLocal (/api/v4/cb/add) — places a managed citation campaign order. BrightLocal's team manually handles submissions within 5-7 business days. Not instant — you're placing an order that their team fulfills. Citations are permanent once built.

Important: The actor pushes your data to these aggregator APIs — it doesn't scrape 200+ directories directly. Data Axle and BrightLocal create permanent citations. Yext creates managed citations tied to your subscription. Re-run the audit after 2-8 weeks to see downstream citations appear.

How It Works

Step 1: Audit (all directories)

1. Searches each directory for your business (platform-native search first, Google site: fallback)
2. If found, navigates to listing and extracts NAP via CSS selectors
3. Firecrawl AI fallback: If CSS selectors return nothing (common on React SPAs like Healthgrades, Zocdoc), Firecrawl's AI extracts NAP data from the page content
4. Compares with fuzzy matching: name word overlap, address abbreviation normalization, last-10-digit phone comparison
5. Reports: found_correct, found_incorrect (with field-level issues), missing, or error

Step 2: Cross-Validation (automatic)

When enableCrossValidation is true (default):

1. Collects NAP data from all directories where your business was found
2. Uses weighted voting to determine your canonical (most likely correct) NAP
3. Platform weights: GBP/Yelp/Facebook = 10, YP/BBB = 6, industry directories = 2-3
4. If googlePlaceId is provided, GBP data is treated as source of truth (always correct)
5. Detects variations in business name, address formatting, and phone numbers

Step 3: AI Health Scoring (optional)

When enableAiAnalysis is true and anthropicApiKey is provided:

1. Claude AI analyzes all audit results and cross-validation data
2. Returns a health score (0-100) with letter grade (A-F)
3. Generates correction suggestions with specific fix instructions per directory
4. Creates prioritized action list — what to fix first for maximum impact
5. Estimates ranking impact of fixing inconsistencies

Step 4: Submit (free directories)

For directories where you're missing and that don't require login:

1. Navigates to the submission form URL
2. Auto-fills all NAP fields (business name, address, city, state, ZIP, phone, website, email)
3. If CAPTCHA detected → auto-solves via your configured solver (CapSolver/2Captcha/Anti-Captcha), or screenshots for manual completion if no solver configured
4. If no CAPTCHA → clicks submit, screenshots confirmation
5. Reports submitted, verification_pending, or failed

For login-required directories:

• Generates a requires_account result with direct claim/add URL and pre-formatted NAP data ready to paste

Step 5: Verify (optional)

If verifyAfterSubmit: true, waits 10 seconds then re-audits directories you just submitted to. Confirms which are live immediately vs. still indexing. Uses a single batched crawler for efficiency.

Step 6: API Push (full mode, BYOK)

With your own API keys:

• Data Axle — creates/claims a listing that feeds 100+ downstream directories. Downstream citations propagate over 2-8 weeks as data partners sync. These are permanent.
• Yext — creates entity with proper category taxonomy mapping (40+ category types supported). Yext syncs to 200+ directories, but only while your Yext subscription is active — if you cancel, those listings get suppressed.
• BrightLocal — places a managed citation campaign order. BrightLocal's team manually builds citations over 5-7 business days. These are permanent once built.

NAP Update Recommendations

For found_incorrect listings, the output includes specific update instructions — where to login, who to call, and which aggregator feeds which directory.

Historical Tracking

Each run saves a snapshot to the Key-Value store. On subsequent runs for the same business, the actor compares against the previous snapshot and reports:

• New citations found since last run
• Citations that disappeared
• NAP corrections detected
• Health score trends

Up to 12 historical snapshots are retained per business.

Output Structure

{
  "businessInfo": { "name": "...", "address": "...", "phone": "...", "website": "..." },
  "mode": "submit",
  "healthScore": 72,
  "healthGrade": "C",
  "canonicalNAP": {
    "name": { "value": "Joe's Pizza", "confidence": 0.95, "sources": 8 },
    "address": { "value": "456 Oak Avenue, Dallas, TX 75201", "confidence": 0.90, "sources": 7 },
    "phone": { "value": "(214) 555-7890", "confidence": 0.88, "sources": 6 },
    "variations": {
      "name": ["Joe's Pizza", "Joes Pizza", "Joe's Pizza Dallas"],
      "phone": ["(214) 555-7890", "214-555-7890"]
    }
  },
  "aiAnalysis": {
    "healthScore": 72,
    "correctionSuggestions": [
      { "directory": "BBB", "field": "phone", "current": "(214) 555-9999", "suggested": "(214) 555-7890", "priority": "high" }
    ],
    "prioritizedActions": [
      "Fix phone number on BBB — high-authority directory affects local pack ranking",
      "Submit to HomeAdvisor and Thumbtack — high-value for restaurant niche"
    ],
    "estimatedImpact": "Fixing 3 NAP inconsistencies could improve local pack visibility by 15-20%"
  },
  "audit": {
    "summary": { "total": 49, "correct": 12, "incorrect": 3, "missing": 31, "errors": 3 },
    "results": [
      {
        "directory": "Yelp",
        "status": "found_incorrect",
        "listingUrl": "https://yelp.com/biz/...",
        "foundNAP": { "name": "...", "address": "...", "phone": "..." },
        "issues": [{ "field": "phone", "expected": "(214) 555-1234", "found": "(214) 555-9999" }],
        "rating": "4.5",
        "reviewCount": "89"
      }
    ]
  },
  "submissions": {
    "summary": { "total": 8, "submitted": 5, "failed": 1, "requiresAccount": 0, "verificationPending": 2 },
    "results": [...]
  },
  "verification": {
    "summary": { "total": 5, "confirmed": 2, "notYetLive": 3, "errors": 0 },
    "results": [...]
  },
  "apiSubmissions": [...],
  "industryDirectoriesAdded": ["HomeAdvisor", "Porch", "Thumbtack", "Houzz"],
  "recommendations": [
    "Fix phone on BBB: (214) 555-9999 → (214) 555-1234",
    "UPDATE BBB: Contact your local BBB office or update at https://www.bbb.org/my-business",
    "Industry directories missing: HomeAdvisor, Thumbtack — these are high-value for your niche",
    "Health score improved from 65 → 72 since last run (3 corrections detected)",
    "Schedule monthly re-audits to track citation health"
  ]
}

Key-Value Store Outputs

Key	Description
CITATION_REPORT	Full output (same as dataset)
AUDIT_RESULTS	Array of audit results only
SUBMISSION_RESULTS	Array of submission results (submit/full mode)
captcha-{directory}	Screenshot of CAPTCHA pages
submission-{directory}	Screenshot of submission confirmations
history-{businessName}	Historical snapshot (last 12 runs)

Input Parameters

Required

Field	Description
businessName	Official business name
streetAddress	Street address
city	City
state	2-letter state code
zipCode	5-digit ZIP
phone	Business phone

Optional

Field	Description
mode	audit (default), submit, or full
website	Business website URL
email	Contact email
description	Business description
categories	Business categories — auto-mapped to Yext taxonomy IDs
industry	Unlocks niche directories (home services, legal, healthcare, real estate, restaurant, auto)
verifyAfterSubmit	Re-audit submitted directories to confirm they went live
enableAiAnalysis	Run Claude AI health scoring and correction suggestions (default: true, requires anthropicApiKey)
enableCrossValidation	Weighted voting across directories to determine canonical NAP (default: true)
googlePlaceId	Your GBP Place ID — if provided, GBP is treated as source of truth
directories	Only process these directories
skipDirectories	Skip these directories
maxConcurrent	Parallel processing (default: 3)
businesses	Array of businesses for batch mode (agencies)
dryRun	Legacy — maps to mode: 'audit'

API Keys (BYOK)

Field	Description
dataAxleApiKey	Data Axle API key — /v3/places/claims for listing creation
yextApiKey	Yext API key — Knowledge API with category mapping
brightLocalApiKey	BrightLocal API key — managed citation campaigns
anthropicApiKey	Claude AI analysis — health scoring, corrections, impact estimates
firecrawlApiKey	AI extraction fallback — extracts NAP from React SPAs when CSS selectors fail
captchaSolverProvider	CAPTCHA solver service: capsolver, 2captcha, or anticaptcha
captchaSolverApiKey	API key for your chosen CAPTCHA solver

Pricing

Event	Description	Price
citation_audited	NAP checked on one directory	$0.05
citation_submitted	Form auto-filled and submitted	$0.25
api_submission	Aggregator API push	$0.50

Example costs:

• Audit 45 base directories: 45 x $0.05 = $2.25
• Audit 49 dirs (with industry): 49 x $0.05 = $2.45
• Audit + submit to 15 free dirs: $2.25 + 15 x $0.25 = $6.00
• Full mode + 3 API pushes: $6.00 + 3 x $0.50 = $7.50

No charge for directories that error/timeout.

Use Cases

• Citation audit: Find which directories list your business and check NAP consistency
• New business: Submit to all free directories in one run
• Rebranding: Identify everywhere your old NAP appears so you can update it
• Agency workflow: Batch audit → fix inconsistencies → submit to missing → push to aggregators
• Franchise ops: Standardize NAP across all locations
• Industry targeting: Add HomeAdvisor/Thumbtack for contractors, Avvo/FindLaw for lawyers, Healthgrades/Zocdoc for doctors
• Monthly monitoring: Track health score trends with historical comparison

Common Issues

"Missing required fields" error

Provide all 6 required fields: businessName, streetAddress, city, state, zipCode, phone.

Many directories showing "error"

Some directories block automated access. Use residential proxy (default) and maxConcurrent: 2 for better success rates.

CAPTCHA on submission

If you provide a captchaSolverProvider and captchaSolverApiKey, the actor will attempt to auto-solve CAPTCHAs during submission. Supported types:

• reCAPTCHA v2/v3 — all three providers
• hCaptcha — all three providers
• Cloudflare Turnstile — all three providers
• Image CAPTCHAs — CapSolver only

If no solver is configured (or solving fails), the actor screenshots the page and reports verification_pending. Complete the CAPTCHA manually using the submission URL provided.

Provider options:

Provider	Website	Notes
CapSolver	capsolver.com	Fastest, supports image CAPTCHAs, best Turnstile support
2Captcha	2captcha.com	Most established, reliable reCAPTCHA solving
Anti-Captcha	anti-captcha.com	Good pricing, solid hCaptcha support

Google blocking searches

If Google blocks too many searches, the actor falls back to platform-native search URLs. Residential proxy helps.

Yext category mapping

Categories are auto-mapped to Yext taxonomy IDs (40+ mappings for common business types). If your category isn't mapped, Yext will still accept the entity — it just won't have a category assigned.

Firecrawl not extracting data

Ensure your firecrawlApiKey is valid and has credits. Firecrawl is used as a fallback only when CSS selectors fail — this is most common on React SPAs like Healthgrades, Zocdoc, and similar modern directory sites.

AI analysis not appearing

Requires both enableAiAnalysis: true and a valid anthropicApiKey. Uses Claude Sonnet for analysis.

Need Deeper Auditing?

Check out Citation God Mode for the most comprehensive citation audit available — 60+ directories, Moz Local Listings integration, cross-validation engine, canonical NAP detection, and tiered depth modes (Quick/Standard/Deep/God). Use Citation Builder to fix what Citation God Mode finds.

---

Built by John Rippy | Actor Arsenal