--- title: "Search Licenses" method: GET path: "/licenses" tags: ["licenses"] --- # Search Licenses `GET /licenses` ## Request - Base URL: `https://api.licenscheck.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.licenscheck.com/licenses` - Auth: none declared Search licenses by contractor/business name or license number, optionally filtered by state. A search term is required: `state` only narrows a name search, so the endpoint can't be used to page through a whole state's licenses. Without a paid key every request that returns licenses (each results page too) counts against a daily allowance; an empty or malformed search doesn't. The searches left are sent in `X-Searches-Remaining`. Args: q: Substring to match against contractor name, business name, or license number (validated by `SearchTerm`). state: State to narrow the search to. Omit to search every state. limit: Max results to return. offset: Number of matching results to skip, for pagination. Capped at the same bound as the match count, so a page past it can't be requested. response: The response, for the remaining-searches header. caller: Injected caller, for its daily search allowance. repo: Injected `LicenseRepository`. counts: Injected `SearchCountRepository`, where the allowance is counted. Returns: The matching page of licenses, plus the total match count. Raises: HTTPException: 429 once the caller's searches for today are used up. ## Query parameters - `q` string, required: Name, DBA, or license number to search for (required, 3-100 characters after trimming, with at least 3 letters or digits in a row). - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY': USPS two-letter abbreviation for each US state and the District of Columbia. Mirrored in airflow/dags/common/enums.py (kept dependency-free of this app -- see CLAUDE.md); test_airflow_enum_sync.py keeps the two in sync. - `limit` integer: Max results to return. - `offset` integer: Number of matching results to skip. ## Response `200` Successful Response - LicenseSearchOut: Response for GET /licenses (search/list). - `results` LicenseOut[], required: Matching licenses for this page. - `id` string, uuid, required: Internal UUID identifier for this license record. - `contractor_name` string, required: Individual contractor's name as registered with the state board. - `business_name` string, nullable, required: Registered business name, if the license is held by a business rather than an individual. - `license_number` string, required: The license number as issued by the state board. - `license_type` 'general_contractor' | 'building_contractor' | 'residential_contractor' | 'air_conditioning_contractor' | 'electrical_contractor' | 'roofing_contractor' | 'plumbing_contractor' | 'pool_spa_contractor' | 'mechanical_contractor' | 'sheet_metal_contractor' | 'utility_excavation_contractor' | 'solar_contractor' | 'specialty_contractor' | 'pollutant_storage_contractor' | 'precision_tank_tester' | 'other' | 'unknown', required: Normalized contractor trade category. Each state board has its own raw code vocabulary (e.g. Florida DBPR's "CBC", "RG", ...); each state's ingestion DAG maps its own codes onto this shared vocabulary. Folds a state's "statewide" vs "local" license classes (e.g. FL's Certified vs Registered) into the same category here -- that distinction isn't tracked separately (yet). - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY', required: USPS two-letter abbreviation for each US state and the District of Columbia. Mirrored in airflow/dags/common/enums.py (kept dependency-free of this app -- see CLAUDE.md); test_airflow_enum_sync.py keeps the two in sync. - `board` 'FL_DBPR' | 'CA_CSLB' | 'WA_LNI' | 'VA_DPOR' | 'OR_CCB' | 'AR_CLB' | 'MN_DLI' | 'TX_TDLR' | 'CT_DCP' | 'IL_IDFPR' | 'NY_DOL' | 'NYC_DOB' | 'NV_NSCB' | 'AZ_ROC' | 'NJ_DCA' | 'MA_OPSI' | 'TN_BLC' | 'TN_HIC' | 'MA_OCABR' | 'AL_GCB' | 'LA_LSLBC' | 'NC_LBGC' | 'NC_BEEC' | 'NC_PHFS' | 'OH_OCILB' | 'OH_SFM' | 'VT_DFS' | 'OK_CIB' | 'MS_BOC' | 'MS_BOC_RES' | 'WV_CLB' | 'CO_DORA' | 'NE_DOL' | 'PA_PHL' | 'TX_TSBPE' | 'MA_PLGF' | 'MA_ELEC' | 'MA_SMW' | 'PA_PGH' | 'NYC_DCWP' | 'OR_BCD' | 'MD_MCOCP' | 'MD_MCFRS' | 'OH_CLE' | 'CO_BOU' | 'DE_DPR' | 'IA_DIAL' | 'UT_DOPL' | 'WI_DSPS' | 'ND_SOS' | 'KY_HBC' | 'MD_MHIC' | 'MD_ELEC' | 'MD_HVACR' | 'MD_PLUMB' | 'DC_DLCP', required: The licensing body that issued a license; each value starts with its state's code. A state can have several (New York's Labor Dept. and NYC's Buildings Dept.), so a license is identified by its number, state and board. Attributes: FL_DBPR: Florida's Dept. of Business & Professional Regulation. CA_CSLB: California's Contractors State License Board. WA_LNI: Washington's Dept. of Labor & Industries. VA_DPOR: Virginia's Dept. of Professional & Occupational Regulation. OR_CCB: Oregon's Construction Contractors Board. AR_CLB: Arkansas's Contractors Licensing Board. MN_DLI: Minnesota's Dept. of Labor and Industry. TX_TDLR: Texas's Dept. of Licensing & Regulation. CT_DCP: Connecticut's Dept. of Consumer Protection. IL_IDFPR: Illinois's Dept. of Financial & Professional Regulation. NY_DOL: New York State's Dept. of Labor (public-work registry, mold and elevator contractors). NYC_DOB: New York City's Dept. of Buildings. NV_NSCB: Nevada's State Contractors Board. AZ_ROC: Arizona's Registrar of Contractors. NJ_DCA: New Jersey's Division of Consumer Affairs (home improvement, electrical, plumbing and HVACR boards). MA_OPSI: Massachusetts's Office of Public Safety and Inspections (construction supervisors and trade contractors). TN_BLC: Tennessee's Board for Licensing Contractors (contractor licenses). TN_HIC: Tennessee's Board for Licensing Contractors' home improvement licenses, numbered apart from its contractor licenses (301 numbers are on both on 2026-10-09). MA_OCABR: Massachusetts's Office of Consumer Affairs and Business Regulation (home improvement contractor registrations, through the MA Contractor Hub). AL_GCB: Alabama's Licensing Board for General Contractors (prime and subcontractor licenses). LA_LSLBC: Louisiana's Licensing Board for Contractors (commercial, residential, home improvement and mold remediation licenses). NC_LBGC: North Carolina's Licensing Board for General Contractors. NC_BEEC: North Carolina's State Board of Examiners of Electrical Contractors. NC_PHFS: North Carolina's State Board of Examiners of Plumbing, Heating and Fire Sprinkler Contractors. OH_OCILB: Ohio's Construction Industry Licensing Board (electrical, HVAC, plumbing, hydronics, refrigeration). OH_SFM: Ohio's State Fire Marshal (fire protection companies). VT_DFS: Vermont's Division of Fire Safety (master and special electricians and plumbers). OK_CIB: Oklahoma's Construction Industries Board (roofing contractor registrations). MS_BOC: Mississippi's State Board of Contractors, commercial program. MS_BOC_RES: Mississippi's State Board of Contractors, residential program (numbered apart from commercial). WV_CLB: West Virginia's Contractor Licensing Board. CO_DORA: Colorado's Dept. of Regulatory Agencies (its Electrical and Plumbing Boards). NE_DOL: Nebraska's Dept. of Labor (contractor registration). PA_PHL: Philadelphia's Dept. of Licenses and Inspections (a city; Pennsylvania has no statewide license). TX_TSBPE: Texas's State Board of Plumbing Examiners (responsible master plumbers). MA_PLGF: Massachusetts's Board of State Examiners of Plumbers and Gas Fitters. MA_ELEC: Massachusetts's Board of State Examiners of Electricians. MA_SMW: Massachusetts's Board of Examiners of Sheet Metal Workers. PA_PGH: Pittsburgh's Dept. of Permits, Licenses, and Inspections (a city, like PA_PHL). NYC_DCWP: New York City's Dept. of Consumer and Worker Protection (home improvement contractors). OR_BCD: Oregon's Building Codes Division (electrical, plumbing, boiler and elevator contractors). MD_MCOCP: Montgomery County, Maryland's Office of Consumer Protection (new home builders; a county). MD_MCFRS: Montgomery County, Maryland's Fire and Rescue Service (fire alarm system licenses; a county). OH_CLE: Cleveland's Dept. of Building & Housing (contractor registrations; a city). CO_BOU: The City of Boulder's Planning & Development Services (contractor licenses; a city). DE_DPR: Delaware's Division of Professional Regulation (master electricians, plumbers and HVACR). IA_DIAL: Iowa's Dept. of Inspections, Appeals, and Licensing (construction contractor registrations). UT_DOPL: Utah's Division of Professional Licensing (its opt-in Construction Business Registry). WI_DSPS: Wisconsin's Dept. of Safety and Professional Services (contractors and master plumbers). ND_SOS: North Dakota's Secretary of State (contractor licenses, Classes A-D). KY_HBC: Kentucky's Dept. of Housing, Buildings and Construction (electrical, HVAC, plumbing, fire protection). MD_MHIC: Maryland's Home Improvement Commission. MD_ELEC: Maryland's State Board of Master Electricians. MD_HVACR: Maryland's State Board of HVACR Contractors. MD_PLUMB: Maryland's State Board of Plumbing. DC_DLCP: The District of Columbia's Dept. of Licensing and Consumer Protection (contractor business licenses). - `status` 'active' | 'inactive' | 'probation' | 'expired' | 'suspended' | 'revoked', required: Current status of a contractor license, as reported by its state board. - `issue_date` string, date, nullable, required: Date the license was originally issued. - `expiration_date` string, date, nullable, required: Date the license expires or expired. - `bond_number` string, nullable, required: Surety bond number backing this license, if applicable. - `bond_amount` number, nullable, required: Surety bond amount in USD, if applicable. - `address` string, nullable, required: Registered business or contractor address on file with the state board. - `phone` string, nullable, required: Business phone as 10 NANP digits with no formatting, or null when the board reports none (or only a placeholder). - `state_business_id` string, nullable, required: The issuing state's own business-registration id (e.g. Washington's UBI). Only comparable between licenses from the same state. - `principal_name` string, nullable, required: The owner/principal of record, in the board's own name format. - `last_verified_at` string, date-time, nullable, required: When this license was last confirmed against the state board's live record. - `delisted_at` string, date-time, nullable, required: When this license disappeared from the state board's full listing, or null while the board still lists it. When set, `status` is the last value the board reported and may be stale. - `board_alerts` BoardAlertOut[]: Warnings the board publishes beyond `status`; empty for almost every license. - `code` 'enforcement_action' | 'pending_suspension' | 'pending_class_removal' | 'pending_case' | 'insurance_lapsed' | 'bond_lapsed' | 'bond_cancelling' | 'past_discipline' | 'debarred' | 'unpaid_wage_assessment', required: A warning a state board publishes about a license on top of its status, e.g. a pending suspension. Attributes: ENFORCEMENT_ACTION: The board reports an enforcement action, without saying what (MN's Enforcement_Action). PENDING_SUSPENSION: A suspension is scheduled for the alert's date (CA's PendingSuspension). PENDING_CLASS_REMOVAL: A classification is to be removed on the alert's date (CA's PendingClassRemoval). PENDING_CASE: An open case, citation or judgment against the license (CA "Pending Case/CIT", "Judgement Pend"). INSURANCE_LAPSED: Required insurance isn't in force (CA "does not have current W/C", OR insurance expiry passed). BOND_LAPSED: The license bond has expired or is unpaid (OR bond expiry passed, CA "BOND Pay Pending"), or its cancellation date has passed while the license still reads clear (CA's CBCancellationDate). BOND_CANCELLING: The surety has filed a bond cancellation taking effect on the alert's date (CA's CBCancellationDate); most such licenses are suspended when it takes effect. PAST_DISCIPLINE: A disciplinary record is on file while the license is in good standing (CA disciplinary bond). DEBARRED: The business is barred from public work until the alert's date, or with no end date (NY DOL). UNPAID_WAGE_ASSESSMENT: The business owes wages or penalties the labor department assessed (NY DOL). - `on` string, date, nullable, required: The date the alert is about, when the board gives one. - `detail` string, nullable: The board's own wording or case number behind the alert, e.g. "WC Susp Pending" or "Case 2016000394". - `federal_exclusions` FederalExclusionOut[]: SAM.gov exclusions in force that match this license by name and address; empty for almost every license. A match asks for review, never risk. - `name` string, required: The excluded firm or person, as SAM.gov lists them. - `location` string, required: Their city and state on SAM.gov. - `agency` string, required: The agency that excluded them, e.g. "the Army". - `type` string, required: SAM.gov's exclusion type, e.g. "Ineligible (Proceedings Completed)". - `since` string, date, required: When the exclusion took effect. - `until` string, date, nullable, required: When it ends, or null when it has no end date. - `matched_on` string, required: What the match rests on besides the name: "name and street address", or "name and ZIP code" (firms only). Never a license number: confirm it is this contractor. - `entity_type` 'sole_proprietor' | 'llc' | 'corporation' | 'partnership' | 'limited_partnership' | 'llp' | 'joint_venture' | 'association' | 'trust': The legal form of the licensed business, as the board records it. Attributes: SOLE_PROPRIETOR: One person trading in their own name (CA "Sole Owner", WA "Individual"). LLC: A limited liability company. CORPORATION: A corporation. PARTNERSHIP: A general partnership. LIMITED_PARTNERSHIP: A limited partnership. LLP: A limited liability partnership. JOINT_VENTURE: A joint venture of two or more businesses. ASSOCIATION: An association. TRUST: A trust. - `board_details` BoardDetailOut[]: State-specific facts from the board, in display order: project limits, bond surety, insurance carrier and similar. Empty when the board publishes none. - `key` string, required: Stable key, for code that reads one value: license_class, project_limit, bond_surety, status_since, workers_comp, liability_insurance, asbestos_certification, temporary_license, renewal_in_progress, scope_limit. New keys may be added. - `label` string, required: How to label it for people, e.g. "Project limit". - `value` string, required: The fact as plain text, e.g. "Under $150,000 a project, under $1M a year". - `created_at` string, date-time, required: When this license record was first ingested. - `total` integer, required: Total number of matches across all pages, before limit/offset. When `total_is_exact` is false this is either the 10,000 count cap (a search with more matches than that) or the table's estimated row count (an unfiltered listing). - `total_is_exact` boolean, required: Whether `total` is an exact count rather than a cap or estimate. ## Other responses - `422`: Validation Error - `429`: Today's searches are used up (10 a day without a key, 50 with a free key); Retry-After says when they reset, at midnight UTC. --- [API](https://skmtc.dev/licenscheck/apis/licenscheck-api.md) · [All operations](https://skmtc.dev/licenscheck/apis/licenscheck-api/llms.txt) · [OpenAPI document](https://skmtc.dev/licenscheck/apis/licenscheck-api/revisions/472db933f385?raw)