Skip to main content
GET
/
v1
/
signals
/
permit
/
leads
Get permit-scoped lead rows for a geo ID
curl --request GET \
  --url https://api.homelogs.io/v1/signals/permit/leads \
  --header 'X-API-Key: <api-key>'
{
  "geo_id": "<string>",
  "geo_type": "jurisdiction",
  "scope": "permit",
  "signal_keys": [
    "<string>"
  ],
  "max_freshness_days": 1825,
  "count": 1,
  "next_cursor": "<string>",
  "group_by": "none",
  "leads": [
    {
      "lead_id": "<string>",
      "signal_key": "<string>",
      "event_date_used": "2023-12-25",
      "signal_basis": "<string>",
      "confidence": 123,
      "reason_codes": [
        "<string>"
      ],
      "freshness_lag_days": 1,
      "permit_number": "<string>",
      "jurisdiction": "<string>",
      "location": {
        "full_address": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zipcode": "<string>",
        "county": "<string>",
        "city_norm": "<string>",
        "zipcode_norm": "<string>",
        "county_norm": "<string>"
      },
      "maps_url": "<string>"
    }
  ],
  "groups": [
    {
      "key": "<string>",
      "count": 1,
      "leads": [
        {
          "lead_id": "<string>",
          "signal_key": "<string>",
          "event_date_used": "2023-12-25",
          "signal_basis": "<string>",
          "confidence": 123,
          "reason_codes": [
            "<string>"
          ],
          "freshness_lag_days": 1,
          "permit_number": "<string>",
          "jurisdiction": "<string>",
          "location": {
            "full_address": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zipcode": "<string>",
            "county": "<string>",
            "city_norm": "<string>",
            "zipcode_norm": "<string>",
            "county_norm": "<string>"
          },
          "maps_url": "<string>"
        }
      ]
    }
  ]
}
Use this endpoint to fetch permit-scoped lead rows for a non-property geo_id. It returns the current page of leads, trust fields (event_date_used, signal_basis, confidence, reason_codes), freshness metadata, and the cursor for the next page. Use include_stale=true if you need rows older than the default freshness window. Supported permit-pack keys are documented in Signals Catalog. See also Permit Signal Stats.

​
Required input

  • geo_id (query, required, non-property geo)

​
Optional input

  • signal_keys (CSV list)
  • from_date, to_date (YYYY-MM-DD)
  • min_confidence (0..1)
  • max_freshness_days (1..3650)
  • include_stale (true|false)
  • sort (event_date_desc or confidence_desc)
  • group_by (none, city, zip)
  • limit (1..100)
  • cursor (opaque pagination token)

​
Example request

curl -sS "$API_BASE_URL/v1/signals/permit/leads?geo_id=geo_county_6973f63e37a900040c0d&signal_keys=site_prep_issued_nowcast,new_construction_issued_nowcast&sort=event_date_desc&group_by=none&limit=25" \
  -H "x-api-key: $HOMELOGS_API_KEY"

​
Response shape

  • geo_id, geo_type, scope=permit
  • signal_keys[]
  • max_freshness_days
  • count
  • next_cursor
  • leads[] (or groups[] when grouped)

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
geo_id
string
required

Location identity token for a non-property geo scope.

Example:

"geo_county_6973f63e37a900040c0d"

​
signal_keys
string

Optional CSV list of customer-facing permit signal keys. Allowed values: site_prep_issued_nowcast, new_construction_issued_nowcast, framing_nowcast_early, framing_window_late, rough_in_nowcast_early, rough_in_window_late.

Example:

"site_prep_issued_nowcast,new_construction_issued_nowcast"

​
from_date
string<date>

Optional lower bound in YYYY-MM-DD format.

​
to_date
string<date>

Optional upper bound in YYYY-MM-DD format.

​
min_confidence
number

Optional minimum confidence between 0 and 1.

Required range: 0 <= x <= 1
​
max_freshness_days
integer
default:60

Optional freshness window in days, between 1 and 3650. Defaults to 60 when include_stale is false.

Required range: 1 <= x <= 3650
​
include_stale
boolean
default:false

When true, disables the default freshness filter.

​
sort
enum<string>
default:event_date_desc

Cursor sort order for the returned page.

Available options:
event_date_desc,
confidence_desc
​
group_by
enum<string>
default:none

Optional grouping for the returned page.

Available options:
none,
city,
zip
​
limit
integer
default:25

Maximum rows to return.

Required range: 1 <= x <= 100
​
cursor
string

Opaque cursor from the previous page.

Response

Permit-scoped lead rows and pagination metadata.

​
geo_id
string
required
​
geo_type
enum<string> | null
required
Available options:
jurisdiction,
city,
zip,
county,
state,
null
​
scope
enum<string>
required
Available options:
permit
​
signal_keys
string[]
required
​
max_freshness_days
integer | null
required
Required range: 1 <= x <= 3650
​
count
integer
required
Required range: x >= 0
​
next_cursor
string | null
required
​
group_by
enum<string>
Available options:
none,
city,
zip
​
leads
object[]
​
groups
object[]