•

Connect a Property Data API for Solar Lead Lists

BatchData author avatar

Author

BatchData

BatchData’s Property Search API can build a solar prospect list - not a list of solar-qualified leads. Start with location and property filters, such as owner-occupied homes with at least 1,500 square feet and 30% estimated equity.

This guide covers connecting with a server-side API token, checking available fields, retrieving all result pages, and mapping records for CSV or CRM export. It also covers duplicate checks, data validation, and a small pilot before scaling.

Roof suitability and permission to contact require separate checks. Property records alone do not confirm shading, roof condition, electricity use, or existing solar equipment.

Property Data API to Solar Prospect List: Workflow

Connect to the BatchData Property Search API

Start by retrieving property records you can filter into prospect lists. Send requests from your server using a BatchData account with Property Search access. Check the developer docs for enabled datasets, accepted filters, response fields, and usage limits. The attributes you receive depend on your subscription.

Set Up Your API Token and Headers

Once you've confirmed the current fields, send your first authenticated request. Use https://api.batchdata.com and POST /api/v1/property/search with Content-Type: application/json and Authorization: Bearer <token>. Store the token on your server, keep test and production credentials separate, and rotate compromised tokens immediately.

Handle credential failures separately from authorization, JSON, and field-validation errors. Return a safe error message in your app. Log only the timestamp, endpoint, HTTP status, correlation ID, and sanitized error details - never the authorization header.

Send a Filtered Search and Check the Response

The location query sets your market, while structured criteria narrow the list. The request below searches for owner-occupied single-family properties in Phoenix. If your account supports it, searchCriteria.quickLists adds predefined segments. Check whether multiple flags use AND or OR logic.

Use this server-side example as a starting point. Before running it, check field names and accepted values against your account documentation.

Illustrative server-side request: ${BATCHDATA_TOKEN} references your secret environment variable.

curl --request POST \
  "https://api.batchdata.com/api/v1/property/search" \
  --header "Authorization: Bearer ${BATCHDATA_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "searchCriteria": {
      "query": "Phoenix, AZ",
      "general": {
        "propertyTypeDetail": {"equals": "Single Family"}
      },
      "ownership": {
        "ownerOccupied": true
      }
    },
    "options": {
      "take": 25,
      "skip": 0
    }
  }'

Fictional, shortened response - not actual properties or a real match count.

{
  "results": {
    "properties": [
      {
        "id": "property_12345",
        "address": {
          "city": "Phoenix",
          "state": "AZ",
          "zip": "85004"
        },
        "propertyType": "Single Family",
        "owner": {
          "fullName": "Sample Owner"
        }
      }
    ],
    "meta": {
      "results": {
        "resultsFound": 1840
      }
    }
  }
}

Check the HTTP status, verify that results.properties is an array, and read results.meta.results.resultsFound. Before accepting records, require a stable property identifier and inspect the requested property and ownership fields. Zero matches does not mean authentication failed.

Retrieve All Matching Properties

Set the page size with options.take and the offset with options.skip. For 25 records per page, request offsets 0, 25, and 50. Check the current documentation for the maximum take value and available metadata. For count-only requests, use only the documented form.

Review your account terms for billing rules, request-per-minute or concurrency limits, timeout behavior, and retryable errors. Apply bounded exponential backoff only to documented transient failures - not authentication or validation errors.

Track page state and distinct property IDs so you collect each matching property once before mapping. Save the search definition, API version or documentation date, retrieval time in ISO 8601 format, page or cursor state, record count, and property IDs. These details let you resume interrupted downloads without duplicates. Once you've collected every page, map the returned fields into lead columns.

Turn Property Results Into Lead Records

Once you’ve retrieved all matching properties, turn each property record into one lead row.

Map API Fields to Lead Columns

Keep raw API fields, derived fields, and qualification flags separate. Build each lead record from the property IDs and raw payloads saved during retrieval. Preserve the original payload and document each field’s exact JSON path. BatchData’s example response uses nested objects such as address, building, valuation, and owner.

Property attribute Response path or mapping rule Lead column
Property address Map the returned address object to normalized address fields, and keep the raw address. property_address
Property type propertyType property_type
Owner occupancy ownerOccupied owner_occupied
Living area building.livingAreaSquareFeet living_area_sq_ft
Lot size Store the raw lot size and unit separately. Convert only in a derived field. lot_size_raw, lot_size_unit; derived lot_size_sq_ft or lot_size_acres
Year built building.yearBuilt year_built
Estimated value valuation.estimatedValue estimated_value_usd
Equity percentage valuation.equityPercent equity_percent

Use the stable source property ID to remove duplicates. Keep parcelId or APN with county context when available, and check normalized street, city, state, and ZIP as a second safeguard. Also save owner.fullName, mailing address, and last sale date when returned.

Mailing address and property address are different fields. Store missing numeric values as null and display them as “unavailable,” not zero. Check units before converting lot size, and document whether percentages use a 0–100 or 0–1 scale.

Show a Sample Property Lead

Here’s how those mapping rules translate into a lead record.

Hypothetical mapping example - not a real property or API response. Numeric values remain unformatted for processing; display 2400 as “2,400 sq ft” and 485000 as “$485,000.”

{
  "source_property_id": "bd_demo_0001842",
  "parcel_id": "DEMO-MARICOPA-1842",
  "property_address": "1842 W Desert Willow Drive, Phoenix, AZ 85027",
  "property_type": "Single-family residence",
  "owner_occupied": true,
  "living_area_sq_ft": 2400,
  "lot_size_sq_ft": 7500,
  "year_built": 2008,
  "estimated_value_usd": 485000,
  "equity_percent": 72.5,
  "last_sale_date": "2021-03-14",
  "phone": "unavailable",
  "email": "unavailable",
  "roof_suitability": "unverified",
  "solar_installed": "unverified",
  "lead_status": "Meets property filters; roof review pending"
}

Living area is not roof area.

Handle Contact Enrichment Separately

If outreach requires accurate skip tracing for phone numbers or email addresses, save enriched values in fields such as contact_phone, contact_email, contact_match_status, contact_source, and contact_checked_at. Contact enrichment may also be available through Property Search or Property Lookup if the API token includes the relevant contact dataset.

Contact availability is not permission to contact. Track contact_available, consent_status, consent_source, dnc_checked_at, internal_dnc_status, and outreach_eligibility separately. A returned phone number means only that a possible contact exists.

Neither enrichment nor property matching confirms roof condition, shading, utility usage, or installed solar equipment. Check those separately before marking the record as solar-ready.

After enrichment, clean the lead fields and export them to CSV or your CRM.

Validate and Export Leads to CSV or a CRM

Once you’ve mapped the lead rows, validate them before export.

Clean and Check Lead Records

Check the mapped columns. Each row must have a usable street address, city, state, ZIP, property ID, and retrieval timestamp. Set aside incomplete or malformed rows rather than silently fixing them. This keeps the property prospect list usable for solar outreach.

Deduplicate by source_property_id, and document which record survives. Log duplicate IDs, missing-field counts, API error objects, and rejected records. For source traceability, require each row to include its retrieval timestamp plus search filters or a saved-query identifier.

Before export, reconcile stored rows against the API total when available. Keep unresolved pages out of the final file.

Once the rows pass validation, format them for CSV or CRM import.

Export a CSV or Map CRM Fields

For CSV delivery, use UTF-8 encoding, stable lowercase or snake_case headers, and one row per property. Include the source property ID, source system, retrieval and export timestamps, search filters or saved-query identifier, and schema version.

Quote cells that contain commas or line breaks. Use one documented convention for missing values, and preserve ZIP columns as text. Then open the CSV in the destination tool to check headers, row counts, and ZIP text formatting.

For CRM delivery, map property, ownership, and source columns to specific destination fields. Use a dedicated external-ID field for source_property_id and explicit column mappings so updates can follow the same process each time. Link properties to owners or contacts through identifiers or explicit association keys - not names alone.

Keep contact enrichment, consent evidence, lead scores, roof-review status, and outreach disposition in separate fields. Source refreshes should not overwrite human-reviewed fields or treat missing consent as approval. Reconcile exported rows against CRM records created, updated, and rejected.

Test Your Property Prospect List Before Scaling

Before exporting to CSV or loading CRM records at scale, run a small, end-to-end pilot in one ZIP code. Check the list’s filters, retrieval, mapping, validation, and import. Scale only when the pilot has no filter errors, duplicates, missing required fields, or import mismatches. Repeat the pilot whenever you change filters, mappings, credentials, or import logic.

Review a sample from each filter group against county assessor records, including boundary values like exactly 2,000 square feet.

Flag discrepancies. Don’t assume the filter worked as intended.

A property match isn’t a solar-qualified lead or permission to contact someone. Leave roof suitability marked as unassessed until a separate review, and complete contact and suppression checks before outreach. Treat each record as a prospect until both roof and contact checks are complete.

FAQs

How often should I refresh my solar prospect list?

Balance accuracy with API credit use by updating phone numbers and emails weekly to limit bounces. Update property values, ownership details, and tax assessments monthly to track market shifts. Refresh the full database every 90 days to keep accuracy above 90%.

Adjust this schedule to fit your business needs. Use scheduled jobs or CRM workflows to find and enrich records that haven’t been updated in more than 90 days.

How can I prioritize prospects for roof reviews?

Narrow your property search by roof cover, roof type, living area, and year built to match installation requirements. Then exclude homes with solar or battery permits on file.

Map these details in your CRM alongside estimated equity and valuation data to automatically score and route high-potential leads. Use contact reachability scores to focus outreach on verified, valid phone numbers and email addresses.

How can I estimate API costs before scaling?

Run your exact filters in the Property Search API, then use the match count to estimate how many records to pull. Enrich only those records to avoid wasted calls.

Start testing in a sandbox, then try batches of 5,000 and 10,000 records. Track usage in the BatchData dashboard and adjust queries that often return no results. Before scaling up, measure time saved and cost per qualified lead.

BatchData author avatar

Author

BatchData

suggested content

Home Under Water: Causes, Risks, and What to Do Next

Home Under Water: Causes, Risks, and What to Do Next