GET
/
contractors
/
search
curl --request GET \
  --url https://api.shovels.ai/v2/contractors/search \
  --header 'X-API-Key: <api-key>'
{
  "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,
          "unknown": 2,
          "inactive": 313
        },
        "tag_tally": {
          "hvac": 27,
          "solar": 39,
          "reroof": 1,
          "pool_spa": 1,
          "heat_pump": 267,
          "utilities": 1110,
          "commercial": 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,
    "pagination_type": "cursor"
  }
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
permit_from
string
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
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

The keyword or phrase to search for in permit description.

Maximum length: 50
​
permit_status
string[] | null

Filter by one or more statuses: final, in_review, inactive, active.

Maximum 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.

​
permit_min_fees
integer | null

Filter by minimum permit fees.

​
permit_tags
string[] | null

Filter by one or more tags.

​
geo_id
string
required

Filter by the geolocation ID: address, city, zip code, county, etc.

​
property_type
string | null

Filter by property type: residential, commercial, industrial, agricultural, vacant land, exempt, miscellaneous, office, recreational.

​
property_min_market_value
integer | null

Minimum assessed market value of the property.

​
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_classifications
string[] | null

State license board classification or other certification codes.

​
contractor_name
string | null

Filter by contractor's name or part of their name.

​
contractor_website
string | null

Filter by contractor's website. Don't include the http(s):// prefix.

​
contractor_min_total_job_value
integer | null

Minimum lifetime job value of the contractor.

​
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

​
cursor
string | null

Cursor for pagination

​
page
integer | null

Page number for offset-based pagination (only used if cursor is not provided)

Required range: x >= 1
​
size
integer
default:50

Number of items per page

Required range: 1 <= x <= 100

Response

200
application/json

A list of contractors.

Schema for paginated contractors details response.