{ "openapi": "3.0.1", "info": { "title": "Carbon Lead Scanner", "description": "Carbon Lead Scanner discovers and qualifys local business leads. It searches selected regions and business categories, collects official websites and publicly listed contact details, crawls websites for business information and email addresses, and verifies email domains using DNS/MX checks.", "version": "0.0", "x-build-id": "7zAJGJbqY86etnZZB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lexicaq~carbon-lead-scanner/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lexicaq-carbon-lead-scanner", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lexicaq~carbon-lead-scanner/runs": { "post": { "operationId": "runs-sync-lexicaq-carbon-lead-scanner", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lexicaq~carbon-lead-scanner/run-sync": { "post": { "operationId": "run-sync-lexicaq-carbon-lead-scanner", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "industry", "region", "targetCount", "discoverySources" ], "properties": { "industry": { "title": "Industry or niche", "minLength": 1, "type": "string", "description": "Describe the exact market to find, for example dentists or solar installers." }, "region": { "title": "Region", "minLength": 1, "type": "string", "description": "City, state, country, or another geographic area for discovery." }, "targetCount": { "title": "Target lead emails", "minimum": 1, "maximum": 5000, "type": "integer", "description": "The number of qualifying leads to return. By default, every returned target lead must have a usable public business email. The Actor keeps checking the candidate buffer until it reaches this target or the selected sources and configured budgets are exhausted." }, "discoverySources": { "title": "Discovery sources", "minItems": 1, "uniqueItems": true, "type": "array", "description": "Choose every source to use for this run. Costs and coverage vary by source.", "items": { "type": "string", "enum": [ "openstreetmap", "wikidata", "customDirectory", "providedUrls", "seedPages", "braveSearch", "googlePlaces", "apifyGoogleMaps" ], "enumTitles": [ "OpenStreetMap", "Wikidata knowledge graph", "Custom open-data or directory JSON", "Provided business websites", "Seed or directory pages", "Brave Search API", "Official Google Places API", "Apify Google Maps Actor" ] }, "default": [ "openstreetmap" ] }, "openStreetMapSearches": { "title": "OpenStreetMap fallback searches", "type": "array", "description": "Optional Nominatim business searches used directly when supplied, or after Overpass discovery is unavailable.", "items": { "type": "string" }, "default": [] }, "additionalRegions": { "title": "Additional nearby regions", "type": "array", "description": "Optional districts, towns, or neighboring municipalities to search separately. This expands coverage without silently changing your main region.", "items": { "type": "string" }, "default": [] }, "queryVariants": { "title": "Industry synonyms or variants", "type": "array", "description": "Optional alternative search phrases such as barber, hairdresser, or Friseur. They are combined with the selected region(s).", "items": { "type": "string" }, "default": [] }, "overpassEndpoints": { "title": "Custom Overpass endpoints", "type": "array", "description": "Optional preferred Overpass API endpoints, including your own local or hosted endpoint. Enter full HTTPS URLs; leave empty to use built-in public fallbacks.", "items": { "type": "string" }, "default": [] }, "wikidataQueries": { "title": "Custom Wikidata SPARQL queries", "type": "array", "description": "Optional advanced SPARQL queries for Wikidata. Each query must return a website variable and may return item, itemLabel, phone, address, and description. Leave empty for the built-in nearby-business query.", "items": { "type": "string" }, "default": [] }, "wikidataRadiusKm": { "title": "Wikidata search radius (km)", "minimum": 1, "maximum": 100, "type": "integer", "description": "Radius around the selected region used by the built-in Wikidata query.", "default": 25 }, "customDirectorySources": { "title": "Custom public-directory JSON sources", "type": "array", "description": "Optional JSON endpoints from permitted municipal, association, or open-data directories. Every source must declare a URL and the field containing the official business website.", "items": { "type": "object" }, "default": [] }, "startUrls": { "title": "Known business websites", "type": "array", "description": "List official business websites to inspect directly. Required only with Provided business websites.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "seedPages": { "title": "Seed or directory pages", "type": "array", "description": "List pages whose external business links may be discovered. Required only with Seed or directory pages.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "braveApiKey": { "title": "Brave Search API key", "type": "string", "description": "Required when Brave Search API is selected. The key is kept secret." }, "googlePlacesApiKey": { "title": "Google Places API key", "type": "string", "description": "Required only for Official Google Places API. Create a Google Cloud key with Places API (New) enabled and billing configured. The key is kept secret." }, "googlePlacesLanguageCode": { "title": "Google Places language code", "type": "string", "description": "Language for Google Places results, for example en or de.", "default": "en" }, "googlePlacesRegionCode": { "title": "Google Places region code", "type": "string", "description": "Optional two-letter country/region code used by Google Places to format and bias results, for example DE or US.", "default": "" }, "googlePlacesPageSize": { "title": "Google Places results per request", "minimum": 1, "maximum": 20, "type": "integer", "description": "Results requested per official Google Places API call. Lower values provide tighter cost control; Google permits up to 20.", "default": 20 }, "enableGeminiEnrichment": { "title": "Enable Gemini website enrichment", "type": "boolean", "description": "Optionally send bounded public website text to Gemini for grounded summaries, service extraction, customer segments, and a cautious outreach angle. It never discovers contacts or changes the score.", "default": false }, "geminiApiKey": { "title": "Gemini API key", "type": "string", "description": "Required only when Gemini website enrichment is enabled. Create the key in Google AI Studio; it is kept secret and can also be supplied as GEMINI_API_KEY locally." }, "geminiModel": { "title": "Gemini enrichment model", "enum": [ "gemini-2.5-flash-lite", "gemini-2.5-flash" ], "type": "string", "description": "Flash-Lite is the stable low-cost default for high-volume website extraction. Flash is available when you want stronger reasoning at a higher cost.", "default": "gemini-2.5-flash-lite" }, "geminiMaxEnrichments": { "title": "Maximum Gemini-enriched websites", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard maximum number of eligible websites sent to Gemini in this run. Remaining leads keep deterministic crawl data without AI enrichment.", "default": 50 }, "geminiMaxInputChars": { "title": "Gemini website-text limit", "minimum": 1000, "maximum": 50000, "type": "integer", "description": "Maximum cleaned public website characters sent to Gemini for each eligible lead. Lower values reduce cost; 12000 preserves useful homepage and contact-page context.", "default": 12000 }, "geminiMaxOutputTokens": { "title": "Gemini output-token limit", "minimum": 100, "maximum": 2048, "type": "integer", "description": "Maximum Gemini output tokens per website. The Actor requests compact JSON only; a lower limit reduces cost.", "default": 400 }, "geminiConcurrency": { "title": "Concurrent Gemini requests", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum Gemini API calls in flight. Keep this low to avoid rate limits and unexpected spend.", "default": 2 }, "geminiTimeoutSecs": { "title": "Gemini request timeout", "minimum": 5, "maximum": 90, "type": "integer", "description": "Maximum seconds to wait for one Gemini response before it is retried or safely skipped.", "default": 30 }, "geminiRetryCount": { "title": "Gemini retry count", "minimum": 0, "maximum": 3, "type": "integer", "description": "Retries for temporary Gemini rate-limit, timeout, and server errors. Invalid responses are not retried repeatedly.", "default": 2 }, "geminiMinWebsiteChars": { "title": "Minimum text before Gemini", "minimum": 100, "maximum": 10000, "type": "integer", "description": "Skip Gemini when the crawled public website text is shorter than this amount, preventing low-value model calls.", "default": 500 }, "apifyToken": { "title": "Apify token for the nested Maps run", "type": "string", "description": "Provide a token for a nested Google Maps Actor when running locally. On Apify, the platform token is available automatically." }, "googleMapsActorId": { "title": "Google Maps Actor ID", "type": "string", "description": "Used only when Apify Google Maps Actor is selected. The default is the maintained Maps Actor with keywords and location inputs.", "default": "microworlds/crawler-google-places" }, "googleMapsInput": { "title": "Additional Google Maps Actor input", "type": "object", "description": "Optional advanced JSON for the maintained nested Maps Actor. Use keywords (an array), location (a place name), or custom_geolocation (GeoJSON). The scanner supplies your industry and region automatically when these are omitted.", "default": {} }, "googleMapsRunTimeoutSecs": { "title": "Nested Google Maps run limit (seconds)", "minimum": 60, "maximum": 2700, "type": "integer", "description": "Maximum time for one nested Maps Actor run. When it reaches this limit, already-collected map records are retained and this Actor continues with website checks and exports instead of allowing the whole run to hit Apify's one-hour timeout.", "default": 1200 }, "maxCandidatesPerSource": { "title": "Candidate buffer per source", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Discovery buffer before duplicates and low-quality candidates are removed. The Actor automatically raises this to at least five times the qualified-lead target.", "default": 100 }, "maxDiscoveryRounds": { "title": "Maximum discovery rounds", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many rounds each selected discovery source may run while seeking new official website domains. The Actor stops earlier when a round adds no new domains.", "default": 3 }, "maxDiscoveryRequests": { "title": "Maximum discovery requests", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap across discovery API and directory requests. It limits third-party usage and cost; increase it only when the selected sources need more query variants.", "default": 40 }, "maxTotalCandidates": { "title": "Maximum website candidates to inspect", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Hard cap for unique official websites that may be crawled after discovery. It is automatically kept at least five times the qualified-lead target.", "default": 200 }, "crawlDepth": { "title": "Website crawl depth", "minimum": 0, "maximum": 2, "type": "integer", "description": "0 = homepage only; 1 = homepage plus Contact, Imprint, and About pages; 2 = one further level of those high-value internal pages. maxPagesPerWebsite still limits total requests.", "default": 1 }, "maxPagesPerWebsite": { "title": "Maximum pages per website", "minimum": 1, "maximum": 15, "type": "integer", "description": "Maximum number of pages inspected for each company website.", "default": 4 }, "concurrency": { "title": "Concurrent website checks", "minimum": 1, "maximum": 30, "type": "integer", "description": "Number of website checks performed in parallel.", "default": 6 }, "requestTimeoutSecs": { "title": "Request timeout in seconds", "minimum": 5, "maximum": 60, "type": "integer", "description": "Maximum wait time before an HTTP request is skipped.", "default": 20 }, "respectRobotsTxt": { "title": "Respect robots.txt", "type": "boolean", "description": "Use website robots.txt rules when crawling internal pages.", "default": true }, "userAgent": { "title": "Crawler user agent", "type": "string", "description": "Crawler identification string; replace the example contact with your monitored address.", "default": "CarbonLeadScanner/2.0 (+contact: your-email@example.com)" }, "requireHttps": { "title": "Require working HTTPS", "type": "boolean", "description": "Reject websites that do not have a working HTTPS URL.", "default": true }, "verifyDns": { "title": "Verify DNS", "type": "boolean", "description": "Check whether the website domain resolves in DNS.", "default": true }, "verifyMx": { "title": "Verify email-domain MX records", "type": "boolean", "description": "Check mail-domain infrastructure; this does not verify an individual mailbox.", "default": true }, "requireVerifiedMx": { "title": "Require confirmed MX", "type": "boolean", "description": "Reject leads whose public email domain has no usable MX record.", "default": false }, "requireEmail": { "title": "Require a public email for each target lead", "type": "boolean", "description": "When enabled, phone-only businesses are excluded and targetCount means the number of leads with a usable public business email. Disable only when phone-only leads are acceptable.", "default": true }, "allowPersonalEmailProviders": { "title": "Allow personal email providers", "type": "boolean", "description": "Retain Gmail, GMX, Outlook-style and similar personal addresses.", "default": false }, "genericEmailsOnly": { "title": "Keep only generic business inboxes", "type": "boolean", "description": "Keep role inboxes such as info@, contact@, or office@ only.", "default": false }, "requireValidPhone": { "title": "Require plausible phone format", "type": "boolean", "description": "Reject a candidate when its discovered phone number has an implausible length or obviously invalid pattern. This is format validation, not a live call check.", "default": false }, "requireContactMethod": { "title": "Require email or phone", "type": "boolean", "description": "Reject candidates where no usable public email or phone number is found.", "default": true }, "excludeBookingSystems": { "title": "Exclude websites with booking systems", "type": "boolean", "description": "Reject businesses where a booking system is detected.", "default": false }, "detectTechStack": { "title": "Detect website technologies", "type": "boolean", "description": "Collect signature-based CMS and frontend technology signals.", "default": true }, "detectAdPixels": { "title": "Detect advertising and tracking pixels", "type": "boolean", "description": "Collect common Google, Meta, LinkedIn, and TikTok tracking signals.", "default": true }, "extractSocials": { "title": "Extract social profiles", "type": "boolean", "description": "Collect public social profile links from company websites.", "default": true }, "minFitScore": { "title": "Minimum fit score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum 0-100 score a lead must reach to be accepted.", "default": 50 }, "includeRejected": { "title": "Include rejected-candidate audit", "type": "boolean", "description": "Include rejected candidates and their reasons in the audit exports.", "default": true }, "exportFormats": { "title": "Export formats", "minItems": 1, "uniqueItems": true, "type": "array", "description": "Select every standalone file to generate alongside the Apify dataset.", "items": { "type": "string", "enum": [ "json", "csv", "xlsx", "html", "pdf" ], "enumTitles": [ "Structured JSON", "CSV table", "Formatted Excel workbook", "Interactive HTML report", "Executive PDF intelligence report" ] }, "default": [ "json", "csv", "xlsx", "html", "pdf" ] }, "debug": { "title": "Verbose debug logging", "type": "boolean", "description": "Write detailed discovery and crawl diagnostics to the run log.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }