# Shovels API — Contractor Building Permit Search

> Shovels API — Contractor Building Permit Search is a paid API for AI agents from stable-shovels.dev, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-15).

Search US building permits by contractor name, date range, and location via a pay-per-call API with no subscription required

## Facts

- Endpoint: POST https://stable-shovels.dev/api/contractors/search
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 1
- Tags: x402
- Canonical page: https://www.zero.xyz/c/shovels-api-contractor-building-permit-search-131694ca
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap__ybhV_WVbim7O5Y8V1rNl

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability shovels-api-contractor-building-permit-search-131694ca -d '<json body>'
```

Example prompt: Search Shovels for all building permits filed by contractors named 'Smith Roofing' in Texas between January 1 2023 and December 31 2023.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

A list of matching US building permit records including contractor details, permit dates, permit types, and location data for permits matching the search criteria

## Example request

```json
{
 "q": "Smith Roofing",
 "size": 10,
 "geo_id": "TX",
 "permit_to": "2023-12-31",
 "permit_from": "2023-01-01"
}
```

## Request schema (JSON Schema)

```json
{
 "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_classificat
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/shovels-api-contractor-building-permit-search-131694ca/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from stable-shovels.dev](https://www.zero.xyz/host/stable-shovels.dev/llms.txt)