{"uid":"cap__ybhV_WVbim7O5Y8V1rNl","slug":"shovels-api-contractor-building-permit-search-131694ca","name":"Shovels API — Contractor Building Permit Search","description":"Pay-per-call access to the Shovels building-permits search API over x402 and MPP. Search US building permits by date, location, and contractor — no accounts, no subscriptions, pay per request.","url":"https://stable-shovels.dev/api/contractors/search","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"size":{"type":"integer","maximum":100,"minimum":1,"description":"Records to return per page (1–100, default 50). Determines the price — each record returned costs one credit."},"cursor":{"type":"string","description":"Pagination cursor — pass the `next_cursor` from a prior page."},"geo_id":{"type":"string","minLength":1,"description":"Geographic filter: a state code (e.g. \"CA\"), a ZIP code, or a Shovels geolocation id."},"permit_q":{"type":"string","maxLength":50,"description":"Substring search over permit text (max 50 chars)."},"permit_to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Include contractors active on permits starting on or before this date (YYYY-MM-DD)."},"permit_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Include contractors active on permits starting on or after this date (YYYY-MM-DD)."},"permit_tags":{"type":"array","items":{"type":"string"},"description":"Permit tags to include/exclude (prefix with '-' to exclude)."},"include_count":{"type":"boolean","description":"Include a `total_count` of matching contractors (first page)."},"permit_status":{"type":"array","items":{"type":"string"},"description":"One or more of: final, in_review, inactive, active."},"property_type":{"type":"string","description":"Property type (e.g. residential, commercial, industrial)."},"contractor_name":{"type":"string","minLength":3,"description":"Contractor name, partial match (min 3 chars)."},"include_tallies":{"type":"boolean","description":"Include tag/status tallies per contractor (default true)."},"contractor_license":{"type":"string","description":"Contractor license number."},"contractor_website":{"type":"string","description":"Contractor website."},"permit_min_job_value":{"type":"number","minimum":0,"description":"Minimum job value on a permit (USD)."},"contractor_min_inspection_pr":{"type":"number","description":"Minimum lifetime inspection pass rate."},"contractor_min_total_job_value":{"type":"number","minimum":0,"description":"Minimum lifetime job value across all permits (USD)."},"contractor_classification_derived":{"type":"array","items":{"type":"string"},"description":"Derived contractor classifications (must match ALL)."},"contractor_min_total_permits_count":{"type":"integer","maximum":9007199254740991,"minimum":0,"description":"Minimum lifetime permit count."}}},"responseSchema":null,"example":{"request":{"q":"Smith Roofing","size":10,"geo_id":"TX","permit_to":"2023-12-31","permit_from":"2023-01-01"},"response":{"size":10,"items":[{"id":"00G0KfBvkp","dba":null,"sic":null,"name":"CESAR ZELAYA","email":null,"naics":null,"phone":"(832) 986-4461","rating":null,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":null,"revenue":null,"website":null,"tag_tally":{"hvac":1,"remodel":2,"electrical":1},"linkedin_url":null,"permit_count":2,"review_count":null,"status_tally":{"final":2},"avg_job_value":null,"business_name":"ZELAYA CONTRACTORS INC.","business_type":null,"primary_email":null,"primary_phone":"(832) 986-4461","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":null,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":90},{"id":"00IOR7gU7Q","dba":null,"sic":null,"name":"RAGHAVENDRA TORANALU VARADARAJ","email":"raagzcd@gmail.com","naics":null,"phone":"(848) 391-7524","rating":null,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":null,"revenue":null,"website":null,"tag_tally":{"adu":1},"linkedin_url":null,"permit_count":1,"review_count":null,"status_tally":{"final":1},"avg_job_value":null,"business_name":"RAGHAVENDRA TORANALU VARADARAJ","business_type":null,"primary_email":"raagzcd@gmail.com","primary_phone":"(848) 391-7524","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":null,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":180},{"id":"00UYhCsVqO","dba":null,"sic":null,"name":"JOEY WEST","email":null,"naics":null,"phone":null,"rating":5,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":null,"revenue":null,"website":"wtxconstruction.com","tag_tally":{"addition":1},"linkedin_url":null,"permit_count":1,"review_count":null,"status_tally":{"final":1},"avg_job_value":50000,"business_name":"WTX CONSTRUCTION","business_type":null,"primary_email":null,"primary_phone":null,"classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":50000,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":207},{"id":"00Z1AJTvph","dba":null,"sic":null,"name":"MARIA WEATHERS","email":"metafoya1@yahoo.com","naics":null,"phone":"(915) 422-9030","rating":null,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":"14-LP-00262","revenue":null,"website":"metafoyainc.com","tag_tally":{"roofing":1},"linkedin_url":null,"permit_count":14,"review_count":null,"status_tally":{"final":1},"avg_job_value":2080000,"business_name":"M. E. TAFOYA ENTERPRISES INC.","business_type":null,"primary_email":"metafoya1@yahoo.com","primary_phone":"(915) 422-9030","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":29120000,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":24},{"id":"00aPTOiM0z","dba":null,"sic":null,"name":"BEST ROOFING & REMODELING","email":"bestroofingremodeling@gmail.com","naics":null,"phone":"(254) 366-5753,(254) 732-2400","rating":null,"address":{"city":"WACO","state":"TX","county":null,"latlng":[31.586771,-97.085208],"street":"PARADISE ISLAND RD","zip_code":"76705","street_no":"4007","address_id":"K7iog7ge5IM","jurisdiction":null,"zip_code_ext":"7408"},"license":null,"revenue":null,"website":null,"tag_tally":{"roofing":2},"linkedin_url":null,"permit_count":35,"review_count":null,"status_tally":{"final":2},"avg_job_value":114143,"business_name":"BEST ROOFING & REMODELING","business_type":null,"primary_email":"bestroofingremodeling@gmail.com","primary_phone":"(254) 732-2400","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":3995000,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":30},{"id":"00za3Xmfet","dba":null,"sic":null,"name":"JESUS SALGADO","email":"salgado4763@gmail.com","naics":null,"phone":"(817) 204-9146","rating":5,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":"RB025707","revenue":null,"website":"salgadosfencingtx.com","tag_tally":{"adu":1},"linkedin_url":null,"permit_count":1,"review_count":null,"status_tally":{"final":1},"avg_job_value":400000,"business_name":"SALGADOS FENCING LLC","business_type":null,"primary_email":"salgado4763@gmail.com","primary_phone":"(817) 204-9146","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":400000,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":0},{"id":"01F8Z8UARQ","dba":null,"sic":null,"name":"KENNETH DONAGHY","email":"ken@goodcontractorsroofing.com","naics":"236","phone":null,"rating":5,"address":{"city":"FORT WORTH","state":"TX","county":null,"latlng":[32.725572,-97.344788],"street":"PARK PLACE AVE","zip_code":"76110","street_no":"1617","address_id":"K9MuECgZvso","jurisdiction":"FORT WORTH","zip_code_ext":"1300"},"license":"RB023887","revenue":"Under 1 Million","website":"goodcontractorsroofing.com","tag_tally":{"hvac":1,"remodel":1,"roofing":2},"linkedin_url":"linkedin.com/company/goodcontractorsroofing","permit_count":4,"review_count":null,"status_tally":{"final":3},"avg_job_value":21274925,"business_name":"GOOD CONTRACTING ROOFING LLC","business_type":null,"primary_email":"ken@goodcontractorsroofing.com","primary_phone":null,"classification":null,"employee_count":"1 to 10","first_seen_date":null,"total_job_value":85099700,"license_act_date":null,"license_exp_date":null,"primary_industry":"Building Construction","license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":123},{"id":"01JUL3f5q5","dba":null,"sic":null,"name":"CHRISTOPHER MIRANDA","email":null,"naics":null,"phone":"(512) 215-1583","rating":null,"address":{"city":"LEANDER","state":"TX","county":null,"latlng":[30.544123,-97.857267],"street":"OAK HOLLOW DR","zip_code":"78641","street_no":"1209","address_id":"K6xHRTyFHoU","jurisdiction":null,"zip_code_ext":"2381"},"license":null,"revenue":null,"website":null,"tag_tally":{"adu":2,"gas":2,"kitchen":1,"remodel":3,"addition":6,"plumbing":8,"generator":2,"demolition":2,"window_door":2,"new_construction":6,"pool_and_hot_tub":3},"linkedin_url":null,"permit_count":510,"review_count":null,"status_tally":{"final":14},"avg_job_value":7820012,"business_name":"GREATER AUSTIN PLUMBING","business_type":null,"primary_email":null,"primary_phone":"(512) 215-1583","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":62560100,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":281},{"id":"01KHOkhPiX","dba":null,"sic":null,"name":"EPL LAKEWAY","email":null,"naics":null,"phone":null,"rating":null,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":null,"revenue":null,"website":null,"tag_tally":{"remodel":1},"linkedin_url":null,"permit_count":1,"review_count":null,"status_tally":{"final":1},"avg_job_value":5000000,"business_name":"BLD CONSTRUCTION LLC","business_type":null,"primary_email":null,"primary_phone":null,"classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":5000000,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":161},{"id":"01L313GG0f","dba":null,"sic":null,"name":"SANDRA GASTELUM","email":null,"naics":null,"phone":"(915) 203-3171","rating":null,"address":{"city":null,"state":"TX","county":null,"latlng":[null,null],"street":null,"zip_code":null,"street_no":null,"address_id":null,"jurisdiction":null,"zip_code_ext":null},"license":"23-LP-00461","revenue":null,"website":null,"tag_tally":{"adu":1},"linkedin_url":null,"permit_count":1,"review_count":null,"status_tally":{"final":1},"avg_job_value":0,"business_name":"SANDRA GASTELUM","business_type":null,"primary_email":null,"primary_phone":"(915) 203-3171","classification":null,"employee_count":null,"first_seen_date":null,"total_job_value":0,"license_act_date":null,"license_exp_date":null,"primary_industry":null,"license_inact_date":null,"license_issue_date":null,"classification_derived":null,"avg_inspection_pass_rate":null,"avg_construction_duration":60}],"next_cursor":"VFg.01L313GG0f.55W.ZIaOydFtLL0","total_count":null}},"exampleRequest":{"q":"Smith Roofing","size":10,"geo_id":"TX","permit_to":"2023-12-31","permit_from":"2023-01-01"},"tags":["x402"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.5","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.5","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_1kmmGO-r2FSSKkNMsNocs","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.5","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Search US building permits by contractor name, date range, and location via a pay-per-call API with no subscription required","exampleAgentPrompt":"Search Shovels for all building permits filed by contractors named 'Smith Roofing' in Texas between January 1 2023 and December 31 2023.","exampleUseCases":null,"resultDescription":"A list of matching US building permit records including contractor details, permit dates, permit types, and location data for permits matching the search criteria","failureModes":["Payment not processed — 402 response if USDC payment is missing or insufficient","No results found — empty results array if no permits match the search criteria","Invalid location parameter — error if location is not a recognized US address, city, or zip code","Invalid date range — error if date format is incorrect or range is illogical","Rate limiting or server error — 5xx response under heavy load"],"whenToPreferThis":"Use this endpoint when you need on-demand, no-subscription access to US building permit data searchable by contractor, location, and date — ideal for one-off lookups or agents that need permit data without committing to a recurring API plan. Prefer this over subscription APIs when call volume is low or unpredictable.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":1,"lastUsedAt":"2026-07-15T14:37:27.013Z","lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T12:55:36.511Z","isFirstParty":false}