Field-level documentation for every entity in the unified dataset. Fields are classified as base (always served) or contact (PII — contact-tier entitlement required).
The core permit record from municipal portals. Each row represents one permit application.
| Field | Type | Tier | Description |
|---|---|---|---|
| bm_permit_id | uuid | base | Builders Monitor internal permit UUID. |
| bm_job_id | uuid | base | Job/project grouping key (one job may have multiple permits). |
| bm_property_id | uuid | base | Foreign key to the property record. |
| permit_number | text | base | Source permit number as issued by the jurisdiction. |
| parent_permit_number | text | base | Parent permit for sub-permits. |
| permit_type | text | base | Canonical permit type (e.g. Building, Electrical, Plumbing). |
| permit_subtype | text | base | Sub-classification within the permit type. |
| work_class | text | base | Work classification (e.g. New Construction, Addition, Repair). |
| description | text | base | Free-text description of the permitted work. |
| valuation | numeric | base | Declared project valuation in USD. |
| fee | numeric | base | Total permit fee charged. |
| sqft | numeric | base | Square footage of the permitted work. |
| units | integer | base | Number of dwelling units. |
| stories | integer | base | Number of stories. |
| applied_date | date | base | Date the permit application was submitted. |
| issued_date | date | base | Date the permit was issued/approved. |
| completed_date | date | base | Date construction was completed. |
| expires_date | date | base | Permit expiration date. |
| city | text | base | Municipality (from the joined property record). |
| state | text | base | 2-letter US state code. |
| zip | text | base | ZIP code. |
| county | text | base | County name. |
| longitude | float | base | Geocoded longitude (WGS84). |
| latitude | float | base | Geocoded latitude (WGS84). |
| parcel_id | text | base | Assessor parcel number (APN). |
| address | text | contact | Full street address (contact tier — re-identifies location). |
| address_raw | text | contact | Address as supplied by the source portal (contact tier). |
| street_number | text | contact | Street number component (contact tier). |
| street_name | text | contact | Street name component (contact tier). |
| unit | text | contact | Unit/suite component (contact tier). |
People and organizations named on permits as contractors, applicants, owners, or other roles. Sourced from permit contacts and certifications.
| Field | Type | Tier | Description |
|---|---|---|---|
| bm_entity_id | uuid | base | Builders Monitor entity UUID (deduplicated person/org). |
| bm_source_id | integer | base | Source jurisdiction ID. |
| kind | text | base | Entity type: person or organization. |
| license_state | text | base | State that issued the license. |
| license_type | text | base | License type (e.g. General Contractor, Electrical, Plumbing). |
| license_class | text | base | License classification. |
| license_status | text | base | License status (active, expired, suspended, etc.). |
| license_expiry | date | base | License expiration date. |
| city | text | base | City of the business address. |
| state | text | base | State of the business address. |
| entity_name | text | contact | Organization name (contact tier — PII). |
| first_name | text | contact | First name (contact tier — PII). |
| last_name | text | contact | Last name (contact tier — PII). |
| phone | text[] | contact | Phone numbers array (contact tier — PII). |
| text[] | contact | Email addresses array (contact tier — PII). | |
| license_number | text | contact | License number (contact tier — PII). |
| address | text | contact | Business address (contact tier — PII). |
| role | text | contact | Role on the permit (e.g. Contractor, Applicant, Owner). |
Individual inspection events linked to a permit. Each row is one scheduled or completed inspection.
| Field | Type | Tier | Description |
|---|---|---|---|
| bm_inspection_id | uuid | base | Builders Monitor inspection UUID. |
| bm_permit_id | uuid | base | Parent permit UUID. |
| bm_source_id | integer | base | Source jurisdiction ID. |
| inspection_type | text | base | Canonical inspection type (e.g. Framing, Electrical Rough, Final). |
| category | text | base | Inspection discipline category. |
| status | text | base | Inspection status (Scheduled, Passed, Failed, Cancelled). |
| outcome | text | base | Result outcome if completed. |
| scheduled_date | date | base | Scheduled inspection date. |
| actual_date | date | base | Actual inspection date. |
| is_reinspection | boolean | base | True if this is a re-inspection. |
| inspector_name | text | contact | Inspector full name (contact tier — PII). |
| inspector_email | text | contact | Inspector email address (contact tier — PII). |
| comments | text | contact | Inspector comments on the inspection result (contact tier). |
Individual fee line items assessed against a permit.
| Field | Type | Tier | Description |
|---|---|---|---|
| bm_fee_id | uuid | base | Builders Monitor fee UUID. |
| bm_permit_id | uuid | base | Parent permit UUID. |
| bm_source_id | integer | base | Source jurisdiction ID. |
| fee_type | text | base | Canonical fee category (e.g. Plan Check, Inspection, Impact). |
| amount | numeric | base | Fee amount in USD. |
| inserted_at | timestamptz | base | Row insertion timestamp. |
Code-enforcement violations linked to a permit or property. Currently a forward-looking spec; populated as coverage expands.
| Field | Type | Tier | Description |
|---|---|---|---|
| bm_violation_id | uuid | base | Builders Monitor violation UUID. |
| bm_permit_id | uuid | base | Associated permit UUID. |
| violation_code | text | base | Violation code as cited. |
| violation_description | text | base | Description of the cited violation. |
| status | text | base | Violation status (Open, Resolved, Dismissed). |
| violation_date | date | base | Date the violation was cited. |
| inspector_name | text | contact | Inspector who cited the violation (contact tier — PII). |
Documents and files attached to a permit (plans, certificates, photos). Metadata only — file bytes are not served through the API.
| Field | Type | Tier | Description |
|---|---|---|---|
| bm_attachment_id | uuid | base | Builders Monitor attachment UUID. |
| bm_permit_id | uuid | base | Parent permit UUID. |
| filename | text | base | Original filename. |
| file_type | text | base | MIME type or file extension. |
| document_type | text | base | Document category (e.g. Plan, Certificate, Photo). |
| file_size | bigint | base | File size in bytes. |
| url | text | base | Source URL (may require authentication at the origin portal). |
| upload_date | date | base | Date the document was uploaded. |
bm_permit_id, permit_number, permit_type, permit_subtype, description, valuation, applied_date, issued_date, updated_at, address, city, state, zip, longitude, latitudePOST /v1/exports) currently supports the permits category. Additional categories are available via the bulk-surface entitlement as coverage expands.