The ScoutedLead API.
Leads from your playbook arrive in your own systems: pulled from a feed, pushed to your webhook, or as a CSV file. Each one carries the reason to reach out and the evidence behind it.
The API is in early access. Keys are issued after a short call about your product and markets.
Prefer to talk? Call or text (616) 585-0206. Leave a voicemail or send a text and Aaron gets back to you.
Three ways to get leads
Pick whichever fits your systems. You can use more than one.
- The delivery feed (pull). Ask for the leads that are ready, oldest first, and mark each one received when it’s safely in your system. Asking twice never creates a duplicate.
- A webhook (push). We POST each lead as JSON to an https address you give us, signed so you can tell it came from us. If your server is down or busy, we try again.
- CSV. A spreadsheet of the same fields, for a team that starts in a spreadsheet or a listing import.
CRM connections come after these, starting with HubSpot. A pilot can start on CSV and move to the feed or the webhook once your team trusts the leads.
What a lead contains
Every lead carries the same core fields, plus the ones your playbook adds:
| Part | What’s in it |
|---|---|
| Business | Name, its own website, city and category |
| Reason | The reason to reach out, in plain words, with the evidence, the page it came from and the date we checked |
| Evidence | Screenshots of what a real browser loaded. In the feed they come as links that expire after an hour |
| Contact | The phone and email the business publishes. An owner’s name only when the site gives their role |
| Context | The platform they use today, and a neighbor comparison when the numbers hold up |
| Extras | A preview link and its expiry date, and drafted first messages, if your playbook uses them |
A lead never contains Google ratings, reviews or opening hours. A field the business’s own website doesn’t state stays empty.
Authentication
Every request is made over HTTPS to https://api.scoutedlead.com with your company’s API key, sent as a Bearer token:
Authorization: Bearer <your key>
An x-api-key header works too. Each company is one tenant with its own key, and a key only ever sees its own runs, leads and deliveries. We show a key once, when we issue it, and store only a hash of it, so a lost key is replaced rather than recovered. A missing or wrong key gets 401.
The main routes
| Route | What it does |
|---|---|
POST /v1/runs | Start a run of your playbook, optionally limited to areas, categories, a list of sites or a number of leads |
GET /v1/runs and GET /v1/runs/{id} | Your runs, newest first, or one run with its progress |
POST /v1/runs/{id}/stop | Stop a run. The leads it already found stay |
GET /v1/deliveries?status=ready | The delivery feed |
POST /v1/deliveries/{id}/ack | Mark a delivery received |
POST /v1/leads/{id}/outcome | Report replied, call booked, won, wrong lead, opted out or bounced |
POST /v1/dnc | Put a domain, email or phone on the do-not-contact list |
GET /v1/health answers without a key. Errors come back as JSON: {"error": "<code>", "detail": "<what went wrong>"}.
Webhook signatures
Each webhook POST carries three headers:
X-ScoutedLead-Delivery: <delivery id>
X-ScoutedLead-Timestamp: <unix seconds>
X-ScoutedLead-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>
v1 is the hex HMAC-SHA256 of the text <t>.<raw body>, keyed with the webhook secret we give you. To check a delivery, compute it over the raw body exactly as received, compare in constant time, and refuse timestamps more than five minutes old. The delivery id stays the same when we retry, so use it to drop duplicates.
Answer with any 2xx when you’ve stored the lead. A 408, a 429 or a 5xx is retried; any other 4xx tells us not to send that delivery again.
Early access
The API is open to a few platforms while we build ScoutedLead with them. Keys are issued after a short call about your product, your markets and where the leads should go. Runs start once your playbook has passed its tests. During early access we work closely with each team: you tell us when a lead was wrong, and that business becomes a test case for every playbook.
We don’t publish prices. We quote after the call, once we know your volume and markets. Request access to start, or read how we check every lead first.
Common questions
Can we run the API without a playbook?
No. A run always belongs to a playbook: the businesses you sell to, the checks that matter for your product, the reasons that count and where the leads go. We write the playbook with you and test it against businesses checked by hand in your vertical. A run can only start once its playbook is active, so nothing reaches your feed before those tests pass.
Will the routes change?
They may, while the API is in early access. The routes on this page are the ones that run today. If one changes, we tell every key holder before it does, and we work through the change with each team. Errors always come back as JSON with an error code and a short explanation, never as a stack trace.
What happens when a business asks us to stop?
Report it with the outcome opted_out and the business goes on ScoutedLead’s do-not-contact list, which every customer’s runs check. You can also send a domain or email straight to POST /v1/dnc. Either way, it won’t come back to you or to any other ScoutedLead customer. Runs and deliveries check the list before anything reaches your feed.