Leads API

Quick start

1. Ask your account contact for an API key.
2. Call GET /api/v1/leads with that key and a days value.
3. Read the leads array in the JSON response.

export CUSTOMER_API_KEY='rl_live_<secret>'

curl \
  --fail-with-body \
  --header "Authorization: Bearer $CUSTOMER_API_KEY" \
  "https://dashboard.refinedleads.ai/api/v1/leads?days=7"

What you get

Each response is the set of properties that were included in your successful daily emails over the last days calendar days (in your account timezone), including today.

• Same leads as those emails — one row per property, no duplicates.
• Properties found after the last send are not included until they go out in a later email.
• There is no pagination. Prefer a smaller days value, or add a furniture filter, if the payload gets large.

Authentication

Send the API key as a bearer token:

Authorization: Bearer rl_live_<secret>

Invalid or revoked keys return:

{ "error": "Unauthorized" }

Parameters

days (required) — integer from 1 through 30. How many recent calendar days to include, counting today.

furniture (optional) — narrow the set:

• furnished — occupied / furnished homes
• unfurnished — vacant / unfurnished homes
• staged — professionally staged homes
• unknown — furniture status could not be determined

Omit furniture to receive every emailed lead in the window. Example with a filter:

curl \
  --fail-with-body \
  --header "Authorization: Bearer $CUSTOMER_API_KEY" \
  "https://dashboard.refinedleads.ai/api/v1/leads?days=3&furniture=furnished"

The response also returns windowStart and windowEndExclusive as UTC timestamps for the exact window used.

Response

{
  "days": 1,
  "furniture": null,
  "timezone": "America/Chicago",
  "windowStart": "2026-05-14T05:00:00.000Z",
  "windowEndExclusive": "2026-05-15T05:00:00.000Z",
  "count": 1,
  "leads": [
    {
      "address": "100 Main St",
      "city": "Chicago",
      "state": "IL",
      "zip_code": "60601",
      "full_address": "100 Main St, Chicago, IL 60601",
      "price": 500000,
      "beds": 3,
      "sqft": 1800,
      "listing_status": "ACTIVE",
      "occupancy_classification": "VACANT",
      "staging_classification": null,
      "realtor_name": "Jane Agent",
      "realtor_phone": "555-0100",
      "realtor_email": "jane@example.com",
      "broker_name": "Example Realty",
      "broker_phone": "555-0200",
      "broker_email": "broker@example.com",
      "owner_name": null,
      "owner_phone": null,
      "owner_email": null,
      "current_resident": null,
      "homestead_status": null
    }
  ]
}

• count and leads — the result set
• furniture — the filter you sent, or null if none
• Each lead includes address, price, beds, sqft, listing status, furniture/staging signals, and realtor, broker, and owner contacts when available

Owner contact fields may be null depending on your account settings. If nothing matched, you still get HTTP 200 with count: 0 and an empty leads array.

Errors

• Bad days or furniture → HTTP 400
• Missing or invalid API key → HTTP 401
• Unexpected server error → HTTP 500

Getting a key

Keys are issued by your account contact and shared once. Questions: support@refinedleads.ai.