Shovels · Schema

Shovels Contractor

A contractor profile from the Shovels API representing a licensed professional undertaking permitted construction projects.

ConstructionBuilding PermitsContractorsReal EstateProperty DataMarket Intelligence

Properties

Name Type Description
id string Unique Shovels contractor identifier
name string Contractor or business name
license string State-issued contractor license number
classification string Contractor classification type (e.g., General, Electrical, Plumbing, HVAC)
phone string Primary contact phone number
email string Primary contact email address
website string Business website URL
address object
inspection_pass_rate number AI-calculated ratio of inspections passed across all permits (0-1)
permit_count integer Total number of permits associated with this contractor
active_permits integer Number of currently active permits
tags array Contractor specialty tags derived from permit work types
avg_job_value number Average job value in US dollars across all permits
total_job_value number Total cumulative job value in US dollars
employees array Key employees and decision makers
View JSON Schema on GitHub

JSON Schema

shovels-contractor-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.shovels.ai/schemas/contractor",
  "title": "Shovels Contractor",
  "description": "A contractor profile from the Shovels API representing a licensed professional undertaking permitted construction projects.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique Shovels contractor identifier"
    },
    "name": {
      "type": "string",
      "description": "Contractor or business name"
    },
    "license": {
      "type": "string",
      "description": "State-issued contractor license number"
    },
    "classification": {
      "type": "string",
      "description": "Contractor classification type (e.g., General, Electrical, Plumbing, HVAC)"
    },
    "phone": {
      "type": "string",
      "description": "Primary contact phone number"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Primary contact email address"
    },
    "website": {
      "type": "string",
      "format": "uri",
      "description": "Business website URL"
    },
    "address": {
      "$ref": "#/$defs/Address"
    },
    "inspection_pass_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "AI-calculated ratio of inspections passed across all permits (0-1)"
    },
    "permit_count": {
      "type": "integer",
      "minimum": 0,
      "description": "Total number of permits associated with this contractor"
    },
    "active_permits": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of currently active permits"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Contractor specialty tags derived from permit work types"
    },
    "avg_job_value": {
      "type": "number",
      "minimum": 0,
      "description": "Average job value in US dollars across all permits"
    },
    "total_job_value": {
      "type": "number",
      "minimum": 0,
      "description": "Total cumulative job value in US dollars"
    },
    "employees": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Employee"
      },
      "description": "Key employees and decision makers"
    }
  },
  "required": ["id", "name"],
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "street_no": { "type": "string" },
        "street": { "type": "string" },
        "city": { "type": "string" },
        "county": { "type": "string" },
        "state": { "type": "string" },
        "zip_code": { "type": "string" },
        "geo_id": { "type": "string" },
        "name": { "type": "string" }
      }
    },
    "Employee": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "title": { "type": "string" },
        "phone": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      }
    }
  }
}