From search to your workflow.

What works today

Reviewed 13 October 2026 against the current code and live beta. Real Philippine province/country jobs and Excel, CSV and JSON downloads have been tested on Azure. Examples below are request instructions or schema descriptions, not invented business results.

Third-party setup recipes were checked against official documentation. They have not been run inside your n8n, Make, Zapier, HubSpot or Sheets accounts. Your account permissions, mapping and any platform fees still apply. LeadMaps adds no connector surcharge; collection credits still apply.

Your first collection

Start with 5–10 leads and inspect their source links, location and contacts before expanding. Maximum leads is a cap, not a promise of that many matches. No exhaustive coverage, speed or email hit-rate guarantee is made.

1. Sign in with Google. A new account receives 50 one-time collection credits; existing accounts keep their balance. Paid checkout is closed during beta.
2. Open New collection. Choose one to eight categories, use the examples or specify your own. Categories are search terms; result classification is not a strict industry taxonomy guarantee.
3. Choose country and scope: whole country, province/state or city. Only the chosen scope needs those location fields. US city/region searches also need a valid state.
4. For each detail choose Don’t collect, Include when available, or Require on every lead. Required phone excludes records without phone; the same rule applies to website, email, socials and rating.
5. Set Maximum leads within your available credits. Review scope, categories, required contacts and maximum charge before confirming.
6. Follow actual counts in Collections. Closing the browser does not stop the job. Cancellation is processed when the worker next checks; completed records remain saved.
7. Open All businesses, choose a list, search/filter/sort, optionally select rows, then preview/export. Edit notes, tags and workflow status beside your leads.

Search fields and coverage

Country searches combine a bounded set of location queries. They are not exhaustive, statistically random or geographically balanced. Source-address/country/region matching excludes uncertain results. Review a small sample for ambiguous names and non-Latin locations.

Contact extraction visits the listed public website and up to two relevant contact/about pages within a budget. Access restrictions stop extraction. Social links come from available source/website content; no logged-in social scraping. Contacts remain found/unverified: no deliverability check or consent guarantee.

Website can be a social page. Phone normalization preserves international prefixes when possible; some source numbers remain unchanged. Source category and business status can be incomplete. Review closed businesses yourself before use.

Record field dictionary

Credits and job states

One credit buys one unique business delivered within the confirmed job. Missing optional email still counts; missing required details excludes the record. Reserve the maximum before starting and release unused credits when the job ends. Duplicates/retries within that job do not charge again.

One queued/running job per workspace. No automatic overage. Viewing saved results and re-exporting do not consume collection credits; an explicit fresh collection is a new operation.

Proposed paid-plan rules: expiring monthly credits consumed before non-expiring prepaid credits; monthly credits reset without rollover. Purchases are not enabled yet.

Counts: discovered, accepted, duplicates, excluded and incomplete (completeness below 100). Strict requirements can deliver zero leads within the search budget.

Exports and templates

Excel has frozen headers, filters, alternating rows and a Read me sheet. A Contact sources sheet is included except for Calling List and CRM Import. Phones/postal codes remain text; dates use date cells.

CSV is UTF-8 with a BOM and protects formula-like values with a leading apostrophe, including + phone prefixes. Prefer XLSX/JSON for exact phone text. JSON contains schemaVersion, generatedAt, count and records, with arrays and nulls preserved.

Exports follow filters/sort and selected records. Hiding workspace columns does not customize template columns. Generated files expire after seven days; authenticated links expire after five minutes. Regenerate from saved results when needed. Inactive free-account datasets may be removed after 30 days; see Privacy.

API: authenticate and create a job

Base URL: https://leadmaps.live/api/v1. All authenticated clients share a 180-request/60-second workspace limit. Never put your key in browser code, query strings or public repositories. Use your automation platform’s private credential storage.

For whole-country searches use scope: country and omit city/region. City scope requires city (e.g. Tuguegarao City), with region to disambiguate (e.g. Cagayan); US city scope must include a valid state.

1. Workspace → Integrations → API keys & Codex. Name the key and choose minimum scopes. read, collect, export are selected by default; write/integrations are opt-in. Copy once and keep it private. Revoke unused keys from this screen.
2. First test GET https://leadmaps.live/api/v1/me with Authorization: Bearer KEY. It returns identity, available/monthly/reserved credits, verified, googleConnected, liveEnabled, paidEnabled and ghlEnabled. No collection charge.
3. Review the JSON search below. POST /jobs with Content-Type: application/json, Authorization, and Idempotency-Key. This example reserves up to 10 credits. Keep the returned job id.
4. Retry the exact same submission with the same request key; use a new key for a different search. Changed parameters under an existing key return 409. Poll GET /jobs/{id} until terminal.

# Bash: set LEADMAPS_API_KEY privately first.
curl 'https://leadmaps.live/api/v1/me' \
  -H "Authorization: Bearer $LEADMAPS_API_KEY"

# Windows PowerShell: use a privately configured environment variable.
$headers = @{ Authorization = "Bearer $env:LEADMAPS_API_KEY" }
Invoke-RestMethod 'https://leadmaps.live/api/v1/me' -Headers $headers

# Job request (review before sending)
POST https://leadmaps.live/api/v1/jobs
Authorization: Bearer YOUR_PRIVATE_KEY
Content-Type: application/json
Idempotency-Key: your-reviewed-isabela-request-001

{
  "categories": ["Restaurants", "Coffee shops"],
  "scope": "region", "country": "PH", "region": "Isabela",
  "limit": 10, "fields": ["phone", "website", "email", "rating"],
  "requiredFields": ["phone"], "preset": "all", "confirmed": true
}

API endpoint reference

All paths follow /api/v1. Replace {id} with your resource id. Job/webhook ids are UUIDs; lead ids are record identifiers. Mutation bodies are JSON. Keys are managed only from the signed-in browser, not another API key.

Pagination, export selection and downloads

GET /leads accepts jobId, page (zero-based integer), search (name/city/category/tags), filter (has-email, has-phone, no-website, incomplete), list, sort (completeness, name, rating). Default completeness/rating sorts descend, then name, then id. No arbitrary-column or status filter exists here. GET does not accept an ids array.

Keep the same query/sort and increment page until (page + 1) × pageSize ≥ total. Prefer a terminal job so records do not change between pages. Export bodies accept jobId, ids (up to 10,000), search, filter, list, sort, format (xlsx,csv,json) and template.

Resolve the returned export url against https://leadmaps.live. Request it with the same export-scoped bearer key, with redirects disabled. Azure returns a short-lived Location URL; fetch that storage URL separately WITHOUT forwarding your bearer key to storage. Do not publish the signed URL.

GET /api/v1/jobs/YOUR_JOB_UUID
GET /api/v1/leads?jobId=YOUR_JOB_UUID&page=0&sort=name

POST /api/v1/exports/preview
POST /api/v1/exports
{
  "jobId": "YOUR_JOB_UUID", "format": "xlsx",
  "template": "Calling List", "sort": "name"
}

API errors and scopes

read reads jobs/results/settings and preview. collect creates/cancels jobs. export previews/generates files and authorizes download. write updates annotations/views. integrations manages webhook/GHL connections and sync. Keys cannot create/revoke other keys. Sessions belong to the website; automate using bearer keys.

Choose your connection path

Use file exports for a finished list, REST polling for repeatable automation, or the local MCP bridge for an assistant. Each external tool needs its own account access. Google sign-in authenticates LeadMaps only; it does not grant Drive or Sheets access.

Give each workflow a separate scoped key. Store request key/job id durably, separate polling from collection creation, deduplicate destination writes by LeadMaps id, and verify actual destination rows. Do not invent personal names from company listings.

GoHighLevel: awaiting live enablement

The native connector is disabled in the current live beta. Mapping is tested locally, but no real GHL destination sync has passed. These steps describe an enabled pilot; contact us to arrange one before relying on it.

GHL upsert matching depends on the location’s duplicate settings. LeadMaps claims a lead submission before sending: synced indicates a successful API response; already-submitted prevents repeat sending; rejected indicates a non-success response; unknown is an ambiguous network outcome. Rejected/unknown records are not automatically resubmitted. Reconcile the actual CRM before asking support to retry. Disconnect does not reset submission history or delete CRM data.

1. Use an eligible GHL sub-account/location. Create a Private Integration token with locations.readonly and contacts.write; contacts.readonly is useful for inspecting pilot contacts. Do not use a legacy agency API key.
2. When enabled, enter token and exact location ID in LeadMaps Integrations. The server checks location access before encrypting/saving credentials.
3. Select 1–100 leads and preview Sync to GHL. Check destination workflows before confirmation; contact upsert can update records and trigger automations.
4. Test one record first. Verify it inside GHL and inspect sync outcomes before expanding. Disconnect in LeadMaps and revoke the GHL token when no longer needed.

n8n / Make / Zapier: shared recipe

These are generic HTTP recipes based on official platform documentation, not native integrations or account-tested automations. Your plan must permit the HTTP actions. Polling is recommended instead of relying exclusively on beta completion webhooks.

1. Test GET /me with a read key first, without spending collection credits.
2. POST one reviewed /jobs request with collect scope, JSON body and persistent Idempotency-Key. Store returned id; never generate a new key for a transport retry.
3. Use a bounded status-check workflow: wait 10–15 seconds between GET /jobs/{id}; branch on terminal states. A single delay is not proof of completion.
4. For completed/partial/cancelled jobs, fetch /leads?jobId=…&page=0, iterate records and increment page until total is covered.
5. Map name to company name, phone, emails[0] only when present, website/address/city/country. Deduplicate with id. Verify small test outputs in the actual destination before scaling.

n8n setup

1. Add HTTP Request. GET https://leadmaps.live/api/v1/me. Use Generic Credential → Header Auth: Authorization with value Bearer followed by your private key.
2. For job submission set POST /api/v1/jobs, JSON body from the API section, and an Idempotency-Key header. Keep auth in the credential store.
3. Use Wait and IF nodes for bounded polling. Preserve the job id between nodes. Read actual output before writing expressions.
4. Results are under records, not the top-level response. Split that array into items before the destination node; increment page and stop based on total/pageSize. Keep certificate validation enabled.

Make setup

1. Add HTTP → Make a request with GET https://leadmaps.live/api/v1/me. Configure secure header/API-key credentials for Authorization: Bearer KEY.
2. For /jobs use POST, Content-Type: application/json, Idempotency-Key, JSON body. Enable parsed response and store id durably.
3. Use a separate scheduled status-check scenario or bounded polling route. An Iterator processes records; advance page until total is covered. Map destination fields explicitly.

Zapier setup

Do not treat a Catch Hook payload as trusted completion unless your receiver verifies the exact raw body/timestamp/signature. Use the polling recipe if those are unavailable.

1. Use Webhooks by Zapier → Custom Request, method GET for /me and header Authorization: Bearer KEY. Keep credentials and task history access private.
2. For /jobs choose POST, Data as JSON body, Content-Type: application/json and Idempotency-Key headers. Store returned job id in your durable storage/table.
3. Use a separate scheduled checker to poll terminal jobs, then loop over records and subsequent pages. Do not assume one Delay means collection finished.

HubSpot company imports

1. Export CRM Import CSV/XLSX and inspect it. In HubSpot start a file import for Companies.
2. Map Company Name → Name, Website → Website URL, Phone → Phone number, Address → Street address, and City/State/Postal Code/Country to the matching company properties.
3. Map Email/Tags only to appropriate existing/custom properties. Do not silently import business listings as named people; first/last names are not supplied.
4. For repeat imports use HubSpot Record ID or a suitable unique company property. Website is a full URL, not a dedicated Company domain name column. If using domain matching, add/review that column yourself and watch for franchises sharing domains.
5. Review mapping errors and duplicates inside HubSpot. This is manual import, not continuous sync.

Google Sheets imports

No native Sheets OAuth connector is available. IMPORTDATA cannot fetch a private authenticated export link, and that link expires. Google sign-in is not permission to write spreadsheets.

1. Download XLSX for structured sheets or CSV for a flat table. In Sheets use File → Import → Upload, choose the file and destination. Or upload XLSX to Drive and open with Sheets.
2. For CSV disable automatic conversion to numbers/dates/formulas when offered; inspect Phone/Postal Code columns. CSV protection may leave a literal apostrophe before + phones; prefer XLSX for exact formatting.
3. Check Unicode, leading zeros and phone prefixes. Apply frozen headers/filters if import did not preserve them.

Codex: local MCP bridge

This is a local stdio server in the LeadMaps project, not a hosted URL. You need Node.js, the supplied project/bridge source, installed dependencies, a compatible MCP client and a private key. No public npm package/self-service bridge download exists yet; request source/setup through Contact us if needed.

LEAD_STUDIO_URL and LEAD_STUDIO_API_KEY are the bridge’s exact current environment names. LEADMAPS_* will not work here. Configuration uses forward slashes in Windows paths. The sample calls the already-installed tsx CLI directly, avoiding npx prompts/downloads.

A protocol test is not proof your particular Codex installation is connected. No hosted ChatGPT OAuth integration or directory app is available.

1. Install dependencies with npm ci in the provided project folder. Check node runs from your terminal.
2. Create a read/collect/export key (or read only for inspecting results). Add config below to your user MCP configuration, preserving existing entries. Replace both absolute paths and the private key.
3. Refresh/restart the client’s MCP connections and check the six tools appear. Try read_results or collection_status for a job you own first; no collection credits consumed.
4. Before create_collection, confirm categories, scope, country/city/region, required contacts, limit and maximum charge. Reuse idempotencyKey for retries.

[mcp_servers.leadmaps]
command = "node"
args = ["C:/LeadMaps/node_modules/tsx/dist/cli.mjs", "C:/LeadMaps/src/server/mcp.ts"]

[mcp_servers.leadmaps.env]
LEAD_STUDIO_URL = "https://leadmaps.live"
LEAD_STUDIO_API_KEY = "REPLACE_WITH_YOUR_PRIVATE_SCOPED_KEY"

Completion webhooks: beta limits

Polling is recommended for dependable beta automation. Endpoint registration and signed delivery are implemented, but the Azure event worker wakes for collection jobs. Pending retries do not independently wake it; a later worker run may process them. Nominal retry intervals are not a timing guarantee. A dedicated retry trigger is needed before webhooks can be relied on alone.

POST /api/v1/webhooks with {url:yourPublicHttpsUrl}, using integrations scope. Save secret immediately, shown once; this is the signing secret, not your API key. GET /webhooks gives endpoint id; DELETE /webhooks/{id} removes it.

Payload: {id:deliveryUUID,type:'job.finished',jobId:jobUUID,status:terminalStatus,accepted:integer,occurredAt:ISOtimestamp}. Header names remain X-Lead-Studio-Timestamp (Unix seconds) and X-Lead-Studio-Signature (lowercase hex) for compatibility.

Verify HMAC-SHA256 of timestamp + period + exact raw UTF-8 request body, before JSON parsing. Reject missing/malformed headers and timestamps more than five minutes away, including future timestamps. Compare fixed-size buffers in constant time. Reserializing parsed JSON changes the signed bytes.

Persist the verified event and deduplicate by id before responding 2xx. Duplicate verified events should also get 2xx. Up to five total attempts (initial + four retries), nominal backoff 30/60/120/240 seconds while a worker is available. Private-network hosts, URL credentials, nonstandard ports and webhook redirects are rejected. No retry timing SLA, replay button or delivery dashboard is available.

// Node.js receiver helper, before parsing the exact raw body.
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, timestamp, signature, signingSecret) {
  if (!/^\d+$/.test(timestamp || '') || !/^[a-f0-9]{64}$/.test(signature || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', signingSecret)
    .update(timestamp + '.' + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

Troubleshooting

For help provide job id, approximate time, scope, error text and failing platform step through Contact us. Never send API keys, OAuth secrets or integration tokens. Data removal requests need the source listing link.

Official platform references

Checked on 13 October 2026. Platform screens and plan entitlements can change; follow their current requirements.

• GHL Private Integrations
• GHL contact upsert
• n8n HTTP Request
• Make HTTP
• Zapier outgoing webhooks
• HubSpot imports
• Google Sheets imports
• Codex MCP

Contact us · Privacy & retention · Data removal