Shovels
US building-permit and contractor data for construction/trades sourcing. BYOK-only on Hyreflow. Key gotcha: everything keys off a geo_id.
Reach for Shovels when you're sourcing or recruiting in construction and the trades (electrical, HVAC, roofing, solar) — it turns US building-permit and contractor data into directly-contactable individuals and active, growing firms.
Shovels is BYOK-only — it isn't resold on managed credits. Bring your own Shovels key;
calls are free on Hyreflow (you pay Shovels directly). size is still your usage dial on
their side — search_contractors and the detail sub-trees bill per record on your Shovels account.
Capabilities
Cost below is on your own Shovels account (BYOK-only) — Hyreflow charges 0 credits for every Shovels call.
| Tool | Does | Shovels-side cost |
|---|---|---|
shovels_search_addresses | Resolve an address → geo_id | Metered |
shovels_search_cities | Resolve cities → geo_ids | Metered |
shovels_search_permits | Permit activity (hiring signal) for a geo + date range | Metered |
shovels_search_contractors | Active contractors in a geo + date range (candidates / BD targets) | ~1 record / result |
shovels_get_contractor_employees | Per-firm roster: named staff with role, seniority, dept, email, LinkedIn | Likely per-record — gate size |
shovels_get_contractor_permits | All of a contractor's permits | Per permit — cost trap |
shovels_list_tags | Valid permit/trade tags (use before filtering by trade) | Metered |
shovels_get_usage | Balance / credits used | Free |
Guidance
geo_idfirst, always. Resolve the place withsearch_addresses/search_cities/etc., then passgeo_idto the searches.search_permitsandsearch_contractorsboth REQUIREgeo_id+permit_from+permit_to(YYYY-MM-DD).- Record richness scales with firm size: established firms return email (often comma-multi-value — parse the non-free-mail one for the corporate domain),
linkedin_url, phone, revenue,employee_count; solo operators return only name + phone + trade → enrich those externally. get_contractor_employeesis the candidate goldmine — full individual records (name, title, seniority, dept, personalemail,linkedin_url). Candidate outreach uses the personalemail; BD usesbusiness_email. Ask the customer which before pulling. Unverified/inferred endpoint — pilot before relying on it.- EEO hard rule: the employee record carries a consumer overlay (gender, age, marital/parental status, income). NEVER filter or screen candidates on these. Use only title / seniority / department / location / skills.
- Trade is an enum, not free text —
classification_derived="solar"returns 0. Discover valid values vialist_tagsfirst. - Cost traps (on your Shovels account):
get_contractor_permitsreturns ALL permits billed per record; gate it — this is also an unverified/inferred endpoint, pilot before relying on it.get_contractor/get_contractor_metricspaths are unverified — use search results instead.
hyreflow tools execute shovels shovels_search_contractors \
--payload '{"geo_id":"<geo_id>","permit_from":"2026-01-01","permit_to":"2026-06-01","size":25}'Run shovels_get_usage and a 0-result or small-size pilot before any bulk pull — a 0-result search costs 0, and size is the only cost dial on contractor calls.