Tracking Leads

Monitor Lead Performance

Note: Lead tracking endpoints are only available for certain partners with organization-level access. Contact joel@venturu.com to enable this feature.

Track how many leads your organization and offices are receiving from Venturu. Perfect for monitoring performance and ROI.

Two Levels of Tracking

Office Level

Get lead counts for a specific office

Organization Level

Get totals across all offices with breakdowns

Office Level Leads

Get the total number of leads for a specific office, optionally filtered by date range. Endpoint: GET /partner/v1/offices/{officeId}/leads/count

Basic Request

Get all leads for an office

curl -X GET "https://www.venturu.com/api/partner/v1/offices/12345/leads/count" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "success",
  "officeId": 12345,
  "officeName": "Downtown Miami Office",
  "totalLeads": 247
}

Filter by Date Range

Add query parameters to filter leads within a specific time period:

curl -X GET "https://www.venturu.com/api/partner/v1/offices/12345/leads/count?startDate=2024-10-01T00:00:00Z&endDate=2024-10-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Organization Level Leads

Get lead counts across your entire organization, with optional breakdown by office. Endpoint: GET /partner/v1/organizations/{organizationId}/leads/count

Basic Request

Get all organizational leads

curl -X GET "https://www.venturu.com/api/partner/v1/organizations/789/leads/count" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "success",
  "organizationId": 789,
  "organizationName": "ABC Realty Group",
  "totalLeads": 1523,
  "officeBreakdown": [
    {
      "officeId": 12345,
      "officeName": "Downtown Miami Office",
      "totalLeads": 247
    },
    {
      "officeId": 12346,
      "officeName": "Boca Raton Office",
      "totalLeads": 189
    },
    {
      "officeId": 12347,
      "officeName": "Fort Lauderdale Office",
      "totalLeads": 312
    }
  ]
}

Filter by Date Range

curl -X GET "https://www.venturu.com/api/partner/v1/organizations/789/leads/count?startDate=2024-07-01T00:00:00Z&endDate=2024-09-30T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Both endpoints support the same optional query parameters:

startDate

string

Start date for filtering leads (ISO 8601 format: 2024-10-01T00:00:00Z)

If not provided, returns all leads from the beginning
Must be a valid ISO 8601 datetime string
Timezone aware (use UTC for consistency)

endDate

string

End date for filtering leads (ISO 8601 format: 2024-10-31T23:59:59Z)

If not provided, defaults to current date/time
Must be a valid ISO 8601 datetime string
Timezone aware (use UTC for consistency)

Date Format

All dates must be in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Pro Tip: Always use UTC timezone (ending with Z) to avoid timezone confusion across different systems.

Common Use Cases

Monthly Performance Report

# Get leads for each month of the quarter
import requests
from datetime import datetime
import os

def get_leads_for_month(org_id, year, month):
    # Calculate month boundaries
    if month == 12:
        next_month = datetime(year + 1, 1, 1)
    else:
        next_month = datetime(year, month + 1, 1)
    
    start = datetime(year, month, 1)
    end = next_month - timedelta(seconds=1)
    
    params = {
        "startDate": start.isoformat() + "Z",
        "endDate": end.isoformat() + "Z"
    }
    
    response = requests.get(
        f"https://www.venturu.com/api/partner/v1/organizations/{org_id}/leads/count",
        params=params,
        headers={"Authorization": f"Bearer {os.getenv('VENTURU_API_KEY')}"}
    )
    
    return response.json()

# Q4 2024 Report
q4_months = [10, 11, 12]
for month in q4_months:
    data = get_leads_for_month(789, 2024, month)
    print(f"Month {month}: {data['totalLeads']} leads")

Compare Office Performance

// Get and compare multiple offices
async function compareOffices(officeIds, startDate, endDate) {
  const params = new URLSearchParams({
    startDate: startDate.toISOString(),
    endDate: endDate.toISOString()
  });

  const results = await Promise.all(
    officeIds.map(async (officeId) => {
      const response = await fetch(
        `https://www.venturu.com/api/partner/v1/offices/${officeId}/leads/count?${params}`,
        {
          headers: {
            'Authorization': `Bearer ${process.env.VENTURU_API_KEY}`
          }
        }
      );
      return response.json();
    })
  );

  // Sort by performance
  results.sort((a, b) => b.totalLeads - a.totalLeads);
  
  console.log('Top Performing Offices:');
  results.forEach((office, index) => {
    console.log(`${index + 1}. ${office.officeName}: ${office.totalLeads} leads`);
  });
}

// Compare last 30 days
const end = new Date();
const start = new Date();
start.setDate(start.getDate() - 30);

compareOffices([12345, 12346, 12347], start, end);

Year-to-Date Tracking

# Get all leads from January 1 to now
START_OF_YEAR=$(date -u +"%Y-01-01T00:00:00Z")
NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

curl -X GET "https://www.venturu.com/api/partner/v1/organizations/789/leads/count?startDate=${START_OF_YEAR}&endDate=${NOW}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

400 Bad Request

Invalid query parameters or date format.

{
  "status": "error",
  "error": "Invalid query parameters. Dates must be in ISO 8601 format."
}

Solutions:

Check date format is ISO 8601: YYYY-MM-DDTHH:MM:SSZ
Ensure dates include timezone (use Z for UTC)
Verify startDate is before endDate

401 Unauthorized

Missing or invalid API key, or insufficient permissions.

{
  "status": "error",
  "error": "Unauthorized"
}

Solutions:

Verify your API key is correct
Check that your key has lead tracking permissions
Contact joel@venturu.com to enable this feature

404 Not Found

Office or organization doesn’t exist or you don’t have access.

{
  "status": "error",
  "error": "Office not found"
}

Solutions:

Verify the office/organization ID is correct
Check that the office belongs to your organization
Ensure you’re using the Venturu ID, not your external ID

Best Practices

Use UTC Timezone

Always use UTC (Z suffix) for consistent cross-system reporting.

Cache Results

Lead counts don’t change retroactively. Cache historical data.

Batch Requests

Use organization endpoint instead of multiple office calls.

Regular Intervals

Pull data on a schedule (daily/weekly) for trend analysis.

Common Questions

What counts as a lead?

A lead is created when a buyer expresses interest in a listing through:

Direct contact form submission
Phone inquiries (if tracked)
Email inquiries to the broker

Can I get individual lead details?

Currently, the API only provides lead counts and statistics. Individual lead details (names, emails, messages) are not available through the API for privacy reasons.

How often is data updated?

Lead counts update in real-time. When you query the API, you get the current count for your specified date range.

What if I don't have an organizationId?

Contact joel@venturu.com. The organization ID is provided during partnership setup for partners with this feature enabled.

Can I get leads for all my offices at once?

Yes! Use the organization endpoint - it returns total leads plus a breakdown by each office automatically.

Integration Example

Here’s a complete example building a simple lead dashboard:

Complete Dashboard Example

import requests
from datetime import datetime, timedelta
import os

API_KEY = os.getenv('VENTURU_API_KEY')
BASE_URL = "https://www.venturu.com/api/partner/v1"
ORG_ID = 789

def get_leads_by_period(org_id, start_date, end_date):
    """Get leads for a specific date range."""
    params = {
        "startDate": start_date.isoformat() + "Z",
        "endDate": end_date.isoformat() + "Z"
    }
    
    response = requests.get(
        f"{BASE_URL}/organizations/{org_id}/leads/count",
        params=params,
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    
    return response.json()

# Generate monthly report for Q4 2024
months = [
    ("October", datetime(2024, 10, 1), datetime(2024, 10, 31, 23, 59, 59)),
    ("November", datetime(2024, 11, 1), datetime(2024, 11, 30, 23, 59, 59)),
    ("December", datetime(2024, 12, 1), datetime(2024, 12, 31, 23, 59, 59)),
]

print("=== Q4 2024 Lead Report ===\n")

for month_name, start, end in months:
    data = get_leads_by_period(ORG_ID, start, end)
    
    print(f"{month_name} {start.year}")
    print(f"Total Leads: {data['totalLeads']}")
    print("\nOffice Breakdown:")
    
    for office in data['officeBreakdown']:
        print(f"  - {office['officeName']}: {office['totalLeads']} leads")
    
    print("\n" + "-" * 50 + "\n")

Next Steps

Create a Broker

Set up brokers to receive leads

Create a Listing

Create listings to generate leads

API Reference

Full API documentation

Contact Support

Enable lead tracking

Introduction

Getting Started

Guides

Monitor Lead Performance

Two Levels of Tracking

Office Level

Organization Level

Office Level Leads

Basic Request

Response

Filter by Date Range

Organization Level Leads

Basic Request

Response

Filter by Date Range

Query Parameters

Date Format

Common Use Cases

Monthly Performance Report

Compare Office Performance

Year-to-Date Tracking

Error Handling

Best Practices

Use UTC Timezone

Cache Results

Batch Requests

Regular Intervals

Common Questions

Integration Example

Next Steps

Create a Broker

Create a Listing

API Reference

Contact Support

Introduction

Getting Started

Guides

​Monitor Lead Performance

​Two Levels of Tracking

Office Level

Organization Level

​Office Level Leads

​Basic Request

​Response

​Filter by Date Range

​Organization Level Leads

​Basic Request

​Response

​Filter by Date Range

​Query Parameters

​Date Format

​Common Use Cases

​Monthly Performance Report

​Compare Office Performance

​Year-to-Date Tracking

​Error Handling

​Best Practices

Use UTC Timezone

Cache Results

Batch Requests

Regular Intervals

​Common Questions

​Integration Example

​Next Steps

Create a Broker

Create a Listing

API Reference

Contact Support

Monitor Lead Performance

Two Levels of Tracking

Office Level Leads

Basic Request

Response

Filter by Date Range

Organization Level Leads

Basic Request

Response

Filter by Date Range

Query Parameters

Date Format

Common Use Cases

Monthly Performance Report

Compare Office Performance

Year-to-Date Tracking

Error Handling

Best Practices

Common Questions

Integration Example

Next Steps