Skip to content

README.md

Latest commit

 

History

History
154 lines (104 loc) · 21.1 KB

README.md

File metadata and controls

154 lines (104 loc) · 21.1 KB
Raw

Contractors

Overview

Search contractors and see their permit history

Available Operations

search_contractors

Search contractors by name, location, or specialty, ranked by activity score.

Example Usage

import os
from permitstack import Permitstack


with Permitstack(
    api_key=os.getenv("PERMITSTACK_API_KEY", ""),
) as p_client:

    res = p_client.contractors.search_contractors(sort="score", page=1, per_page=25)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
name OptionalNullable[str] ➖ Contractor name (partial match)
state OptionalNullable[str] ➖ 2-letter state code
city OptionalNullable[str] ➖ City name
specialty OptionalNullable[str] ➖ Specialty tag (e.g. solar, roofing, hvac)
license_number OptionalNullable[str] ➖ Exact state licence number, e.g. 'CBC1262595'. Matched exactly, and also tried uppercased -- so any capitalisation works for the licences stored uppercase, which is 99.96% of them. Combine with license_state when the same number is issued in more than one state.
license_state OptionalNullable[str] ➖ 2-letter state that ISSUED the licence. Not the same as state, which is where the contractor pulls permits.
min_permits OptionalNullable[int] ➖ Minimum total permits
min_score OptionalNullable[int] ➖ Minimum contractor activity score (0-100)
sort Optional[str] ➖ Sort order: 'score' (default), 'permits', or 'recent'
page Optional[int] ➖ N/A
per_page Optional[int] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ContractorSearchResponse

Errors

Error Type Status Code Content Type
errors.HTTPValidationError 422 application/json
errors.ErrorDetail 401, 429 application/json
errors.PermitstackDefaultError 4XX, 5XX */*

get_contractor

Get a contractor's full profile with permit stats.

phone and email are contractor contact fields gated to the Developer plan and up (see /v1/billing/plans for current pricing); on free/indie/hobbyist they return null. name, license_number, specialties, city/state/address, and the stats are available on all plans.

Example Usage

import os
from permitstack import Permitstack


with Permitstack(
    api_key=os.getenv("PERMITSTACK_API_KEY", ""),
) as p_client:

    res = p_client.contractors.get_contractor(contractor_id="d886f7c0-9af0-429f-a2d4-dfe6f2f526ae")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
contractor_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ContractorProfile

Errors

Error Type Status Code Content Type
errors.HTTPValidationError 422 application/json
errors.ErrorDetail 401, 429 application/json
errors.PermitstackDefaultError 4XX, 5XX */*

get_contractor_permits

Get all permits associated with a contractor.

Example Usage

import os
from permitstack import Permitstack


with Permitstack(
    api_key=os.getenv("PERMITSTACK_API_KEY", ""),
) as p_client:

    res = p_client.contractors.get_contractor_permits(contractor_id="a9c0dbb7-1080-46cd-85f9-7abfb02d5914", page=1, per_page=25)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
contractor_id str ✔️ N/A
page Optional[int] ➖ N/A
per_page Optional[int] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

Any

Errors

Error Type Status Code Content Type
errors.HTTPValidationError 422 application/json
errors.ErrorDetail 401, 429 application/json
errors.PermitstackDefaultError 4XX, 5XX */*