# Skip the Gatekeeper — local-business lead discovery & enrichment

Given a niche + city, Skip the Gatekeeper searches Google Maps and enriches each business with
owner name, domain-checked emails, phone line type (mobile/landline/voip) + carrier, social
profiles, and crawled website pages, then returns a CSV.

Base URL: {{API_BASE_URL}}

## Auth
Ask the user for their Skip the Gatekeeper API token (starts with lb_at_). Send it on every call:
  Authorization: Bearer lb_at_xxxxxxxx
Never print or log the token.

## Flow (async: start -> poll -> download)

1) Start a run (depth caps businesses, 1-700):
   curl -s -X POST "{{API_BASE_URL}}/api/runs" \
     -H "Authorization: Bearer $API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"keyword":"plumber","location":"Austin, Texas","depth":50}'
   -> {"ok":true,"run_id":"01...","status":"queued"}

2) Poll until status is "done" (polling is free):
   curl -s "{{API_BASE_URL}}/api/runs/RUN_ID" -H "Authorization: Bearer $API_TOKEN"
   -> {"status":"running","total":50,"enriched":31,"failed":0,"credits_charged":31,...}

3) Download the CSV once done:
   curl -s "{{API_BASE_URL}}/api/runs/RUN_ID/results.csv" \
     -H "Authorization: Bearer $API_TOKEN" -o leads.csv

   Add ?format=simple|advanced|ghl|instantly for a short, import-ready layout.
   Or get JSON: GET /api/runs/RUN_ID/results?limit=100&offset=0
   (page text is omitted unless you add &include=pages).

## The field to read first
"Decision Maker Email" is the address that reaches a person rather than a front desk.
It is deliberately EMPTY when the business only publishes info@ - that absence is the
answer, not a gap. "Primary Email Type" is owner | personal | role.

## Other endpoints
GET /api/runs -> list your runs, newest first (?limit= up to 200).
GET /api/locations?q=springfield -> up to 8 ranked matches with location_code. Free.
   Call this first when a location is ambiguous: the wrong Springfield spends real
   credits on the wrong city and looks like it worked.
POST /api/enrich -d '{"domains":["acme.com"]}' (max 10) - enrich a list you already
   have, no Maps search. Returns a normal run_id.
/api/demo/* - every route above with NO token and NO credits, returning fixtures.
   Build against these first. Add ?status=running to drive any polling state.

## Credits
1 credit per enriched business; permanent failures are refunded (net zero).
Check balance: GET {{API_BASE_URL}}/api/credits -> {"balance":1234,...}
If a run's note is "credit_capped", buy more credits from the dashboard.

## Webhook (skip the polling)
Pass "callbackUrl" (a public https URL) when starting a run and we POST it once when
the run reaches a terminal state (done or error) — no polling needed:
   -d '{"keyword":"plumber","location":"Austin, Texas","callbackUrl":"https://you.example.com/hook"}'
   -> {"ok":true,"run_id":"01...","webhook_signing_secret":""}
The POST body is the same summary as GET /api/runs/:id ({event:"run.completed", run_id,
status, total, enriched, failed, credits_charged, completed_at}). Verify authenticity:
the header "X-STG-Signature: sha256=" is HMAC-SHA256(webhook_signing_secret, raw_body).
The signing secret is stable per account and returned whenever you register a callback.
A private/loopback callbackUrl is rejected (422) — the URL must be publicly routable.

## Notes
- depth (1-700) caps the run; start small (10-50), then scale. Each enriched business = 1 credit.
- Enrichment is async — poll the run OR register a callbackUrl (above); don't expect results in the POST response.
- Errors: {"error":{"code":"..."}} with status 401 (bad token) / 403 (missing capability) / 422 (location or callback) / 429 (rate limit).