Skip to main content
GET
/
contractors
/
search
Search Contractors
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
  }
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
cursor
string | null

Cursor for pagination

​
size
integer
default:50
Required range: 1 <= x <= 100
​
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

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

Filter by derived contractor classifications. 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 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

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.

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