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:
Last 30 Days
This Month
Python
JavaScript
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"
# Get current month's leads
START_DATE = $( date -u +"%Y-%m-01T00:00:00Z" )
END_DATE = $( date -u +"%Y-%m-%dT23:59:59Z" )
curl -X GET "https://www.venturu.com/api/partner/v1/offices/12345/leads/count?startDate=${ START_DATE }&endDate=${ END_DATE }" \
-H "Authorization: Bearer YOUR_API_KEY"
import requests
from datetime import datetime, timedelta
import os
# Last 30 days
end_date = datetime.utcnow()
start_date = end_date - timedelta( days = 30 )
url = "https://www.venturu.com/api/partner/v1/offices/12345/leads/count"
params = {
"startDate" : start_date.isoformat() + "Z" ,
"endDate" : end_date.isoformat() + "Z"
}
response = requests.get(
url,
params = params,
headers = { "Authorization" : f "Bearer { os.getenv( 'VENTURU_API_KEY' ) } " }
)
print (response.json())
const endDate = new Date ();
const startDate = new Date ();
startDate . setDate ( startDate . getDate () - 30 );
const params = new URLSearchParams ({
startDate: startDate . toISOString (),
endDate: endDate . toISOString ()
});
const response = await fetch (
`https://www.venturu.com/api/partner/v1/offices/12345/leads/count? ${ params } ` ,
{
headers: {
'Authorization' : `Bearer ${ process . env . VENTURU_API_KEY } `
}
}
);
const data = await response . json ();
console . log ( data );
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
Last Quarter
Python - Monthly Report
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"
import requests
from datetime import datetime
from calendar import monthrange
import os
def get_monthly_leads ( org_id , year , month ):
# Calculate first and last day of month
first_day = datetime(year, month, 1 )
last_day_num = monthrange(year, month)[ 1 ]
last_day = datetime(year, month, last_day_num, 23 , 59 , 59 )
url = f "https://www.venturu.com/api/partner/v1/organizations/ { org_id } /leads/count"
params = {
"startDate" : first_day.isoformat() + "Z" ,
"endDate" : last_day.isoformat() + "Z"
}
response = requests.get(
url,
params = params,
headers = { "Authorization" : f "Bearer { os.getenv( 'VENTURU_API_KEY' ) } " }
)
return response.json()
# Get October 2024 leads
leads = get_monthly_leads( 789 , 2024 , 10 )
print ( f "Total leads in October: { leads[ 'totalLeads' ] } " )
Query Parameters
Both endpoints support the same optional query parameters:
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)
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)
All dates must be in ISO 8601 format :
2024-10-01T00:00:00Z ← Start of October 1, 2024 (UTC)
2024-10-31T23:59:59Z ← End of October 31, 2024 (UTC)
2024-01-15T12:30:00Z ← January 15, 2024 at 12:30 PM (UTC)
Pro Tip: Always use UTC timezone (ending with Z) to avoid timezone confusion across different systems.
Common Use Cases
# 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" )
// 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
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
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
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
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 ( " \n Office 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