openapi: 3.1.0
info:
  title: Shovels Addresses Contractors API
  description: The Shovels API provides building permit intelligence and contractor data aggregated from 1,800+ jurisdictions across the United States. Access 130M+ building permits, 2.3M+ contractor profiles, property details, resident information, and geographic metrics. The API is used by materials suppliers, construction tech companies, energy and climate firms, home services companies, real estate professionals, and telecommunications providers to power sales, marketing, and market analytics.
  version: v2
  contact:
    name: Shovels Support
    url: https://docs.shovels.ai
    email: sales@shovels.ai
  termsOfService: https://www.shovels.ai/terms
servers:
- url: https://api.shovels.ai/v2
  description: Shovels API v2
security:
- ApiKeyAuth: []
tags:
- name: Contractors
paths:
  /contractors/search:
    get:
      operationId: searchContractors
      summary: Search Contractors
      description: Returns contractors doing work within the given location area. Supports filtering by permit date range, specialty, license type, inspection pass rate, and more. Useful for identifying qualified contractors and understanding their work history.
      tags:
      - Contractors
      parameters:
      - name: geo_id
        in: query
        required: true
        description: Location filter for the search area
        schema:
          type: string
      - name: permit_from
        in: query
        required: true
        description: Return permits that started on or after this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: permit_to
        in: query
        required: true
        description: Return permits that started on or before this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: name
        in: query
        description: Filter by contractor name
        schema:
          type: string
      - name: tags
        in: query
        description: Filter by permit tags (contractor specialties)
        schema:
          type: string
      - name: classification
        in: query
        description: Filter by contractor classification
        schema:
          type: string
      - name: min_inspection_pass_rate
        in: query
        description: Minimum inspection pass rate (0-1)
        schema:
          type: number
          minimum: 0
          maximum: 1
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page (1-100, default 50)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: include_count
        in: query
        description: Include total count in response
        schema:
          type: boolean
      responses:
        '200':
          description: List of contractors matching the search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractorListResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
  /contractors/{id}:
    get:
      operationId: getContractorById
      summary: Get Contractor By ID
      description: Retrieves detailed contractor information by unique ID, including business details, contact information, license data, and permit statistics.
      tags:
      - Contractors
      parameters:
      - name: id
        in: path
        required: true
        description: Unique contractor ID
        schema:
          type: string
      responses:
        '200':
          description: Contractor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contractor'
        '404':
          description: Contractor not found
  /contractors/{id}/permits:
    get:
      operationId: getContractorPermits
      summary: Get Contractor Permits
      description: Retrieves all permits associated with a specific contractor.
      tags:
      - Contractors
      parameters:
      - name: id
        in: path
        required: true
        description: Unique contractor ID
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: List of permits for the contractor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermitListResponse'
  /contractors/{id}/employees:
    get:
      operationId: getContractorEmployees
      summary: Get Contractor Employees
      description: Returns a paginated list of employees for a specific contractor, including contact information for decision makers.
      tags:
      - Contractors
      parameters:
      - name: id
        in: path
        required: true
        description: Unique contractor ID
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: List of contractor employees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeListResponse'
  /contractors/{id}/metrics:
    get:
      operationId: getContractorMetrics
      summary: Get Contractor Metrics
      description: Returns filtered performance metrics for a specific contractor.
      tags:
      - Contractors
      parameters:
      - name: id
        in: path
        required: true
        description: Unique contractor ID
        schema:
          type: string
      responses:
        '200':
          description: Contractor metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractorMetrics'
components:
  schemas:
    Contractor:
      type: object
      properties:
        id:
          type: string
          description: Unique contractor identifier
        name:
          type: string
          description: Contractor or business name
        license:
          type: string
          description: Contractor license number
        classification:
          type: string
          description: Contractor classification type
        phone:
          type: string
          description: Contact phone number
        email:
          type: string
          format: email
          description: Contact email address
        website:
          type: string
          format: uri
          description: Business website
        address:
          $ref: '#/components/schemas/Address'
        inspection_pass_rate:
          type: number
          description: Ratio of passed inspections (0-1)
        permit_count:
          type: integer
          description: Total number of associated permits
        tags:
          type: array
          items:
            type: string
          description: Contractor specialty tags
    EmployeeListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
        size:
          type: integer
        next_cursor:
          type: string
          nullable: true
    PermitListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Permit'
        size:
          type: integer
          description: Number of items returned
        next_cursor:
          type: string
          nullable: true
          description: Pagination cursor for next page
        total_count:
          $ref: '#/components/schemas/TotalCount'
    TotalCount:
      type: object
      properties:
        value:
          type: integer
          description: Total count value (capped at 10,000)
        relation:
          type: string
          enum:
          - eq
          - gte
          description: Whether the value is exact (eq) or a lower bound (gte)
    ValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  type: string
              msg:
                type: string
              type:
                type: string
    ContractorMetrics:
      type: object
      properties:
        contractor_id:
          type: string
        permit_count:
          type: integer
        inspection_pass_rate:
          type: number
        avg_job_value:
          type: number
        total_job_value:
          type: number
        active_permits:
          type: integer
    Permit:
      type: object
      properties:
        id:
          type: string
          description: Unique permit identifier
        status:
          type: string
          description: Current permit status (issued, approved, completed, expired, cancelled)
        issue_date:
          type: string
          format: date
          description: Date the permit was issued
        final_date:
          type: string
          format: date
          description: Date the permit was finalized
        description:
          type: string
          description: Description of the permitted work
        job_value:
          type: number
          description: Estimated value of the permitted job in dollars
        tags:
          type: array
          items:
            type: string
          description: Permit classification tags
        property_type:
          type: string
          description: Type of property (residential, commercial, industrial)
        address:
          $ref: '#/components/schemas/Address'
        contractor_id:
          type: string
          description: Associated contractor ID
        jurisdiction:
          type: string
          description: Jurisdiction that issued the permit
    Address:
      type: object
      properties:
        street_no:
          type: string
          description: Street number
        street:
          type: string
          description: Street name
        city:
          type: string
        county:
          type: string
        state:
          type: string
        zip_code:
          type: string
        jurisdiction:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        geo_id:
          type: string
          description: Unique geographic identifier for the address
        name:
          type: string
          description: Formatted full address
    ContractorListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Contractor'
        size:
          type: integer
        next_cursor:
          type: string
          nullable: true
        total_count:
          $ref: '#/components/schemas/TotalCount'
    Employee:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
        contractor_id:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from app.shovels.ai Profile Settings