GET
/
contractors
/
{id}
/
permits
Get Permits By Contractor Id
curl --request GET \
  --url https://api.shovels.ai/v2/contractors/{id}/permits \
  --header 'X-API-Key: <api-key>'
{
  "items": [
    {
      "property_census_tract": "101",
      "property_congressional_district": "1",
      "property_type": "residential",
      "property_type_detail": "single_family_home",
      "property_legal_owner": "OAKLAND HOUSING AUTHORITY",
      "property_owner_type": "individual",
      "property_lot_size": 4000,
      "property_building_area": 1000,
      "property_story_count": 1,
      "property_unit_count": 1,
      "property_year_built": 1970,
      "property_assess_market_value": 1050000,
      "id": "caf3b9d5ce317d53",
      "number": "RE2303928",
      "description": "Battery backup",
      "jurisdiction": "Berkeley",
      "type": "Re) - electrical - 1 & 2 unit residential (building)",
      "fees": 61960,
      "status": "active",
      "file_date": "2023-10-02",
      "issue_date": "2023-10-11",
      "final_date": "2023-12-11",
      "start_date": "2022-10-19",
      "end_date": "2023-12-11",
      "total_duration": 230,
      "construction_duration": 61,
      "approval_duration": 9,
      "contractor_id": "KOm4dMLIuT",
      "tags": [
        "solar",
        "battery"
      ],
      "address": {
        "street_no": "3360",
        "street": "DWIGHT WAY",
        "city": "OAKLAND",
        "zip_code": "94704",
        "state": "CA",
        "latlng": [
          37.868443,
          -122.24374
        ]
      },
      "geo_ids": {
        "address_id": "asd8a8b19",
        "city_id": "KLais31",
        "county_id": "ALa2s33",
        "jurisdiction_id": "BLa2s33"
      }
    },
    {
      "property_census_tract": "101",
      "property_congressional_district": "1",
      "property_type": "residential",
      "property_type_detail": "single_family_home",
      "property_legal_owner": "OAKLAND HOUSING AUTHORITY",
      "property_owner_type": "individual",
      "property_lot_size": 4000,
      "property_building_area": 1000,
      "property_story_count": 1,
      "property_unit_count": 1,
      "property_year_built": 1970,
      "property_assess_market_value": 1050000,
      "id": "71c02bd70f7ce1c9",
      "number": "E2304692",
      "description": "Install 27 kwh back-up batteries in cabinet ",
      "jurisdiction": "Berkeley",
      "type": "E) - electrical - 3+ residential units or commercial",
      "fees": 61506,
      "status": "in_review",
      "file_date": "2023-11-29",
      "start_date": "2022-11-29",
      "end_date": "2023-11-29",
      "total_duration": 0,
      "construction_duration": 154,
      "approval_duration": 204,
      "tags": [
        "solar"
      ],
      "address": {
        "street_no": "544",
        "street": "DWIGHT PL",
        "city": "OAKLAND",
        "zip_code": "94704",
        "state": "CA",
        "latlng": [
          37.8671,
          -122.24461
        ]
      },
      "geo_ids": {
        "address_id": "1sd8a8b19",
        "city_id": "KLais31",
        "county_id": "ALa2s33",
        "jurisdiction_id": "BLa2s33"
      }
    },
    {
      "property_census_tract": "101",
      "property_congressional_district": "1",
      "property_type": "residential",
      "property_type_detail": "single_family_home",
      "property_legal_owner": "OAKLAND HOUSING AUTHORITY",
      "property_owner_type": "individual",
      "property_lot_size": 4000,
      "property_building_area": 1000,
      "property_story_count": 1,
      "property_unit_count": 1,
      "property_year_built": 1970,
      "property_assess_market_value": 1050000,
      "id": "9525a96a93e0cdb7",
      "number": "B2303829",
      "description": "Install 27 kwh back-up batteries in cabinet",
      "jurisdiction": "Berkeley",
      "job_value": 500100,
      "type": "Building alteration: 3+ residential units or commercial",
      "fees": 795300,
      "status": "in_review",
      "file_date": "2023-11-29",
      "start_date": "2022-11-29",
      "end_date": "2023-11-29",
      "total_duration": 0,
      "construction_duration": 154,
      "approval_duration": 204,
      "tags": [
        "solar"
      ],
      "address": {
        "street_no": "544",
        "street": "DWIGHT PL",
        "city": "OAKLAND",
        "zip_code": "94704",
        "state": "CA",
        "latlng": [
          37.8671,
          -122.24461
        ]
      },
      "geo_ids": {
        "address_id": "1sd8a8b19",
        "city_id": "KLais31",
        "county_id": "ALa2s33",
        "jurisdiction_id": "BLa2s33"
      }
    }
  ],
  "page": 1,
  "size": 3
}

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
id
string
required

Filter by the specified contractor ID.

Query Parameters

​
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

A list of permits associated with the contractor and grouped by address

Schema for paginated permits details response.

​
items
PermitsRead · object[]
required

The list of items returned in the response following given criteria.

​
page
integer
required

The page number of the response.

​
size
integer
required

The number of items returned in the response.

​
next_page
integer | null
required

The next page number of the response.

​
pagination_type
string
default:offset
Allowed value: "offset"