> ## Documentation Index
> Fetch the complete documentation index at: https://realtycrawl.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search US building permits for an address

> Search building-permit index records for one US street address through the Shovels source (v2). Supply address={formatted or line1+city,country:US}; permit_from/permit_to bound the permit date window (defaults: ten years back to today) and limit bounds returned records (default10). The source resolves the address to its geo_id then returns indexed jurisdiction filings; each returned record bills provider usage, checked against the configured run allowance. Success costs50 credits and stores one account-owned prop_shovels_ observation24h; retained property/record/permit reads1, errors/replay0. Permits are provider-indexed filings, not a complete permit history, title or contractor verification; coverage varies by jurisdiction. Source: Shovels pay-per-record API. Documentation-backed beta; not fresh live-source verification.

Search building-permit index records for one US street address through the Shovels pay-per-record source (v2). Supply `address={formatted:...}` or `address={line1,city,region or postal_code,country:\"US\"}`; optional `permit_from`/`permit_to` bound the permit date window (default: ten years back to today) and `limit` caps returned records (default10). Success costs50 credits and stores one account-owned `prop_shovels_` observation for24 hours; retained property, record and permit reads cost1 credit each, errors/no-match0.

The source first resolves the address to a provider `geo_id`, then returns indexed jurisdiction permit filings with file/issue/start/end/final dates, status, job value, fees, tags and contractor id. Provider usage bills per returned record, so the requested window is also bounded by the configured run allowance. Permits are provider-indexed filings — not a complete permit history, title, contractor verification or code-compliance proof; coverage varies across \~20k US jurisdictions and absence of records does not establish absence of work. This binding is documentation-backed beta.

> [!NOTE]
>
> Check [live capabilities](https://realtycrawl.dev/v1/meta/capabilities?platform=shovels) before calling this operation.

Requires SHOVELS\_API\_KEY, SHOVELS\_PLAN\_CONFIRMED and a bounded REALTYCRAWL\_SHOVELS\_RUN\_MAX\_USD.


## OpenAPI

````yaml POST /v1/permits/search
openapi: 3.1.0
info:
  title: RealtyCrawl API
  version: 0.1.0
  description: >-
    Unified real estate API with source-specific operations, markets and access
    requirements. Check current capabilities before source requests.
    Documentation-backed beta contracts require explicit configuration and do
    not establish fresh live source acceptance.
servers: []
security:
  - ApiKeyAuth: []
paths:
  /v1/permits/search:
    post:
      tags:
        - permits
      summary: Search US building permits for an address
      description: >-
        Search building-permit index records for one US street address through
        the Shovels source (v2). Supply address={formatted or
        line1+city,country:US}; permit_from/permit_to bound the permit date
        window (defaults: ten years back to today) and limit bounds returned
        records (default10). The source resolves the address to its geo_id then
        returns indexed jurisdiction filings; each returned record bills
        provider usage, checked against the configured run allowance. Success
        costs50 credits and stores one account-owned prop_shovels_
        observation24h; retained property/record/permit reads1, errors/replay0.
        Permits are provider-indexed filings, not a complete permit history,
        title or contractor verification; coverage varies by jurisdiction.
        Source: Shovels pay-per-record API. Documentation-backed beta; not fresh
        live-source verification.
      operationId: searchPermits
      parameters:
        - name: fields
          in: query
          description: >-
            Response-only comma-separated field paths relative to data items; up
            to 32 paths. Source requests and billing are unchanged.
          schema:
            type: string
            maxLength: 4127
        - name: format
          in: query
          description: >-
            Response-only export format. JSON retains the envelope; CSV/NDJSON
            contain data records, with request/credit metadata in headers.
            Errors stay JSON.
          schema:
            type: string
            enum:
              - json
              - csv
              - ndjson
            default: json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermitSearchRequest'
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchPermitsResponse'
            text/csv:
              schema:
                type: string
                description: Data rows only; request, row count and credits are in headers.
            application/x-ndjson:
              schema:
                type: string
                description: One JSON data item per line; metadata is in headers.
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PermitSearchRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressSelector'
        permit_from:
          type: string
          format: date
          description: >-
            Earliest permit start date (file/issue/start); defaults to ten years
            before today.
        permit_to:
          type: string
          format: date
          description: Latest permit end bound; defaults to today.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: >-
            Maximum permit records to return; each returned record bills
            provider usage, so the effective bound is also allowance-capped.
      required:
        - address
      additionalProperties: false
    searchPermitsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Permit'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - meta
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            details:
              type: array
              items:
                $ref: '#/components/schemas/SourceOutcome'
          required:
            - code
            - message
            - retryable
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    AddressSelector:
      oneOf:
        - type: object
          properties:
            formatted:
              type: string
              minLength: 3
            country:
              type: string
              pattern: ^[A-Z]{2}$
          required:
            - formatted
            - country
          additionalProperties: false
        - type: object
          properties:
            line1:
              type: string
              minLength: 1
            unit:
              anyOf:
                - type: string
                - type: 'null'
            city:
              type: string
              minLength: 1
            region:
              anyOf:
                - type: string
                - type: 'null'
            postal_code:
              anyOf:
                - type: string
                - type: 'null'
            country:
              type: string
              pattern: ^[A-Z]{2}$
            original_text:
              anyOf:
                - type: string
                - type: 'null'
          required:
            - line1
            - city
            - country
          additionalProperties: false
    Permit:
      type: object
      properties:
        id:
          type: string
        property_id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        permit_number:
          anyOf:
            - type: string
            - type: 'null'
        permit_type:
          anyOf:
            - type: string
            - type: 'null'
        description:
          anyOf:
            - type: string
            - type: 'null'
        status:
          anyOf:
            - type: string
            - type: 'null'
        jurisdiction:
          anyOf:
            - type: string
            - type: 'null'
        event_dates:
          type: object
          properties:
            filed:
              anyOf:
                - type: string
                  format: date
                - type: 'null'
            issued:
              anyOf:
                - type: string
                  format: date
                - type: 'null'
            started:
              anyOf:
                - type: string
                  format: date
                - type: 'null'
            ended:
              anyOf:
                - type: string
                  format: date
                - type: 'null'
            finaled:
              anyOf:
                - type: string
                  format: date
                - type: 'null'
          required:
            - filed
            - issued
            - started
            - ended
            - finaled
          additionalProperties: false
        durations_days:
          type: object
          properties:
            total:
              anyOf:
                - type: number
                - type: 'null'
            construction:
              anyOf:
                - type: number
                - type: 'null'
            approval:
              anyOf:
                - type: number
                - type: 'null'
          required:
            - total
            - construction
            - approval
          additionalProperties: false
        inspection_pass_rate:
          anyOf:
            - type: number
            - type: 'null'
        job_value:
          anyOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
        fees:
          anyOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
        tags:
          type: array
          items:
            type: string
        contractor_id:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - property_id
        - source
        - permit_number
        - permit_type
        - description
        - status
        - jurisdiction
        - event_dates
        - durations_days
        - inspection_pass_rate
        - job_value
        - fees
        - tags
        - contractor_id
      additionalProperties: false
    Meta:
      type: object
      properties:
        request_id:
          type: string
        schema_version:
          type: string
        generated_at:
          type: string
          format: date-time
        completeness:
          type: string
          enum:
            - complete
            - partial
            - unknown
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceOutcome'
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
            required:
              - code
              - message
            additionalProperties: false
        pagination:
          type: object
          properties:
            next_cursor:
              anyOf:
                - type: string
                - type: 'null'
            has_more:
              type: boolean
            returned:
              type: integer
            total:
              anyOf:
                - type: integer
                - type: 'null'
            total_relation:
              type: string
              enum:
                - exact
                - lower_bound
                - unknown
          required:
            - next_cursor
            - has_more
            - returned
            - total
            - total_relation
          additionalProperties: false
        property_groups:
          type: array
          items:
            $ref: '#/components/schemas/PropertyGroup'
      required:
        - request_id
        - schema_version
        - generated_at
        - completeness
        - sources
      additionalProperties: false
    SourceOutcome:
      type: object
      properties:
        platform:
          type: string
        provider:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - success
            - partial
            - failed
            - unsupported
        error_code:
          anyOf:
            - type: string
            - type: 'null'
        truncated:
          type: boolean
        observed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
      required:
        - platform
        - status
      additionalProperties: false
    Source:
      type: object
      properties:
        platform:
          type: string
        country:
          type: string
        native_id:
          anyOf:
            - type: string
            - type: 'null'
        url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
        provider:
          type: string
        observed_at:
          type: string
          format: date-time
        source_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        access_class:
          type: string
          enum:
            - public_portal
            - licensed_feed
            - public_record
            - modeled
        retrieved_at:
          type: string
          format: date-time
      required:
        - platform
        - provider
        - observed_at
        - access_class
      additionalProperties: false
    Money:
      type: object
      properties:
        amount:
          anyOf:
            - type: string
              pattern: ^-?\d+(\.\d+)?$
            - type: 'null'
        min:
          anyOf:
            - type: string
            - type: 'null'
        max:
          anyOf:
            - type: string
            - type: 'null'
        currency:
          anyOf:
            - type: string
              pattern: ^[A-Z]{3}$
            - type: 'null'
        unit_code:
          anyOf:
            - type: string
            - type: 'null'
        kind:
          type: string
          enum:
            - asking
            - sold
            - rent
            - lease_rate
            - starting_bid
            - deposit
            - fee
            - estimate
            - unknown
        period:
          anyOf:
            - type: string
              enum:
                - night
                - week
                - month
                - year
                - one_time
            - type: 'null'
        per_area_unit:
          anyOf:
            - type: string
            - type: 'null'
        display_text:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - amount
        - currency
        - kind
      additionalProperties: false
    PropertyGroup:
      type: object
      properties:
        property_id:
          anyOf:
            - type: string
            - type: 'null'
        listing_ids:
          type: array
          items:
            type: string
        match_method:
          type: string
        confidence:
          anyOf:
            - type: number
            - type: 'null'
        status:
          type: string
          enum:
            - matched
            - ambiguous
      required:
        - property_id
        - listing_ids
        - match_method
        - status
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.