Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., ‘installing’ matches ‘install’). Multi-word queries use AND semantics (e.g., ‘solar panel’ finds permits mentioning both words). NOTE: Contractors are ordered by the start date of the most recent permit on which they worked.
GET
/
contractors
/
search
Search Contractors
curl --request GET \
--url https://api.shovels.ai/v2/contractors/search \
--header 'X-API-Key: <api-key>'
When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'.
include_tallies
boolean
default:true
Include tag and status tallies in response. Tallies are the only aggregate fields scoped to the search filters (permit_count, avg_job_value and total_job_value are lifetime totals), so they are the way to count a contractor's permits within the searched area and date range. Set to false to omit tally computation for faster response times when tallies are not needed.
permit_from
string<date>
required
Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: YYYY-MM-DD
permit_to
string<date>
required
Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: YYYY-MM-DD
permit_q
string | null
Search permit descriptions. Permits search uses case-insensitive substring matching, including partial words. Contractors search uses full-text search with English stemming. For example, installing matches install. Multi-word contractor queries require all words after English text processing. For example, solar panel requires both solar and panel.
Maximum string length: 50
permit_status
string[]
Filter by one or more statuses: final, in_review, inactive, active.
Maximum array length: 4
permit_min_approval_duration
integer | null
Filter by the minimum permit approval duration in days.
permit_min_construction_duration
integer | null
Filter by the minimum project construction duration in days.
permit_min_inspection_pr
integer | null
Filter by the minimum inspection pass rate.
permit_min_job_value
integer | null
Filter by the minimum job value, in cents (e.g. 5000000 = $50,000).
permit_min_fees
integer | null
Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000).
permit_tags
string[] | null
Filter by one or more tags. Use '-' prefix to exclude tags. Example: ?permit_tags=solar&permit_tags=-roofing (has solar, not roofing). Tags match against the contractor's aggregated permit history in the searched area: every included tag must appear somewhere in that history, and different permits may contribute different tags. An excluded tag drops the contractor if any permit in that history ever had it. The date filter does not restrict which tags count; the tag history is an all-time aggregate.
geo_id
string
required
Filter results by geographic area. Accepts:
US state code (e.g. CA)
ZIP code (e.g. 90210 or 90210-1234)
Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. a4xysKbZwqg)
Resolve addresses and places to geolocation IDs via:
Free-form text such as "123 Main St" is not accepted.
property_type
string[] | null
Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. ?property_type=residential&property_type=commercial).
property_min_market_value
integer | null
Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000).
property_min_building_area
integer | null
Minimum total building area in sq ft.
property_min_lot_size
integer | null
Minimum size of the property lot in sq ft.
property_min_story_count
integer | null
Minimum number of property stories.
property_min_unit_count
integer | null
Minimum number of property units
contractor_classification_derived
string[] | null
Filter by derived contractor classifications. Use '-' prefix to exclude. Example: ?classification_derived=electrical&classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.
contractor_name
string | null
Filter by contractor's name or business name (partial match supported). Must be at least 3 characters — shorter patterns cannot use the trigram index and would force a sequential scan.
Minimum string length: 3
contractor_website
string | null
Filter by contractor's website prefix. Surrounding whitespace is trimmed and input is lowercased. Leading http://, https://, and www. prefixes and trailing slashes are removed. Paths are retained. A value that is empty after normalization applies no website filter.
contractor_min_total_job_value
integer | null
Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000).
contractor_min_total_permits_count
integer | null
Minimum lifetime permits count.
contractor_min_inspection_pr
integer | null
Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive.
contractor_license
string | null
Filter by the contractor's license
Response
A list of contractors.
Schema for paginated contractors details response.
items
ContractorsRead · object[]
required
The list of items returned in the response following given criteria.
Show child attributes
size
integer
required
The number of items returned in the response.
next_cursor
string | null
required
The cursor for retrieving the next page of results.
total_count
TotalCount · object | null
Top-level count object, not an integer: {"value": 970, "relation": "eq"}. "eq" means an exact count up to 10,000. "gte" means at least 10,000 matches, with value set to 10,000. Counted only when requested on the first page without a cursor. null when not requested, on later pages, or when the count query times out.
Show child attributes
Example:
{ "relation": "eq", "value": 970 }
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Shovels Documentation","colors":{"primary":"#01654D","light":"#E8BD51","dark":"#01654D"},"logo":{"light":"https://mintcdn.com/shovelsai/RpZdSdGGx61eI0yq/assets/shovels-logo.png?fit=max\u0026auto=format\u0026n=RpZdSdGGx61eI0yq\u0026q=85\u0026s=4580f7cd0725b33ba31367d40fda3bbf","dark":"https://mintcdn.com/shovelsai/1PwAyN7q-VPDJL6r/assets/shovels-logo-dark.png?fit=max\u0026auto=format\u0026n=1PwAyN7q-VPDJL6r\u0026q=85\u0026s=48cea9b3276127273eefe9d0d6d9b0b8","href":"https://www.shovels.ai"},"favicon":"https://mintcdn.com/shovelsai/RpZdSdGGx61eI0yq/assets/favicon.png?fit=max\u0026auto=format\u0026n=RpZdSdGGx61eI0yq\u0026q=85\u0026s=fd9ec8e38b5dd0ef58cf2d43fdc71ec3","api":{"playground":{"display":"interactive"},"examples":{"languages":["curl","python","java","go","ruby","php"]},"mdx":{"server":"https://api.shovels.ai/v2"}},"background":{"color":{"light":"#fcfbf8","dark":"#101727"}},"navbar":{"links":[{"href":"mailto:support@shovels.ai","label":"Contact Support"}],"primary":{"type":"button","label":"Free Trial","href":"https://app.shovels.ai/login?mode=register"}},"footer":{"socials":{"discord":"https://discord.gg/Nypja3cKDx","github":"https://github.com/shovelsai","linkedin":"https://linkedin.com/company/shovels"}},"seo":{"metatags":{"og:site_name":"Shovels Documentation","og:type":"website","og:image":"https://docs.shovels.ai/assets/shovels-logo.png","twitter:card":"summary_large_image","twitter:site":"@shovelsai"},"indexing":"navigable"},"fonts":{"heading":{"family":"Poppins"},"body":{"family":"IBM Plex Sans"}},"styling":{"codeblocks":{"theme":{"light":"css-variables","dark":"css-variables"}},"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Data Dictionary","icon":"book-open-cover","href":"https://www.shovels.ai/data-dictionary"},{"anchor":"Coverage Dashboard","icon":"map-pin","href":"https://www.shovels.ai/coverage"},{"anchor":"Community","icon":"discord","href":"https://discord.gg/Nypja3cKDx"},{"anchor":"Blog","icon":"newspaper","href":"https://www.shovels.ai/blog/"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"shovelsai","hasAudioNarration":false,"actualSubdomain":"shovelsai","customDomains":["docs.shovels.ai"],"gitSource":{"type":"github","owner":"shovelsai","repo":"shovels-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"edits":true,"issues":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6afce8a948ff1e2d8cd6e8e6","clientVersion":"0.0.4205","searchFilterCounts":[{"language":"default","tag":"Knowledge Base","count":204},{"language":"default","tag":"API Reference","count":35},{"language":"default","tag":"Endpoints","count":34},{"language":"default","tag":"API Questions","count":30},{"language":"default","tag":"Data \u0026 Coverage","count":28},{"language":"default","tag":"Documentation","count":18},{"language":"default","tag":"Contractors","count":15},{"language":"default","tag":"Permits","count":12},{"language":"default","tag":"API Basics","count":10},{"language":"default","tag":"Shovels CLI","count":10}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[],"googleFontsInlined":true},"customCss":[{"filePath":"style.css","content":"/* cyrillic-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F63fjptAgt5VM-kVkqdyU8n1iIq129k.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F63fjptAgt5VM-kVkqdyU8n1isq129k.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* symbols2 */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F63fjptAgt5VM-kVkqdyU8n1pUL8lJdhg.woff2) format('woff2');\n unicode-range: U+2000-2001, U+2004-2008, U+200A, U+23B8-23BD, U+2500-259F;\n}\n/* vietnamese */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F63fjptAgt5VM-kVkqdyU8n1iAq129k.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F63fjptAgt5VM-kVkqdyU8n1iEq129k.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F63fjptAgt5VM-kVkqdyU8n1i8q1w.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3twJwl1FgtIU.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3twJwlRFgtIU.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* symbols2 */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3twJwupkp-8tFQ.woff2) format('woff2');\n unicode-range: U+2000-2001, U+2004-2008, U+200A, U+23B8-23BD, U+2500-259F;\n}\n/* vietnamese */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3twJwl9FgtIU.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3twJwl5FgtIU.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3twJwlBFgg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3vAOwl1FgtIU.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3vAOwlRFgtIU.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* symbols2 */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3vAOwupkp-8tFQ.woff2) format('woff2');\n unicode-range: U+2000-2001, U+2004-2008, U+200A, U+23B8-23BD, U+2500-259F;\n}\n/* vietnamese */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3vAOwl9FgtIU.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3vAOwl5FgtIU.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v23/-F6qfjptAgt5VM-kVkqdyU8n3vAOwlBFgg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n:root{--shovels-ink: #101727;--shovels-ink-body: #1e293e;--shovels-ink-secondary: #6b695c;--shovels-label: #837e6c;--shovels-primary: #01654d;--shovels-emerald-dark-rgb: 16 185 129;--shovels-emerald-dark: rgb(var(--shovels-emerald-dark-rgb));--shovels-on-emerald: #0e1420;--shovels-surface: #ffffff;--shovels-panel: #f9f7f1;--shovels-subtle: #f0ecdf;--shovels-rule: #e2dcc9;--shovels-rule-strong: #dad3bd;--shovels-dark-panel: #161d2c;--shovels-dark-subtle: #1a2338;--shovels-dark-rule: #2a3550;--shovels-dark-rule-strong: #33415e;--shovels-dark-ink: #d6d0c1;--shovels-dark-ink-secondary: #948d73;--shovels-dark-success-rgb: 110 231 183;--shovels-dark-warning-rgb: 233 190 81;--shovels-dark-error-rgb: 217 135 98;--shovels-success-fill: #e6f2ee;--shovels-success-line: #c6d7ce;--shovels-success-ink: #014d3a;--shovels-warning-fill: #fdfaf0;--shovels-warning-line: #ecd9a4;--shovels-warning-ink: #7a5b18;--shovels-error-fill: #fdf2ee;--shovels-error-line: #a63d27;--shovels-error-ink: #8a3b28;--shovels-structure: Poppins, ui-sans-serif, system-ui, sans-serif;--shovels-identifier: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace;--shovels-lift: 0 1px 1px rgba(84, 72, 40, 0.04)}:root:not(.dark){--gray-50: 250 249 244;--gray-100: 244 241 231;--gray-200: 233 228 212;--gray-300: 216 209 188;--gray-400: 148 142 122;--gray-500: 121 116 95;--gray-600: 107 105 92;--gray-700: 30 41 62;--gray-800: 23 32 50;--gray-900: 16 23 39;--gray-950: 10 15 26}.eyebrow,#sidebar .sidebar-title,#content-area table th{font-family:var(--shovels-structure);font-size:10.5px;font-weight:700;text-transform:uppercase;letter-spacing:0.08em;line-height:1.4}:root:not(.dark) .eyebrow{color:var(--shovels-primary)}:root:not(.dark) #sidebar .sidebar-title,:root:not(.dark) #content-area table th{color:var(--shovels-ink-secondary)}:root.dark #content-area table th{color:var(--shovels-dark-ink-secondary)}#content-area .prose:not(.text-sm){font-size:15px;line-height:1.65}#content-area h1,#content-area h2,#content-area h3,#content-area h4{font-weight:600;letter-spacing:-0.02em}:root{--font-paper-mono: var(--shovels-identifier)}code,pre,kbd,samp{font-family:var(--shovels-identifier)}:root:not(.dark) #content-area :not(pre)>code{color:var(--shovels-ink);background:var(--shovels-subtle);border:1px solid var(--shovels-rule)}:root.dark #content-area :not(pre)>code{color:var(--shovels-dark-ink);background:var(--shovels-dark-subtle);border:1px solid var(--shovels-dark-rule)}:root:not(.dark){--mint-foreground: var(--shovels-ink);--mint-background: transparent;--mint-token-keyword: var(--shovels-primary);--mint-token-function: var(--shovels-primary);--mint-token-string: #874d33;--mint-token-string-expression: #874d33;--mint-token-constant: #765817;--mint-token-parameter: #55622f;--mint-token-punctuation: #6b6652;--mint-token-comment: #6c6753;--mint-token-link: var(--shovels-primary)}:root.dark{--mint-foreground: var(--shovels-dark-ink);--mint-background: transparent;--mint-token-keyword: var(--shovels-emerald-dark);--mint-token-function: var(--shovels-emerald-dark);--mint-token-string: #d98762;--mint-token-string-expression: #d98762;--mint-token-constant: #ba974a;--mint-token-parameter: #90a653;--mint-token-punctuation: var(--shovels-dark-ink-secondary);--mint-token-comment: #8c8670;--mint-token-link: var(--shovels-emerald-dark)}span[style*=\"--mint-token-keyword\"],span[style*=\"--mint-token-function\"]{font-weight:500;--shiki-dark-font-weight: 500}#sidebar .sidebar-group a{font-family:var(--shovels-structure)}:root:not(.dark) #search-bar-entry,:root:not(.dark) #assistant-entry{background:var(--shovels-subtle);border:1px solid var(--shovels-rule)}:root:not(.dark) #search-bar-entry *,:root:not(.dark) #assistant-entry *{color:var(--shovels-ink-secondary)}:root.dark #search-bar-entry,:root.dark #assistant-entry{background:var(--shovels-dark-subtle);border:1px solid var(--shovels-dark-rule)}:root.dark #search-bar-entry *,:root.dark #assistant-entry *{color:var(--shovels-dark-ink-secondary)}#content-area .card{border-radius:10px}:root:not(.dark) #content-area .card{background:var(--shovels-surface);border-color:var(--shovels-rule);box-shadow:var(--shovels-lift)}#content-area table td{font-size:13px}#content-area table th{padding-top:8px;padding-bottom:8px;vertical-align:middle}#content-area details table td{overflow-wrap:anywhere}#content-area details table td:first-child{font-family:var(--shovels-identifier);font-weight:500}:root:not(.dark) #content-area table th{background:var(--shovels-subtle);border-bottom:1px solid var(--shovels-rule-strong)}:root:not(.dark) #content-area table td{border-bottom:1px solid var(--shovels-rule)}:root.dark #content-area table th{background:var(--shovels-dark-subtle);border-bottom:1px solid var(--shovels-dark-rule-strong)}:root.dark #content-area table td{border-bottom:1px solid var(--shovels-dark-rule)}#content-area .callout{border-radius:10px}:root:not(.dark) #content-area .callout[class*=\"bg-neutral-\"]{background:var(--shovels-panel);border-color:var(--shovels-rule)}:root:not(.dark) #content-area .callout[class*=\"bg-neutral-\"] svg{color:var(--shovels-label)}:root:not(.dark) #content-area .callout[class*=\"bg-blue-\"]{background:var(--shovels-subtle);border-color:var(--shovels-rule-strong)}:root:not(.dark) #content-area .callout[class*=\"bg-blue-\"] svg{color:var(--shovels-ink-secondary)}:root:not(.dark) #content-area .callout[class*=\"bg-green-\"]{background:var(--shovels-success-fill);border-color:var(--shovels-success-line)}:root:not(.dark) #content-area .callout[class*=\"bg-green-\"] svg{color:var(--shovels-primary)}:root:not(.dark) #content-area .callout[class*=\"bg-yellow-\"]{background:var(--shovels-warning-fill);border-color:var(--shovels-warning-line)}:root:not(.dark) #content-area .callout[class*=\"bg-yellow-\"] svg{color:var(--shovels-warning-ink)}:root:not(.dark) #content-area .callout[class*=\"bg-red-\"]{background:var(--shovels-error-fill);border-color:var(--shovels-error-line)}:root:not(.dark) #content-area .callout[class*=\"bg-red-\"] svg{color:var(--shovels-error-line)}:root:not(.dark) #content-area .callout[class*=\"bg-neutral-\"] .prose,:root:not(.dark) #content-area .callout[class*=\"bg-blue-\"] .prose{color:var(--shovels-ink-body)}:root:not(.dark) #content-area .callout[class*=\"bg-green-\"] .prose{color:var(--shovels-success-ink)}:root:not(.dark) #content-area .callout[class*=\"bg-yellow-\"] .prose{color:var(--shovels-warning-ink)}:root:not(.dark) #content-area .callout[class*=\"bg-red-\"] .prose{color:var(--shovels-error-ink)}:root.dark #content-area .callout[class*=\"bg-neutral-\"]{background:var(--shovels-dark-panel);border-color:var(--shovels-dark-rule)}:root.dark #content-area .callout[class*=\"bg-neutral-\"] svg{color:var(--shovels-dark-ink-secondary)}:root.dark #content-area .callout[class*=\"bg-blue-\"]{background:var(--shovels-dark-subtle);border-color:var(--shovels-dark-rule-strong)}:root.dark #content-area .callout[class*=\"bg-blue-\"] svg{color:var(--shovels-dark-ink-secondary)}:root.dark #content-area .callout[class*=\"bg-green-\"]{background:rgb(var(--shovels-dark-success-rgb) / 0.12);border-color:rgb(var(--shovels-dark-success-rgb) / 0.30)}:root.dark #content-area .callout[class*=\"bg-green-\"] svg{color:rgb(var(--shovels-dark-success-rgb))}:root.dark #content-area .callout[class*=\"bg-yellow-\"]{background:rgb(var(--shovels-dark-warning-rgb) / 0.12);border-color:rgb(var(--shovels-dark-warning-rgb) / 0.30)}:root.dark #content-area .callout[class*=\"bg-yellow-\"] svg{color:rgb(var(--shovels-dark-warning-rgb))}:root.dark #content-area .callout[class*=\"bg-red-\"]{background:rgb(var(--shovels-dark-error-rgb) / 0.12);border-color:rgb(var(--shovels-dark-error-rgb) / 0.30)}:root.dark #content-area .callout[class*=\"bg-red-\"] svg{color:rgb(var(--shovels-dark-error-rgb))}:root.dark #content-area .callout[class*=\"bg-neutral-\"] .prose,:root.dark #content-area .callout[class*=\"bg-blue-\"] .prose{color:var(--shovels-dark-ink)}:root.dark #content-area .callout[class*=\"bg-green-\"] .prose{color:rgb(var(--shovels-dark-success-rgb))}:root.dark #content-area .callout[class*=\"bg-yellow-\"] .prose{color:rgb(var(--shovels-dark-warning-rgb))}:root.dark #content-area .callout[class*=\"bg-red-\"] .prose{color:rgb(var(--shovels-dark-error-rgb))}:root:not(.dark){--accordion-background-color: var(--shovels-panel);--accordion-background-hover: var(--shovels-subtle);--accordion-icon-color: var(--shovels-label)}:root:not(.dark) .method-nav-pill [class*=\"2AB673\"],:root:not(.dark) .tryit-button[class*=\"2AB673\"]{background-color:var(--shovels-primary)}:root:not(.dark) .method-nav-pill [class*=\"bg-green-\"],:root:not(.dark) .method-pill[class*=\"bg-green-\"]{background-color:var(--shovels-success-fill);color:var(--shovels-primary)}:root.dark .method-nav-pill [class*=\"2AB673\"],:root.dark .tryit-button[class*=\"2AB673\"]{background-color:var(--shovels-emerald-dark);color:var(--shovels-on-emerald)}:root.dark .method-nav-pill [class*=\"bg-green-\"],:root.dark .method-pill[class*=\"bg-green-\"]{background-color:rgb(var(--shovels-emerald-dark-rgb) / 0.18);color:var(--shovels-emerald-dark)}:root.dark [class*=\"bg-primary-dark\"]{background-color:var(--shovels-emerald-dark)}:root.dark #topbar-cta-button,:root.dark #topbar-cta-button *{color:var(--shovels-on-emerald)}:root:not(.dark) #content-area [class*=\"bg-red-100\"]{background-color:var(--shovels-warning-fill);color:var(--shovels-warning-ink);box-shadow:inset 0 0 0 1px var(--shovels-warning-line)}:root.dark #content-area [class*=\"bg-red-100\"]{background-color:rgb(var(--shovels-dark-warning-rgb) / 0.12);color:rgb(var(--shovels-dark-warning-rgb));box-shadow:inset 0 0 0 1px rgb(var(--shovels-dark-warning-rgb) / 0.30)}"}],"page":{"pagePath":"api-reference/contractors/search-contractors","slug":"/api-reference/contractors/search-contractors","pageMetadata":{"title":"Search Contractors","description":"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., 'installing' matches 'install'). Multi-word queries use AND semantics (e.g., 'solar panel' finds permits mentioning both words). **NOTE:** Contractors are ordered by the start date of the most recent permit on which they worked.","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors/search","href":"/api-reference/contractors/search-contractors","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., ‘installing’ matches ‘install’). Multi-word queries use AND semantics (e.g., ‘solar panel’ finds permits mentioning both words). \", _jsx(_components.strong, {\n children: \"NOTE:\"\n }), \" Contractors are ordered by the start date of the most recent permit on which they worked.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":{"theme":{"light":"css-variables","dark":"css-variables"}},"config":{},"pageMetadata":{"title":"Search Contractors","description":"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., 'installing' matches 'install'). Multi-word queries use AND semantics (e.g., 'solar panel' finds permits mentioning both words). **NOTE:** Contractors are ordered by the start date of the most recent permit on which they worked.","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors/search","href":"/api-reference/contractors/search-contractors","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Contractors","Contractors"],"summary":"Search Contractors","description":"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., 'installing' matches 'install'). Multi-word queries use AND semantics (e.g., 'solar panel' finds permits mentioning both words). **NOTE:** Contractors are ordered by the start date of the most recent permit on which they worked.","operationId":"search_contractors_contractors_search_get","security":["1545a1b4-da8a-4ead-aaa6-f5ae297a0080"],"parameters":["98cb4d78-978c-4175-992c-723cf2d48848","4bf46f7e-b073-414e-b059-fbd46f174bfe","e60fce4b-380f-4010-a776-171139f4a815","78160c31-b3a4-4cec-8973-8cf959470f7a","cf370ef9-60b8-4814-b204-f9865740badb","2431e7f8-7ea6-4029-bdba-861af0fa001b","7d09c86b-f979-46a0-b774-1f63ac36b2d2","34dd53a9-e80b-4249-8825-b4861f5cb7cf","6f1ac1e7-613d-4cfe-84fe-a24e8f1246c1","d17203a4-a836-4027-9300-088ded3da59c","13801b6a-c222-44c4-aac3-fc45f16c3bc4","5e3ee74e-3f94-4a6a-86b5-fb049a4a16ec","50bf2644-b539-49ea-b89b-6d2e8db529d9","ca1c6166-7231-4813-b823-47b03606bc5a","d91483e0-07e6-4506-87a9-b5541b851934","cfeba662-587d-46b7-aa05-2535f1fcb33d","2ebd03a7-399e-4fcb-8582-0761c1ffd7e3","f1074e5c-d94d-4cdf-86c3-aee2dbbfd4d4","aba7f5fc-09fb-49df-94cb-e18ce086127d","a0c2eb91-6233-426e-9c8c-e26aab380148","777e959b-4000-4768-9978-47228d88c42b","9d3d4484-1818-4066-86f8-4f9f27090ed0","8c80869a-9f43-406d-8a89-549345d002e0","01e31dfd-061c-4108-82a0-389b3ca5fcfe","565c95cd-f1b3-4214-b10e-55a5bba46bcc","ea226a74-10a0-410f-842d-78263224923a","8bc2d8b4-92fa-41ed-95f3-75a7837ab3ec","74b6bdb6-3fd3-493b-a7ae-64e47f21704f"],"responses":{"200":"769195a7-b24c-4423-af9d-b0db693c65bd","422":"ce3c5432-01c2-4f0a-b306-cc7145e9a831"},"method":"get","type":"path","servers":["93374fb2-01d3-412c-b619-45b0cd831bff"],"path":"/contractors/search","baseUrlOptions":["https://api.shovels.ai/v2"],"title":"Search Contractors","codeSamples":[],"requestExampleLanguages":["bash","python","java","go","ruby","php"],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"98cb4d78-978c-4175-992c-723cf2d48848":{"name":"cursor","in":"query","required":false,"schema":{"oneOf":[{"type":"string","title":"Cursor","description":"Cursor for pagination","uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Cursor","description":"Cursor for pagination","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"},"description":"Cursor for pagination"},"4bf46f7e-b073-414e-b059-fbd46f174bfe":{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":10,"title":"Size","isRequired":false,"uniqueKey":"","typeLabel":"integer"}},"e60fce4b-380f-4010-a776-171139f4a815":{"name":"include_count","in":"query","required":false,"schema":{"type":"boolean","description":"When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'.","default":false,"title":"Include Count","isRequired":false,"uniqueKey":"","typeLabel":"boolean"},"description":"When true and on the first page (no cursor), include total_count in the response. The count is exact up to 10,000; above that, relation is 'gte'."},"78160c31-b3a4-4cec-8973-8cf959470f7a":{"name":"include_tallies","in":"query","required":false,"schema":{"type":"boolean","description":"Include tag and status tallies in response. Tallies are the only aggregate fields scoped to the search filters (permit_count, avg_job_value and total_job_value are lifetime totals), so they are the way to count a contractor's permits within the searched area and date range. Set to false to omit tally computation for faster response times when tallies are not needed.","default":true,"title":"Include Tallies","isRequired":false,"uniqueKey":"","typeLabel":"boolean"},"description":"Include tag and status tallies in response. Tallies are the only aggregate fields scoped to the search filters (permit_count, avg_job_value and total_job_value are lifetime totals), so they are the way to count a contractor's permits within the searched area and date range. Set to false to omit tally computation for faster response times when tallies are not needed."},"cf370ef9-60b8-4814-b204-f9865740badb":{"name":"permit_from","in":"query","required":true,"schema":{"type":"string","format":"date","title":"Permit From Date","description":"Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: `YYYY-MM-DD`","isRequired":true,"uniqueKey":"","typeLabel":"string\u003cdate>"},"description":"Return permits that started on or after the specified date.This includes all permits with the earliest date (file, issue, or start date) that falls on or after this date. Date format: `YYYY-MM-DD`"},"2431e7f8-7ea6-4029-bdba-861af0fa001b":{"name":"permit_to","in":"query","required":true,"schema":{"type":"string","format":"date","title":"Permit To Date","description":"Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: `YYYY-MM-DD`","isRequired":true,"uniqueKey":"","typeLabel":"string\u003cdate>"},"description":"Return permits that started on or before the specified date.This includes all permits with the latest date (file, issue, or end date) that falls on or before this date. Date format: `YYYY-MM-DD`"},"7d09c86b-f979-46a0-b774-1f63ac36b2d2":{"name":"permit_q","in":"query","required":false,"schema":{"oneOf":[{"type":"string","title":"Search Query","description":"Search permit descriptions. Permits search uses case-insensitive substring matching, including partial words. Contractors search uses full-text search with English stemming. For example, installing matches install. Multi-word contractor queries require all words after English text processing. For example, solar panel requires both solar and panel.","maxLength":50,"uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Search Query","description":"Search permit descriptions. Permits search uses case-insensitive substring matching, including partial words. Contractors search uses full-text search with English stemming. For example, installing matches install. Multi-word contractor queries require all words after English text processing. For example, solar panel requires both solar and panel.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"},"description":"Search permit descriptions. Permits search uses case-insensitive substring matching, including partial words. Contractors search uses full-text search with English stemming. For example, installing matches install. Multi-word contractor queries require all words after English text processing. For example, solar panel requires both solar and panel."},"34dd53a9-e80b-4249-8825-b4861f5cb7cf":{"name":"permit_status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","uniqueKey":"items.[INDEX]","typeLabel":"string"},"title":"Permit Status","description":"Filter by one or more statuses: final, in_review, inactive, active.","maxItems":4,"isRequired":false,"uniqueKey":"","typeLabel":"string[]"},"description":"Filter by one or more statuses: final, in_review, inactive, active."},"6f1ac1e7-613d-4cfe-84fe-a24e8f1246c1":{"name":"permit_min_approval_duration","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Minimum Permit Approval Duration","description":"Filter by the minimum permit approval duration in days.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Minimum Permit Approval Duration","description":"Filter by the minimum permit approval duration in days.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Filter by the minimum permit approval duration in days."},"d17203a4-a836-4027-9300-088ded3da59c":{"name":"permit_min_construction_duration","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Minimum Project Construction Duration","description":"Filter by the minimum project construction duration in days.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Minimum Project Construction Duration","description":"Filter by the minimum project construction duration in days.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Filter by the minimum project construction duration in days."},"13801b6a-c222-44c4-aac3-fc45f16c3bc4":{"name":"permit_min_inspection_pr","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Minimum Inspection Pass Rate","description":"Filter by the minimum inspection pass rate.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Minimum Inspection Pass Rate","description":"Filter by the minimum inspection pass rate.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Filter by the minimum inspection pass rate."},"5e3ee74e-3f94-4a6a-86b5-fb049a4a16ec":{"name":"permit_min_job_value","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Minimum Job Value","description":"Filter by the minimum job value, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Minimum Job Value","description":"Filter by the minimum job value, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Filter by the minimum job value, in cents (e.g. 5000000 = $50,000)."},"50bf2644-b539-49ea-b89b-6d2e8db529d9":{"name":"permit_min_fees","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Minimum Permit Fees","description":"Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Minimum Permit Fees","description":"Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Filter by minimum permit fees, in cents (e.g. 5000000 = $50,000)."},"ca1c6166-7231-4813-b823-47b03606bc5a":{"name":"permit_tags","in":"query","required":false,"schema":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.items.[INDEX]","typeLabel":"string"},"title":"Permit Tags","description":"Filter by one or more tags. Use '-' prefix to exclude tags. Example: ?permit_tags=solar\u0026permit_tags=-roofing (has solar, not roofing). Tags match against the contractor's aggregated permit history in the searched area: every included tag must appear somewhere in that history, and different permits may contribute different tags. An excluded tag drops the contractor if any permit in that history ever had it. The date filter does not restrict which tags count; the tag history is an all-time aggregate.","uniqueKey":"oneOf.0","typeLabel":"string[]"},{"type":"null","title":"Permit Tags","description":"Filter by one or more tags. Use '-' prefix to exclude tags. Example: ?permit_tags=solar\u0026permit_tags=-roofing (has solar, not roofing). Tags match against the contractor's aggregated permit history in the searched area: every included tag must appear somewhere in that history, and different permits may contribute different tags. An excluded tag drops the contractor if any permit in that history ever had it. The date filter does not restrict which tags count; the tag history is an all-time aggregate.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string[] | null"},"description":"Filter by one or more tags. Use '-' prefix to exclude tags. Example: ?permit_tags=solar\u0026permit_tags=-roofing (has solar, not roofing). Tags match against the contractor's aggregated permit history in the searched area: every included tag must appear somewhere in that history, and different permits may contribute different tags. An excluded tag drops the contractor if any permit in that history ever had it. The date filter does not restrict which tags count; the tag history is an all-time aggregate."},"d91483e0-07e6-4506-87a9-b5541b851934":{"name":"geo_id","in":"query","required":true,"schema":{"type":"string","title":"Geolocation ID","description":"Filter results by geographic area. Accepts:\n- US state code (e.g. `CA`)\n- ZIP code (e.g. `90210` or `90210-1234`)\n- Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. `a4xysKbZwqg`)\n\nResolve addresses and places to geolocation IDs via:\n- [Search Addresses](/api-reference/addresses/search-addresses)\n- [Search Cities](/api-reference/cities/search-cities)\n- [Search Counties](/api-reference/counties/search-counties)\n- [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions)\n\nFree-form text such as `\"123 Main St\"` is not accepted.","isRequired":true,"uniqueKey":"","typeLabel":"string"},"description":"Filter results by geographic area. Accepts:\n- US state code (e.g. `CA`)\n- ZIP code (e.g. `90210` or `90210-1234`)\n- Shovels geolocation ID for an address, city, county, or jurisdiction (e.g. `a4xysKbZwqg`)\n\nResolve addresses and places to geolocation IDs via:\n- [Search Addresses](/api-reference/addresses/search-addresses)\n- [Search Cities](/api-reference/cities/search-cities)\n- [Search Counties](/api-reference/counties/search-counties)\n- [Search Jurisdictions](/api-reference/jurisdictions/search-jurisdictions)\n\nFree-form text such as `\"123 Main St\"` is not accepted."},"cfeba662-587d-46b7-aa05-2535f1fcb33d":{"name":"property_type","in":"query","required":false,"schema":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.items.[INDEX]","typeLabel":"string"},"title":"Property Type","description":"Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential\u0026property_type=commercial`).","uniqueKey":"oneOf.0","typeLabel":"string[]"},{"type":"null","title":"Property Type","description":"Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential\u0026property_type=commercial`).","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string[] | null"},"description":"Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational. Repeat the key to match any of several types (e.g. `?property_type=residential\u0026property_type=commercial`)."},"2ebd03a7-399e-4fcb-8582-0761c1ffd7e3":{"name":"property_min_market_value","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Property Market Value","description":"Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Property Market Value","description":"Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum assessed market value of the property, in cents (e.g. 5000000 = $50,000)."},"f1074e5c-d94d-4cdf-86c3-aee2dbbfd4d4":{"name":"property_min_building_area","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Property Building Area","description":"Minimum total building area in sq ft.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Property Building Area","description":"Minimum total building area in sq ft.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum total building area in sq ft."},"aba7f5fc-09fb-49df-94cb-e18ce086127d":{"name":"property_min_lot_size","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Property Lot Size","description":"Minimum size of the property lot in sq ft.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Property Lot Size","description":"Minimum size of the property lot in sq ft.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum size of the property lot in sq ft."},"a0c2eb91-6233-426e-9c8c-e26aab380148":{"name":"property_min_story_count","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Property Story Count","description":"Minimum number of property stories.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Property Story Count","description":"Minimum number of property stories.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum number of property stories."},"777e959b-4000-4768-9978-47228d88c42b":{"name":"property_min_unit_count","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Property Unit Count","description":"Minimum number of property units","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Property Unit Count","description":"Minimum number of property units","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum number of property units"},"9d3d4484-1818-4066-86f8-4f9f27090ed0":{"name":"contractor_classification_derived","in":"query","required":false,"schema":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.items.[INDEX]","typeLabel":"string"},"title":"Contractor Classification Derived","description":"Filter by derived contractor classifications. Use '-' prefix to exclude. Example: ?classification_derived=electrical\u0026classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.","uniqueKey":"oneOf.0","typeLabel":"string[]"},{"type":"null","title":"Contractor Classification Derived","description":"Filter by derived contractor classifications. Use '-' prefix to exclude. Example: ?classification_derived=electrical\u0026classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string[] | null"},"description":"Filter by derived contractor classifications. Use '-' prefix to exclude. Example: ?classification_derived=electrical\u0026classification_derived=-hvac. Returns results containing ALL specified classifications. Possible values: concrete_and_paving, demolition_and_excavation, electrical, fencing_and_glazing, framing_and_carpentry, general_building_contractor, general_engineering_contractor, hvac, landscaping_and_outdoor_work, other, plumbing, roofing, specialty_trades."},"8c80869a-9f43-406d-8a89-549345d002e0":{"name":"contractor_name","in":"query","required":false,"schema":{"oneOf":[{"type":"string","title":"Contractor Name","description":"Filter by contractor's name or business name (partial match supported). Must be at least 3 characters — shorter patterns cannot use the trigram index and would force a sequential scan.","minLength":3,"uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Contractor Name","description":"Filter by contractor's name or business name (partial match supported). Must be at least 3 characters — shorter patterns cannot use the trigram index and would force a sequential scan.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"},"description":"Filter by contractor's name or business name (partial match supported). Must be at least 3 characters — shorter patterns cannot use the trigram index and would force a sequential scan."},"01e31dfd-061c-4108-82a0-389b3ca5fcfe":{"name":"contractor_website","in":"query","required":false,"schema":{"oneOf":[{"type":"string","title":"Contractor Website","description":"Filter by contractor's website prefix. Surrounding whitespace is trimmed and input is lowercased. Leading http://, https://, and www. prefixes and trailing slashes are removed. Paths are retained. A value that is empty after normalization applies no website filter.","uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Contractor Website","description":"Filter by contractor's website prefix. Surrounding whitespace is trimmed and input is lowercased. Leading http://, https://, and www. prefixes and trailing slashes are removed. Paths are retained. A value that is empty after normalization applies no website filter.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"},"description":"Filter by contractor's website prefix. Surrounding whitespace is trimmed and input is lowercased. Leading http://, https://, and www. prefixes and trailing slashes are removed. Paths are retained. A value that is empty after normalization applies no website filter."},"565c95cd-f1b3-4214-b10e-55a5bba46bcc":{"name":"contractor_min_total_job_value","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Contractor Total Job Value","description":"Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Contractor Total Job Value","description":"Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000).","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum lifetime job value of the contractor, in cents (e.g. 5000000 = $50,000)."},"ea226a74-10a0-410f-842d-78263224923a":{"name":"contractor_min_total_permits_count","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Contractor Permits Count","description":"Minimum lifetime permits count.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Contractor Permits Count","description":"Minimum lifetime permits count.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum lifetime permits count."},"8bc2d8b4-92fa-41ed-95f3-75a7837ab3ec":{"name":"contractor_min_inspection_pr","in":"query","required":false,"schema":{"oneOf":[{"type":"integer","title":"Mininum Contractor Inspection Pass Rate","description":"Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive.","uniqueKey":"oneOf.0","typeLabel":"integer"},{"type":"null","title":"Mininum Contractor Inspection Pass Rate","description":"Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive.","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"integer | null"},"description":"Minimum lifetime inspection pass rate. The value must be an integer between 0 and 100, inclusive."},"74b6bdb6-3fd3-493b-a7ae-64e47f21704f":{"name":"contractor_license","in":"query","required":false,"schema":{"oneOf":[{"type":"string","title":"Contractor License","description":"Filter by the contractor's license","uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Contractor License","description":"Filter by the contractor's license","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"},"description":"Filter by the contractor's license"}},"responses":{"769195a7-b24c-4423-af9d-b0db693c65bd":{"description":"A list of contractors.","content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"id":{"type":"string","title":"Id","description":"The contractor ID.","isRequired":true,"uniqueKey":"\\items.items.[INDEX].id","typeLabel":"string"},"address":{"oneOf":[{"type":"object","title":"AddressesEmbedded","description":"The contractor's address dictionary that contains street_no, street, city, jurisdiction, zip_code, zip_code_ext, state, and latlng fields.","properties":{"street_no":{"oneOf":[{"type":"string","title":"Street No","description":"The number of the street of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.street_no.oneOf.0","typeLabel":"string"},{"type":"null","title":"Street No","description":"The number of the street of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.street_no.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.street_no","typeLabel":"string | null"},"street":{"oneOf":[{"type":"string","title":"Street","description":"The name of the street of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.street.oneOf.0","typeLabel":"string"},{"type":"null","title":"Street","description":"The name of the street of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.street.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.street","typeLabel":"string | null"},"city":{"oneOf":[{"type":"string","title":"City","description":"The city of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.city.oneOf.0","typeLabel":"string"},{"type":"null","title":"City","description":"The city of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.city.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.city","typeLabel":"string | null"},"county":{"oneOf":[{"type":"string","title":"County","description":"The county of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.county.oneOf.0","typeLabel":"string"},{"type":"null","title":"County","description":"The county of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.county.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.county","typeLabel":"string | null"},"zip_code":{"oneOf":[{"type":"string","title":"Zip Code","description":"The ZIP code of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.zip_code.oneOf.0","typeLabel":"string"},{"type":"null","title":"Zip Code","description":"The ZIP code of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.zip_code.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.zip_code","typeLabel":"string | null"},"zip_code_ext":{"oneOf":[{"type":"string","title":"Zip Code Ext","description":"The extension of the ZIP code of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.zip_code_ext.oneOf.0","typeLabel":"string"},{"type":"null","title":"Zip Code Ext","description":"The extension of the ZIP code of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.zip_code_ext.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.zip_code_ext","typeLabel":"string | null"},"state":{"oneOf":[{"type":"string","title":"State","description":"The state of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.state.oneOf.0","typeLabel":"string"},{"type":"null","title":"State","description":"The state of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.state.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.state","typeLabel":"string | null"},"jurisdiction":{"oneOf":[{"type":"string","title":"Jurisdiction","description":"The jurisdiction the address belongs to.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.jurisdiction.oneOf.0","typeLabel":"string"},{"type":"null","title":"Jurisdiction","description":"The jurisdiction the address belongs to.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.jurisdiction.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.jurisdiction","typeLabel":"string | null"},"address_id":{"oneOf":[{"type":"string","title":"Address Id","description":"The address identifier.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.address_id.oneOf.0","typeLabel":"string"},{"type":"null","title":"Address Id","description":"The address identifier.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.address_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.address_id","typeLabel":"string | null"},"latlng":{"oneOf":[{"type":"array","items":{"oneOf":[{"type":"number","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.latlng.oneOf.0.items.[INDEX].oneOf.0","typeLabel":"number"},{"type":"null","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.latlng.oneOf.0.items.[INDEX].oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.latlng.oneOf.0.items.[INDEX]","typeLabel":"number | null"},"title":"Latlng","description":"The latitude and longitude of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.latlng.oneOf.0","typeLabel":"(number | null)[]"},{"type":"null","title":"Latlng","description":"The latitude and longitude of the address.","uniqueKey":"\\items.items.[INDEX].address.oneOf.0.latlng.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].address.oneOf.0.latlng","typeLabel":"(number | null)[] | null"}},"isRequired":true,"uniqueKey":"\\items.items.[INDEX].address.oneOf.0","typeLabel":"AddressesEmbedded · object"},{"type":"null","description":"The contractor's address dictionary that contains street_no, street, city, jurisdiction, zip_code, zip_code_ext, state, and latlng fields.","isRequired":true,"uniqueKey":"\\items.items.[INDEX].address.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"\\items.items.[INDEX].address","typeLabel":"AddressesEmbedded · object | null"},"license":{"oneOf":[{"type":"string","title":"License","description":"The contractor license number.","uniqueKey":"\\items.items.[INDEX].license.oneOf.0","typeLabel":"string"},{"type":"null","title":"License","description":"The contractor license number.","uniqueKey":"\\items.items.[INDEX].license.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].license","typeLabel":"string | null"},"name":{"oneOf":[{"type":"string","title":"Name","description":"The contractor name.","uniqueKey":"\\items.items.[INDEX].name.oneOf.0","typeLabel":"string"},{"type":"null","title":"Name","description":"The contractor name.","uniqueKey":"\\items.items.[INDEX].name.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].name","typeLabel":"string | null"},"business_name":{"oneOf":[{"type":"string","title":"Business Name","description":"The contractor business name.","uniqueKey":"\\items.items.[INDEX].business_name.oneOf.0","typeLabel":"string"},{"type":"null","title":"Business Name","description":"The contractor business name.","uniqueKey":"\\items.items.[INDEX].business_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].business_name","typeLabel":"string | null"},"business_type":{"oneOf":[{"type":"string","title":"Business Type","description":"The type of business: JointVenture, Corporation, Partnership, Limited Liability, Sole Owner.","uniqueKey":"\\items.items.[INDEX].business_type.oneOf.0","typeLabel":"string"},{"type":"null","title":"Business Type","description":"The type of business: JointVenture, Corporation, Partnership, Limited Liability, Sole Owner.","uniqueKey":"\\items.items.[INDEX].business_type.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].business_type","typeLabel":"string | null"},"classification":{"oneOf":[{"type":"string","title":"Classification","description":"The contractor's classification/certification.","uniqueKey":"\\items.items.[INDEX].classification.oneOf.0","typeLabel":"string"},{"type":"null","title":"Classification","description":"The contractor's classification/certification.","uniqueKey":"\\items.items.[INDEX].classification.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].classification","typeLabel":"string | null"},"classification_derived":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"\\items.items.[INDEX].classification_derived.oneOf.0.items.[INDEX]","typeLabel":"string"},"title":"Classification Derived","description":"Array of derived contractor classifications.","uniqueKey":"\\items.items.[INDEX].classification_derived.oneOf.0","typeLabel":"string[]"},{"type":"null","title":"Classification Derived","description":"Array of derived contractor classifications.","uniqueKey":"\\items.items.[INDEX].classification_derived.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].classification_derived","typeLabel":"string[] | null"},"license_issue_date":{"oneOf":[{"type":"string","title":"License Issue Date","description":"The license issue date.","format":"date","uniqueKey":"\\items.items.[INDEX].license_issue_date.oneOf.0","typeLabel":"string\u003cdate>"},{"type":"null","title":"License Issue Date","description":"The license issue date.","uniqueKey":"\\items.items.[INDEX].license_issue_date.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].license_issue_date","typeLabel":"string\u003cdate> | null"},"license_exp_date":{"oneOf":[{"type":"string","title":"License Exp Date","description":"The license expiration date.","format":"date","uniqueKey":"\\items.items.[INDEX].license_exp_date.oneOf.0","typeLabel":"string\u003cdate>"},{"type":"null","title":"License Exp Date","description":"The license expiration date.","uniqueKey":"\\items.items.[INDEX].license_exp_date.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].license_exp_date","typeLabel":"string\u003cdate> | null"},"license_inact_date":{"oneOf":[{"type":"string","title":"License Inact Date","description":"Date when the contractor's license became inactive.","format":"date","uniqueKey":"\\items.items.[INDEX].license_inact_date.oneOf.0","typeLabel":"string\u003cdate>"},{"type":"null","title":"License Inact Date","description":"Date when the contractor's license became inactive.","uniqueKey":"\\items.items.[INDEX].license_inact_date.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].license_inact_date","typeLabel":"string\u003cdate> | null"},"license_act_date":{"oneOf":[{"type":"string","title":"License Act Date","description":"Date when the contractor's license became active.","format":"date","uniqueKey":"\\items.items.[INDEX].license_act_date.oneOf.0","typeLabel":"string\u003cdate>"},{"type":"null","title":"License Act Date","description":"Date when the contractor's license became active.","uniqueKey":"\\items.items.[INDEX].license_act_date.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].license_act_date","typeLabel":"string\u003cdate> | null"},"primary_phone":{"oneOf":[{"type":"string","title":"Primary Phone","description":"The contractor's primary phone number.","uniqueKey":"\\items.items.[INDEX].primary_phone.oneOf.0","typeLabel":"string"},{"type":"null","title":"Primary Phone","description":"The contractor's primary phone number.","uniqueKey":"\\items.items.[INDEX].primary_phone.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].primary_phone","typeLabel":"string | null"},"primary_email":{"oneOf":[{"type":"string","title":"Primary Email","description":"The contractor's primary email.","uniqueKey":"\\items.items.[INDEX].primary_email.oneOf.0","typeLabel":"string"},{"type":"null","title":"Primary Email","description":"The contractor's primary email.","uniqueKey":"\\items.items.[INDEX].primary_email.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].primary_email","typeLabel":"string | null"},"phone":{"oneOf":[{"type":"string","title":"Phone","description":"The contractor's phone number(s).","uniqueKey":"\\items.items.[INDEX].phone.oneOf.0","typeLabel":"string"},{"type":"null","title":"Phone","description":"The contractor's phone number(s).","uniqueKey":"\\items.items.[INDEX].phone.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].phone","typeLabel":"string | null"},"email":{"oneOf":[{"type":"string","title":"Email","description":"The contractor's email(s).","uniqueKey":"\\items.items.[INDEX].email.oneOf.0","typeLabel":"string"},{"type":"null","title":"Email","description":"The contractor's email(s).","uniqueKey":"\\items.items.[INDEX].email.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].email","typeLabel":"string | null"},"website":{"oneOf":[{"type":"string","title":"Website","description":"The contractor's website).","uniqueKey":"\\items.items.[INDEX].website.oneOf.0","typeLabel":"string"},{"type":"null","title":"Website","description":"The contractor's website).","uniqueKey":"\\items.items.[INDEX].website.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].website","typeLabel":"string | null"},"dba":{"oneOf":[{"type":"string","title":"Dba","description":"Doing Business As name for the contractor.","uniqueKey":"\\items.items.[INDEX].dba.oneOf.0","typeLabel":"string"},{"type":"null","title":"Dba","description":"Doing Business As name for the contractor.","uniqueKey":"\\items.items.[INDEX].dba.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].dba","typeLabel":"string | null"},"sic":{"oneOf":[{"type":"string","title":"Sic","description":"Standard Industrial Classification (SIC) code of the contractor.","uniqueKey":"\\items.items.[INDEX].sic.oneOf.0","typeLabel":"string"},{"type":"null","title":"Sic","description":"Standard Industrial Classification (SIC) code of the contractor.","uniqueKey":"\\items.items.[INDEX].sic.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].sic","typeLabel":"string | null"},"naics":{"oneOf":[{"type":"string","title":"Naics","description":"North American Industry Classification System (NAICS) code of the contractor.","uniqueKey":"\\items.items.[INDEX].naics.oneOf.0","typeLabel":"string"},{"type":"null","title":"Naics","description":"North American Industry Classification System (NAICS) code of the contractor.","uniqueKey":"\\items.items.[INDEX].naics.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].naics","typeLabel":"string | null"},"linkedin_url":{"oneOf":[{"type":"string","title":"Linkedin Url","description":"LinkedIn URL of the contractor.","uniqueKey":"\\items.items.[INDEX].linkedin_url.oneOf.0","typeLabel":"string"},{"type":"null","title":"Linkedin Url","description":"LinkedIn URL of the contractor.","uniqueKey":"\\items.items.[INDEX].linkedin_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].linkedin_url","typeLabel":"string | null"},"revenue":{"oneOf":[{"type":"string","title":"Revenue","description":"Annual revenue of the contractor's business.","uniqueKey":"\\items.items.[INDEX].revenue.oneOf.0","typeLabel":"string"},{"type":"null","title":"Revenue","description":"Annual revenue of the contractor's business.","uniqueKey":"\\items.items.[INDEX].revenue.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].revenue","typeLabel":"string | null"},"employee_count":{"oneOf":[{"type":"string","title":"Employee Count","description":"Number of employees working for the contractor.","uniqueKey":"\\items.items.[INDEX].employee_count.oneOf.0","typeLabel":"string"},{"type":"null","title":"Employee Count","description":"Number of employees working for the contractor.","uniqueKey":"\\items.items.[INDEX].employee_count.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].employee_count","typeLabel":"string | null"},"primary_industry":{"oneOf":[{"type":"string","title":"Primary Industry","description":"Primary industry in which the contractor operates.","uniqueKey":"\\items.items.[INDEX].primary_industry.oneOf.0","typeLabel":"string"},{"type":"null","title":"Primary Industry","description":"Primary industry in which the contractor operates.","uniqueKey":"\\items.items.[INDEX].primary_industry.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].primary_industry","typeLabel":"string | null"},"review_count":{"oneOf":[{"type":"integer","title":"Review Count","description":"Number of reviews the contractor has received.","uniqueKey":"\\items.items.[INDEX].review_count.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Review Count","description":"Number of reviews the contractor has received.","uniqueKey":"\\items.items.[INDEX].review_count.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].review_count","typeLabel":"integer | null"},"rating":{"oneOf":[{"type":"number","title":"Rating","description":"Rating of the contractor based on reviews.","uniqueKey":"\\items.items.[INDEX].rating.oneOf.0","typeLabel":"number"},{"type":"null","title":"Rating","description":"Rating of the contractor based on reviews.","uniqueKey":"\\items.items.[INDEX].rating.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].rating","typeLabel":"number | null"},"status_tally":{"oneOf":[{"type":"object","title":"Status Tally","description":"Permit counts by status (active, final, unknown, inactive, in_review). The status unknown can appear in responses. It is not accepted by the permit_status filter. On /contractors/search: filtered by geo and date range parameters. On /contractors (get by ID): unfiltered lifetime counts.","default":{},"additionalProperties":{"type":"integer","uniqueKey":"\\items.items.[INDEX].status_tally.oneOf.0.additionalProperties","typeLabel":"integer"},"uniqueKey":"\\items.items.[INDEX].status_tally.oneOf.0","typeLabel":"Status Tally · object"},{"type":"null","title":"Status Tally","description":"Permit counts by status (active, final, unknown, inactive, in_review). The status unknown can appear in responses. It is not accepted by the permit_status filter. On /contractors/search: filtered by geo and date range parameters. On /contractors (get by ID): unfiltered lifetime counts.","default":{},"uniqueKey":"\\items.items.[INDEX].status_tally.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].status_tally","typeLabel":"Status Tally · object | null"},"tag_tally":{"oneOf":[{"type":"object","title":"Tag Tally","description":"Permit counts by tag. Each permit is counted once under every tag it has — a permit tagged both 'solar' and 'electrical' adds 1 to each. On /contractors/search: filtered by geo and date range parameters. On /contractors (get by ID): unfiltered lifetime counts, so the values can add up to more than permit_count.","default":{},"additionalProperties":{"type":"integer","uniqueKey":"\\items.items.[INDEX].tag_tally.oneOf.0.additionalProperties","typeLabel":"integer"},"uniqueKey":"\\items.items.[INDEX].tag_tally.oneOf.0","typeLabel":"Tag Tally · object"},{"type":"null","title":"Tag Tally","description":"Permit counts by tag. Each permit is counted once under every tag it has — a permit tagged both 'solar' and 'electrical' adds 1 to each. On /contractors/search: filtered by geo and date range parameters. On /contractors (get by ID): unfiltered lifetime counts, so the values can add up to more than permit_count.","default":{},"uniqueKey":"\\items.items.[INDEX].tag_tally.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].tag_tally","typeLabel":"Tag Tally · object | null"},"permit_count":{"oneOf":[{"type":"integer","title":"Permit Count","description":"Contractor lifetime total permit count across all locations and dates. Not filtered by search parameters.","uniqueKey":"\\items.items.[INDEX].permit_count.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Permit Count","description":"Contractor lifetime total permit count across all locations and dates. Not filtered by search parameters.","uniqueKey":"\\items.items.[INDEX].permit_count.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].permit_count","typeLabel":"integer | null"},"avg_job_value":{"oneOf":[{"type":"integer","title":"Avg Job Value","description":"The average job value of all permits in cents (integer value representing dollars × 100).","uniqueKey":"\\items.items.[INDEX].avg_job_value.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Avg Job Value","description":"The average job value of all permits in cents (integer value representing dollars × 100).","uniqueKey":"\\items.items.[INDEX].avg_job_value.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].avg_job_value","typeLabel":"integer | null"},"total_job_value":{"oneOf":[{"type":"integer","title":"Total Job Value","description":"The total job value of all permits in cents (integer value representing dollars × 100).","uniqueKey":"\\items.items.[INDEX].total_job_value.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Total Job Value","description":"The total job value of all permits in cents (integer value representing dollars × 100).","uniqueKey":"\\items.items.[INDEX].total_job_value.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].total_job_value","typeLabel":"integer | null"},"avg_construction_duration":{"oneOf":[{"type":"integer","title":"Avg Construction Duration","description":"The average construction duration in days.","uniqueKey":"\\items.items.[INDEX].avg_construction_duration.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Avg Construction Duration","description":"The average construction duration in days.","uniqueKey":"\\items.items.[INDEX].avg_construction_duration.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].avg_construction_duration","typeLabel":"integer | null"},"avg_inspection_pass_rate":{"oneOf":[{"type":"integer","title":"Avg Inspection Pass Rate","description":"The average inspection pass rate as a percentage (0-100).","uniqueKey":"\\items.items.[INDEX].avg_inspection_pass_rate.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Avg Inspection Pass Rate","description":"The average inspection pass rate as a percentage (0-100).","uniqueKey":"\\items.items.[INDEX].avg_inspection_pass_rate.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].avg_inspection_pass_rate","typeLabel":"integer | null"},"first_seen_date":{"oneOf":[{"type":"string","title":"First Seen Date","description":"Date when the contractor was first seen in the system.","format":"date","uniqueKey":"\\items.items.[INDEX].first_seen_date.oneOf.0","typeLabel":"string\u003cdate>"},{"type":"null","title":"First Seen Date","description":"Date when the contractor was first seen in the system.","uniqueKey":"\\items.items.[INDEX].first_seen_date.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].first_seen_date","typeLabel":"string\u003cdate> | null"}},"type":"object","required":["id","address"],"title":"ContractorsRead","description":"Schema for contractor response with embedded address.","uniqueKey":"\\items.items.[INDEX]","typeLabel":"ContractorsRead · object"},"type":"array","title":"Items","description":"The list of items returned in the response following given criteria.","isRequired":true,"uniqueKey":"\\items","typeLabel":"ContractorsRead · object[]"},"size":{"type":"integer","title":"Size","description":"The number of items returned in the response.","isRequired":true,"uniqueKey":"size","typeLabel":"integer"},"next_cursor":{"oneOf":[{"type":"string","title":"Next Cursor","description":"The cursor for retrieving the next page of results.","isRequired":true,"uniqueKey":"next_cursor.oneOf.0","typeLabel":"string"},{"type":"null","title":"Next Cursor","description":"The cursor for retrieving the next page of results.","isRequired":true,"uniqueKey":"next_cursor.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"next_cursor","typeLabel":"string | null"},"total_count":{"oneOf":[{"type":"object","title":"TotalCount","description":"Top-level count object, not an integer: {\"value\": 970, \"relation\": \"eq\"}. \"eq\" means an exact count up to 10,000. \"gte\" means at least 10,000 matches, with value set to 10,000. Counted only when requested on the first page without a cursor. null when not requested, on later pages, or when the count query times out.","required":["value","relation"],"example":{"relation":"eq","value":970},"properties":{"value":{"type":"integer","minimum":0,"title":"Value","description":"The count value; capped at the probe's cap (10,000 on the wire).","isRequired":true,"uniqueKey":"total_count.oneOf.0.value","typeLabel":"integer"},"relation":{"type":"string","enum":["eq","gte"],"title":"Relation","description":"\"eq\" means value is the exact count. \"gte\" means the actual count is at least value (the cap).","isRequired":true,"uniqueKey":"total_count.oneOf.0.relation","typeLabel":"enum\u003cstring>"}},"uniqueKey":"total_count.oneOf.0","typeLabel":"TotalCount · object"},{"type":"null","description":"Top-level count object, not an integer: {\"value\": 970, \"relation\": \"eq\"}. \"eq\" means an exact count up to 10,000. \"gte\" means at least 10,000 matches, with value set to 10,000. Counted only when requested on the first page without a cursor. null when not requested, on later pages, or when the count query times out.","example":{"relation":"eq","value":970},"uniqueKey":"total_count.oneOf.1","typeLabel":"null"}],"uniqueKey":"total_count","typeLabel":"TotalCount · object | null"}},"type":"object","required":["items","size","next_cursor"],"title":"PaginatedContractorsResponse","description":"Schema for paginated contractors details response.","uniqueKey":"","typeLabel":"PaginatedContractorsResponse · object"},"example":{"example":{"items":[{"id":"e79c3393ad","license":"961870","name":"CA SUNRISE CONSTRUCTION SOLUTION INC.","business_name":"CA SUNRISE CONSTRUCTION SOLUTION INC.","business_type":"Corporation","classification":"CFC","license_issue_date":"2018-05-15","license_exp_date":"2024-05-15","license_act_date":"2018-05-15","primary_phone":"(425) 507-4300","primary_email":"atobar.casunrise@gmail.com","phone":"(425) 270-9678,(425) 281-6152","email":"atobar.casunrise@gmail.com,david@calsunrise.com","dba":"SUNRISE SOLAR","sic":"1731","naics":"238210","linkedin_url":"https://linkedin.com/company/ca-sunrise-constr","revenue":"$1M-$5M","employee_count":"10-49","primary_industry":"Solar Installation","review_count":42,"rating":4.8,"status_tally":{"final":754,"active":81,"in_review":2,"inactive":313},"tag_tally":{"hvac":27,"solar":39,"roofing":1,"pool_and_hot_tub":1,"heat_pump":267,"electrical":1110,"new_construction":20},"permit_count":1150,"avg_job_value":1500000,"total_job_value":172500000,"avg_construction_duration":45,"avg_inspection_pass_rate":85,"address":{"street_no":"2800","street":"COTTONWOOD DR","city":"SAN BRUNO","zip_code":"94066","state":"CA","address_id":"asd8a8b19","latlng":[37.37619,-121.869064]}}],"size":1}},"examples":{"Example":{"title":"Example","value":{"example":{"items":[{"id":"e79c3393ad","license":"961870","name":"CA SUNRISE CONSTRUCTION SOLUTION INC.","business_name":"CA SUNRISE CONSTRUCTION SOLUTION INC.","business_type":"Corporation","classification":"CFC","license_issue_date":"2018-05-15","license_exp_date":"2024-05-15","license_act_date":"2018-05-15","primary_phone":"(425) 507-4300","primary_email":"atobar.casunrise@gmail.com","phone":"(425) 270-9678,(425) 281-6152","email":"atobar.casunrise@gmail.com,david@calsunrise.com","dba":"SUNRISE SOLAR","sic":"1731","naics":"238210","linkedin_url":"https://linkedin.com/company/ca-sunrise-constr","revenue":"$1M-$5M","employee_count":"10-49","primary_industry":"Solar Installation","review_count":42,"rating":4.8,"status_tally":{"final":754,"active":81,"in_review":2,"inactive":313},"tag_tally":{"hvac":27,"solar":39,"roofing":1,"pool_and_hot_tub":1,"heat_pump":267,"electrical":1110,"new_construction":20},"permit_count":1150,"avg_job_value":1500000,"total_job_value":172500000,"avg_construction_duration":45,"avg_inspection_pass_rate":85,"address":{"street_no":"2800","street":"COTTONWOOD DR","city":"SAN BRUNO","zip_code":"94066","state":"CA","address_id":"asd8a8b19","latlng":[37.37619,-121.869064]}}],"size":1}}}},"exampleType":"examples"}},"exampleType":"examples"},"ce3c5432-01c2-4f0a-b306-cc7145e9a831":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"},"input":{"oneOf":[{"title":"Input"}],"uniqueKey":"detail.items.[INDEX].input","typeLabel":"any"},"ctx":{"type":"object","title":"Context","uniqueKey":"detail.items.[INDEX].ctx","typeLabel":"Context · object"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>","input":"\u003cunknown>","ctx":{}}]}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"1545a1b4-da8a-4ead-aaa6-f5ae297a0080":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","scopes":[],"schemeName":"APIKeyHeader"}}},"servers":{"93374fb2-01d3-412c-b619-45b0cd831bff":{"url":"https://api.shovels.ai/v2","description":"Shovels API"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"X-API-Key","scopes":[],"schemeName":"APIKeyHeader"},"schema":{"title":"X-API-Key","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"APIKeyHeader","name":"X-API-Key"}],"title":"APIKeyHeader"}]},"originalFileLocation":"https://api.shovels.ai/spec/v2/openapi.production.yaml"},"subdomain":"shovelsai","siteName":"Shovels Documentation","title":"Search Contractors - Shovels Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-17T00:14:09.904Z","originalFileLocation":"api-reference/contractors/search-contractors.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., \u0026#x27;installing\u0026#x27; matches \u0026#x27;install\u0026#x27;). Multi-word queries use AND semantics (e.g., \u0026#x27;solar panel\u0026#x27; finds permits mentioning both words). NOTE: Contractors are ordered by the start date of the most recent permit on which they worked.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Shovels Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Search Contractors - Shovels Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., \u0026#x27;installing\u0026#x27; matches \u0026#x27;install\u0026#x27;). Multi-word queries use AND semantics (e.g., \u0026#x27;solar panel\u0026#x27; finds permits mentioning both words). NOTE: Contractors are ordered by the start date of the most recent permit on which they worked.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Shovels Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.shovels.ai/api-reference/contractors/search-contractors\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://docs.shovels.ai/assets/shovels-logo.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Search Contractors - Shovels Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., \u0026#x27;installing\u0026#x27; matches \u0026#x27;install\u0026#x27;). Multi-word queries use AND semantics (e.g., \u0026#x27;solar panel\u0026#x27; finds permits mentioning both words). NOTE: Contractors are ordered by the start date of the most recent permit on which they worked.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://docs.shovels.ai/assets/shovels-logo.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Shovels Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#01654D\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.shovels.ai/api-reference/contractors/search-contractors\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/contractors/search-contractors.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.shovels.ai/#organization\",\"name\":\"Shovels Documentation\",\"url\":\"https://docs.shovels.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/shovelsai/RpZdSdGGx61eI0yq/assets/shovels-logo.png?fit=max\u0026auto=format\u0026n=RpZdSdGGx61eI0yq\u0026q=85\u0026s=4580f7cd0725b33ba31367d40fda3bbf\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.shovels.ai#website\",\"name\":\"Shovels Documentation\",\"url\":\"https://docs.shovels.ai\",\"publisher\":{\"@id\":\"https://docs.shovels.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors#webpage\",\"url\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors\",\"name\":\"Search Contractors\",\"description\":\"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., 'installing' matches 'install'). Multi-word queries use AND semantics (e.g., 'solar panel' finds permits mentioning both words). NOTE: Contractors are ordered by the start date of the most recent permit on which they worked.\",\"dateModified\":\"2026-11-17T00:14:09.904Z\",\"isPartOf\":{\"@id\":\"https://docs.shovels.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.shovels.ai/api-reference/permits/search-permits\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Contractors\",\"item\":\"https://docs.shovels.ai/api-reference/contractors/get-contractors-by-id\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Search Contractors\",\"item\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors#apireference\",\"headline\":\"Search Contractors\",\"name\":\"Search Contractors\",\"description\":\"Returns contractors doing work within the given location area filtered by type of work. Contractors must meet all specified parameters, with multiple parameters treated as AND queries. Use contractor_classification_derived to filter by derived classifications (ALL specified values required). The permit_q parameter uses full-text search with English stemming (e.g., 'installing' matches 'install'). Multi-word queries use AND semantics (e.g., 'solar panel' finds permits mentioning both words). NOTE: Contractors are ordered by the start date of the most recent permit on which they worked.\",\"url\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors\",\"mainEntityOfPage\":{\"@id\":\"https://docs.shovels.ai/api-reference/contractors/search-contractors#webpage\"},\"image\":\"https://docs.shovels.ai/assets/shovels-logo.png\",\"dateModified\":\"2026-11-17T00:14:09.904Z\",\"publisher\":{\"@id\":\"https://docs.shovels.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.shovels.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Shovels Documentation\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Shovels Documentation\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/contractors/search-contractors.md","siteName":"Shovels Documentation","nav":{"global":{"anchors":[{"anchor":"Data Dictionary","icon":"book-open-cover","href":"https://www.shovels.ai/data-dictionary"},{"anchor":"Coverage Dashboard","icon":"map-pin","href":"https://www.shovels.ai/coverage"},{"anchor":"Community","icon":"discord","href":"https://discord.gg/Nypja3cKDx"},{"anchor":"Blog","icon":"newspaper","href":"https://www.shovels.ai/blog/"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/docs/introduction"}]},{"tab":"API Reference","groups":[{"group":"Getting Started","pages":[{"title":"About the API Reference","href":"/docs/api-reference-about"}]},{"group":"Endpoints","pages":[{"group":"Permits","pages":[{"title":"Search Permits","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /permits/search","href":"/api-reference/permits/search-permits"},{"title":"Get Permits By Id","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /permits","href":"/api-reference/permits/get-permits-by-id"}]},{"group":"Decisions","pages":[{"title":"Search Decisions","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /decisions/search","href":"/api-reference/decisions/search-decisions"},{"title":"Get Decisions By Id","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /decisions","href":"/api-reference/decisions/get-decisions-by-id"}]},{"group":"Contractors","pages":[{"title":"Get Contractors By Id","description":"Returns contractors by their IDs. Multiple `id` query parameters can be provided in the same API call","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors","href":"/api-reference/contractors/get-contractors-by-id"},{"title":"Search Contractors","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors/search","href":"/api-reference/contractors/search-contractors"},{"title":"Get Permits By Contractor Id","description":"Retrieves all permits associated with a single contractor.","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors/{id}/permits","href":"/api-reference/contractors/get-permits-by-contractor-id"},{"title":"Get Contractor Employees","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors/{id}/employees","href":"/api-reference/contractors/get-contractor-employees"},{"title":"Get Filtered Metrics By Contractor Id","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /contractors/{id}/metrics","href":"/api-reference/contractors/get-filtered-metrics-by-contractor-id"}]},{"group":"Addresses","pages":[{"title":"Search Addresses","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /addresses/search","href":"/api-reference/addresses/search-addresses"},{"title":"Get Address Metrics Monthly","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /addresses/{geo_id}/metrics/monthly","href":"/api-reference/addresses/get-address-metrics-monthly"},{"title":"Get Address Metrics Current","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /addresses/{geo_id}/metrics/current","href":"/api-reference/addresses/get-address-metrics-current"},{"title":"Get Residents","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /addresses/{geo_id}/residents","href":"/api-reference/addresses/get-residents"}]},{"group":"Cities","pages":[{"title":"Search Cities","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /cities/search","href":"/api-reference/cities/search-cities"},{"title":"Get City Metrics Monthly","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /cities/{geo_id}/metrics/monthly","href":"/api-reference/cities/get-city-metrics-monthly"},{"title":"Get City Metrics Current","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /cities/{geo_id}/metrics/current","href":"/api-reference/cities/get-city-metrics-current"},{"title":"Get City Details","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /cities","href":"/api-reference/cities/get-city-details"}]},{"group":"Counties","pages":[{"title":"Search Counties","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /counties/search","href":"/api-reference/counties/search-counties"},{"title":"Get County Metrics Monthly","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /counties/{geo_id}/metrics/monthly","href":"/api-reference/counties/get-county-metrics-monthly"},{"title":"Get County Metrics Current","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /counties/{geo_id}/metrics/current","href":"/api-reference/counties/get-county-metrics-current"},{"title":"Get County Details","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /counties","href":"/api-reference/counties/get-county-details"}]},{"group":"Jurisdictions","pages":[{"title":"Search Jurisdictions","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /jurisdictions/search","href":"/api-reference/jurisdictions/search-jurisdictions"},{"title":"Get Jurisdiction Metrics Monthly","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /jurisdictions/{geo_id}/metrics/monthly","href":"/api-reference/jurisdictions/get-jurisdiction-metrics-monthly"},{"title":"Get Jurisdiction Metrics Current","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /jurisdictions/{geo_id}/metrics/current","href":"/api-reference/jurisdictions/get-jurisdiction-metrics-current"},{"title":"Get Jurisdiction Details","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /jurisdictions","href":"/api-reference/jurisdictions/get-jurisdiction-details"}]},{"group":"Zipcodes","pages":[{"title":"Search Zipcodes","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /zipcodes/search","href":"/api-reference/zipcodes/search-zipcodes"}]},{"group":"States","pages":[{"title":"Search States","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /states/search","href":"/api-reference/states/search-states"}]},{"group":"Meta","pages":[{"title":"Get Data Release Date","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /meta/release","href":"/api-reference/meta/get-data-release-date"},{"title":"Get Coverage","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /meta/coverage","href":"/api-reference/meta/get-coverage"}]},{"group":"Lists","pages":[{"title":"Get All Available Zip Codes","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /list/zip","href":"/api-reference/lists/get-all-available-zip-codes"},{"title":"Get All Available Tags","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /list/tags","href":"/api-reference/lists/get-all-available-tags"}]},{"group":"Properties","pages":[{"title":"Get Properties By Id","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /properties","href":"/api-reference/properties/get-properties-by-id"},{"title":"Search Properties","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /properties/search","href":"/api-reference/properties/search-properties"}]},{"group":"Usage","pages":[{"title":"Get Usage","deprecated":null,"version":null,"openapi":"https://api.shovels.ai/spec/v2/openapi.production.yaml get /usage","href":"/api-reference/usage/get-usage"}]}]}]},{"tab":"Release Notes","pages":[{"title":"Release Notes","href":"/release-notes/release-notes"}]},{"tab":"Knowledge Base","pages":[{"title":"Knowledge Base","href":"/docs/knowledge-base"}]}]},"basePath":"","title":"Search Contractors - Shovels Documentation","deploymentId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","buildId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-B6WFFOBL.js","utils-BN5um1KA.js","cloneDeep-C3md22mN.js","_Uint8Array-DLlL8L26.js","isObject-FP1Yky1u.js","utils-BSmbkXJR.js","addUniqueKeysToSchema-2tqcVnUE.js","snippetPresets-CtWfvr2J.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DkKHBy30.js","isEqual-O3q7y6pq.js","usePlaygroundInputsStore-Brc5H9UJ.js","shallow-C4L4xvbs.js","getApiPlaygroundDisplay-2bxyq_aI.js","CodeSnippet-BJu8ddd5.js","CodeSnippets-dazWmoqB.js","Page-CnLhKuUV.js","getPastedJson-Chy3Qa1S.js","icon-CyO7h3jh.js","MethodPill-Dle0_91v.js","DuplicateIcon-CVvWAf4a.js","createIcon-Di07A27B.js","DynamicMarkdown-C4w9kavL.js","SectionHeading-XiBebVYC.js","axios-vUo_bRtp.js","Markdown-DTeL0SpS.js","dist-OCScizqf.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","katex-YMM-FMeD.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js","AssistantPageLink-KcneGfMY.js"]}