Property Object
Property Properties
{
"id": "property_123e4567-e89b-12d3-a456-426614174000",
"organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
"mlsId": "MLS12345678",
"address": {
"street": "123 Ocean Drive",
"unit": "Apt 2B",
"city": "Miami Beach",
"state": "FL",
"zipCode": "33139",
"county": "Miami-Dade",
"country": "US",
"coordinates": {
"latitude": 25.7617,
"longitude": -80.1918
}
},
"details": {
"propertyType": "CONDO",
"propertySubType": "HIGH_RISE",
"bedrooms": 2,
"bathrooms": 2.5,
"halfBaths": 1,
"squareFootage": 1200,
"lotSize": null,
"yearBuilt": 2018,
"stories": 1,
"garage": true,
"parking": {
"spaces": 2,
"type": "COVERED"
},
"pool": true,
"waterfront": true,
"view": "OCEAN"
},
"listing": {
"status": "ACTIVE",
"listPrice": 750000,
"originalPrice": 795000,
"priceHistory": [
{
"price": 795000,
"date": "2024-01-01T00:00:00Z",
"event": "LISTED"
},
{
"price": 750000,
"date": "2024-01-15T00:00:00Z",
"event": "PRICE_REDUCTION"
}
],
"listDate": "2024-01-01T00:00:00Z",
"daysOnMarket": 45,
"listingAgent": {
"id": "agent_123",
"name": "Sarah Johnson",
"email": "sarah@premierrealty.com",
"phone": "+1-555-123-4567"
},
"coListingAgent": {
"id": "agent_456",
"name": "Mike Rodriguez",
"email": "mike@premierrealty.com"
},
"commission": {
"buyerAgent": 0.025,
"listingAgent": 0.025,
"total": 0.05
}
},
"features": {
"interior": [
"Hardwood floors",
"Granite countertops",
"Stainless steel appliances",
"Walk-in closet",
"Balcony"
],
"exterior": [
"Private beach access",
"Concierge service",
"Fitness center",
"Rooftop pool"
],
"appliances": [
"Dishwasher",
"Refrigerator",
"Washer/Dryer",
"Microwave"
]
},
"media": {
"photos": [
{
"url": "https://storage.winnerr.com/properties/prop_123/photo_1.jpg",
"caption": "Living room with ocean view",
"order": 1
}
],
"virtualTour": "https://tours.winnerr.com/property_123",
"videos": [
{
"url": "https://storage.winnerr.com/properties/prop_123/tour.mp4",
"type": "WALKTHROUGH"
}
]
},
"valuation": {
"estimatedValue": 725000,
"confidence": 0.85,
"valuationDate": "2024-01-15T00:00:00Z",
"pricePerSquareFoot": 625,
"comparables": [
{
"address": "125 Ocean Drive",
"soldPrice": 720000,
"soldDate": "2023-12-15T00:00:00Z",
"squareFootage": 1150
}
]
},
"marketing": {
"description": "Stunning oceanfront condo with panoramic views...",
"keywordTags": ["luxury", "waterfront", "condo", "ocean-view"],
"showingInstructions": "Call listing agent for appointments",
"virtualShowings": true,
"openHouses": [
{
"date": "2024-01-20T14:00:00Z",
"endTime": "2024-01-20T16:00:00Z",
"type": "PUBLIC"
}
]
},
"analytics": {
"views": 1250,
"inquiries": 45,
"showings": 18,
"offers": 3,
"saveCount": 89,
"averageTimeOnSite": 180
},
"hoa": {
"monthlyFee": 450,
"includes": ["Water", "Sewer", "Building maintenance", "Concierge"],
"restrictions": ["No pets over 25lbs", "No short-term rentals"]
},
"taxes": {
"annualAmount": 12500,
"taxYear": 2023,
"exemptions": ["Homestead"]
},
"disclosure": {
"floodZone": "X",
"environmental": [],
"structural": [],
"other": []
},
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": "2024-01-15T14:30:00Z"
}
Property Types
| Type | Description |
|---|---|
SINGLE_FAMILY | Single-family residential home |
CONDO | Condominium unit |
TOWNHOUSE | Townhouse |
MULTI_FAMILY | Multi-family residential |
LAND | Vacant land |
COMMERCIAL | Commercial property |
INDUSTRIAL | Industrial property |
MIXED_USE | Mixed-use property |
Listing Status
| Status | Description |
|---|---|
ACTIVE | Active listing |
PENDING | Under contract |
SOLD | Sold |
EXPIRED | Listing expired |
WITHDRAWN | Withdrawn from market |
CANCELLED | Listing cancelled |
COMING_SOON | Coming soon |
Endpoints
List Properties
Retrieve a paginated list of properties with optional filtering and sorting.curl -X GET "https://api.winnerr.com/v1/properties" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json"
const response = await fetch('https://api.winnerr.com/v1/properties', {
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.winnerr.com/v1/properties',
headers={
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
}
)
data = response.json()
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of properties to return (1-100, default: 25) |
cursor | string | Pagination cursor for next page |
propertyType | string | Filter by property type |
status | string | Filter by listing status |
city | string | Filter by city |
state | string | Filter by state |
zipCode | string | Filter by ZIP code |
bedrooms[gte] | integer | Filter by minimum bedrooms |
bathrooms[gte] | number | Filter by minimum bathrooms |
squareFootage[gte] | integer | Filter by minimum square footage |
listPrice[gte] | number | Filter by minimum list price |
listPrice[lte] | number | Filter by maximum list price |
daysOnMarket[lte] | integer | Filter by maximum days on market |
waterfront | boolean | Filter by waterfront properties |
pool | boolean | Filter by properties with pool |
garage | boolean | Filter by properties with garage |
bounds | string | Filter by geographic bounds (lat1,lng1,lat2,lng2) |
radius | string | Filter by radius from point (lat,lng,miles) |
sort | string | Sort order (e.g., “listPrice:desc,daysOnMarket:asc”) |
include | string | Include related data (e.g., “agent,photos,analytics”) |
{
"success": true,
"data": [
{
"id": "property_123",
"mlsId": "MLS12345678",
"address": {
"street": "123 Ocean Drive",
"city": "Miami Beach",
"state": "FL",
"zipCode": "33139"
},
"details": {
"propertyType": "CONDO",
"bedrooms": 2,
"bathrooms": 2.5,
"squareFootage": 1200
},
"listing": {
"status": "ACTIVE",
"listPrice": 750000,
"daysOnMarket": 45
}
}
],
"pagination": {
"hasMore": true,
"nextCursor": "eyJpZCI6IjEyNCJ9",
"total": 342,
"limit": 25
}
}
Get Property
Retrieve a specific property by ID.curl -X GET "https://api.winnerr.com/v1/properties/property_123" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://api.winnerr.com/v1/properties/property_123', {
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
const property = await response.json();
| Parameter | Type | Description |
|---|---|---|
id | string | Property ID |
| Parameter | Type | Description |
|---|---|---|
include | string | Include related data (e.g., “photos,agent,analytics,comparables”) |
{
"success": true,
"data": {
"id": "property_123",
"mlsId": "MLS12345678",
"address": {
"street": "123 Ocean Drive",
"city": "Miami Beach",
"state": "FL",
"zipCode": "33139"
},
"details": {
"propertyType": "CONDO",
"bedrooms": 2,
"bathrooms": 2.5,
"squareFootage": 1200
},
"listing": {
"status": "ACTIVE",
"listPrice": 750000,
"listingAgent": {
"id": "agent_123",
"name": "Sarah Johnson",
"email": "sarah@premierrealty.com"
}
},
"media": {
"photos": [
{
"url": "https://storage.winnerr.com/properties/prop_123/photo_1.jpg",
"caption": "Living room with ocean view"
}
]
}
}
}
Create Property
Create a new property listing.curl -X POST "https://api.winnerr.com/v1/properties" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"address": {
"street": "456 Bay Street",
"city": "Miami",
"state": "FL",
"zipCode": "33131"
},
"details": {
"propertyType": "SINGLE_FAMILY",
"bedrooms": 3,
"bathrooms": 2,
"squareFootage": 1800,
"lotSize": 7200,
"yearBuilt": 1985
},
"listing": {
"listPrice": 550000,
"commission": {
"buyerAgent": 0.03,
"listingAgent": 0.03
}
},
"marketing": {
"description": "Charming single-family home in desirable neighborhood"
}
}'
const response = await fetch('https://api.winnerr.com/v1/properties', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: {
street: '456 Bay Street',
city: 'Miami',
state: 'FL',
zipCode: '33131'
},
details: {
propertyType: 'SINGLE_FAMILY',
bedrooms: 3,
bathrooms: 2,
squareFootage: 1800,
lotSize: 7200,
yearBuilt: 1985
},
listing: {
listPrice: 550000,
commission: {
buyerAgent: 0.03,
listingAgent: 0.03
}
},
marketing: {
description: 'Charming single-family home in desirable neighborhood'
}
})
});
const property = await response.json();
| Field | Type | Required | Description |
|---|---|---|---|
address | object | Yes | Property address |
details | object | Yes | Property details |
listing | object | Yes | Listing information |
features | object | No | Property features |
media | object | No | Property media |
marketing | object | No | Marketing information |
hoa | object | No | HOA information |
taxes | object | No | Tax information |
{
"success": true,
"data": {
"id": "property_456",
"address": {
"street": "456 Bay Street",
"city": "Miami",
"state": "FL",
"zipCode": "33131"
},
"details": {
"propertyType": "SINGLE_FAMILY",
"bedrooms": 3,
"bathrooms": 2,
"squareFootage": 1800
},
"listing": {
"status": "ACTIVE",
"listPrice": 550000,
"listDate": "2024-01-15T16:00:00Z",
"daysOnMarket": 0
},
"createdAt": "2024-01-15T16:00:00Z"
}
}
Update Property
Update an existing property’s information.curl -X PUT "https://api.winnerr.com/v1/properties/property_123" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"listing": {
"listPrice": 725000,
"status": "ACTIVE"
},
"marketing": {
"description": "Updated description with new features"
}
}'
const response = await fetch('https://api.winnerr.com/v1/properties/property_123', {
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
listing: {
listPrice: 725000,
status: 'ACTIVE'
},
marketing: {
description: 'Updated description with new features'
}
})
});
const property = await response.json();
Delete Property
Delete a property listing.curl -X DELETE "https://api.winnerr.com/v1/properties/property_123" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://api.winnerr.com/v1/properties/property_123', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
Property Photos
Upload Property Photos
Upload photos for a property listing.curl -X POST "https://api.winnerr.com/v1/properties/property_123/photos" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-F "photos=@photo1.jpg" \
-F "photos=@photo2.jpg" \
-F "captions=Living room with ocean view" \
-F "captions=Kitchen with granite countertops"
const formData = new FormData();
formData.append('photos', photo1File);
formData.append('photos', photo2File);
formData.append('captions', 'Living room with ocean view');
formData.append('captions', 'Kitchen with granite countertops');
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/photos', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
},
body: formData
});
const photos = await response.json();
{
"success": true,
"data": [
{
"id": "photo_123",
"url": "https://storage.winnerr.com/properties/prop_123/photo_1.jpg",
"caption": "Living room with ocean view",
"order": 1,
"uploadedAt": "2024-01-15T16:00:00Z"
}
]
}
Reorder Property Photos
Update the order of property photos.curl -X PUT "https://api.winnerr.com/v1/properties/property_123/photos/order" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"photoOrder": [
{"id": "photo_456", "order": 1},
{"id": "photo_123", "order": 2}
]
}'
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/photos/order', {
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
photoOrder: [
{ id: 'photo_456', order: 1 },
{ id: 'photo_123', order: 2 }
]
})
});
Property Valuations
Get Property Valuation
Retrieve AI-powered property valuation.curl -X GET "https://api.winnerr.com/v1/properties/property_123/valuation" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/valuation', {
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
const valuation = await response.json();
{
"success": true,
"data": {
"estimatedValue": 725000,
"confidence": 0.85,
"valuationDate": "2024-01-15T00:00:00Z",
"pricePerSquareFoot": 625,
"priceRange": {
"low": 695000,
"high": 755000
},
"factors": {
"location": 0.25,
"size": 0.20,
"condition": 0.18,
"amenities": 0.15,
"market": 0.22
},
"comparables": [
{
"id": "comp_123",
"address": "125 Ocean Drive",
"soldPrice": 720000,
"soldDate": "2023-12-15T00:00:00Z",
"similarity": 0.92
}
],
"marketTrends": {
"appreciation": 0.08,
"averageDaysOnMarket": 32,
"pricePerSquareFoot": 650
}
}
}
Request New Valuation
Request a fresh property valuation.curl -X POST "https://api.winnerr.com/v1/properties/property_123/valuation" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/valuation', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
const valuation = await response.json();
Property Analytics
Get Property Analytics
Retrieve performance analytics for a property.curl -X GET "https://api.winnerr.com/v1/properties/property_123/analytics" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/analytics', {
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
const analytics = await response.json();
{
"success": true,
"data": {
"period": "30d",
"views": 1250,
"uniqueViews": 890,
"inquiries": 45,
"showings": 18,
"offers": 3,
"saveCount": 89,
"shareCount": 12,
"averageTimeOnSite": 180,
"conversionRate": 0.036,
"topReferrers": [
{
"source": "Zillow",
"views": 425,
"percentage": 0.34
},
{
"source": "Realtor.com",
"views": 312,
"percentage": 0.25
}
],
"viewsByDay": [
{
"date": "2024-01-15",
"views": 42
}
]
}
}
Property Search
Advanced Property Search
Perform advanced property searches with multiple criteria.curl -X POST "https://api.winnerr.com/v1/properties/search" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"criteria": {
"propertyType": ["CONDO", "TOWNHOUSE"],
"bedrooms": {"min": 2, "max": 4},
"bathrooms": {"min": 2},
"priceRange": {"min": 400000, "max": 800000},
"squareFootage": {"min": 1000},
"features": ["pool", "waterfront"],
"location": {
"city": "Miami Beach",
"state": "FL"
}
},
"sort": "listPrice:asc",
"limit": 20
}'
const response = await fetch('https://api.winnerr.com/v1/properties/search', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
criteria: {
propertyType: ['CONDO', 'TOWNHOUSE'],
bedrooms: { min: 2, max: 4 },
bathrooms: { min: 2 },
priceRange: { min: 400000, max: 800000 },
squareFootage: { min: 1000 },
features: ['pool', 'waterfront'],
location: {
city: 'Miami Beach',
state: 'FL'
}
},
sort: 'listPrice:asc',
limit: 20
})
});
const results = await response.json();
MLS Integration
Sync with MLS
Synchronize property data with MLS systems.curl -X POST "https://api.winnerr.com/v1/properties/property_123/mls-sync" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/mls-sync', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
const syncResult = await response.json();
{
"success": true,
"data": {
"mlsId": "MLS12345678",
"syncStatus": "COMPLETED",
"syncedAt": "2024-01-15T16:00:00Z",
"changes": [
{
"field": "listPrice",
"oldValue": 750000,
"newValue": 725000
}
]
}
}
Property Reports
Generate Property Report
Generate comprehensive property reports.curl -X POST "https://api.winnerr.com/v1/properties/property_123/reports" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"reportType": "MARKET_ANALYSIS",
"format": "PDF",
"includeComparables": true,
"includeMarketTrends": true
}'
const response = await fetch('https://api.winnerr.com/v1/properties/property_123/reports', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
reportType: 'MARKET_ANALYSIS',
format: 'PDF',
includeComparables: true,
includeMarketTrends: true
})
});
const report = await response.json();
{
"success": true,
"data": {
"reportId": "report_123",
"reportType": "MARKET_ANALYSIS",
"format": "PDF",
"url": "https://storage.winnerr.com/reports/report_123.pdf",
"generatedAt": "2024-01-15T16:00:00Z",
"expiresAt": "2024-02-15T16:00:00Z"
}
}
Webhooks
Property Events
Supported webhook events for properties:property.createdproperty.updatedproperty.status_changedproperty.price_changedproperty.photos_uploadedproperty.inquiry_receivedproperty.showing_scheduledproperty.offer_received
Webhook Payload Example
{
"id": "evt_123456789",
"event": "property.price_changed",
"createdAt": "2024-01-15T14:30:00Z",
"data": {
"id": "property_123",
"mlsId": "MLS12345678",
"address": {
"street": "123 Ocean Drive",
"city": "Miami Beach",
"state": "FL"
},
"previousPrice": 750000,
"newPrice": 725000,
"changeType": "PRICE_REDUCTION",
"changeAmount": -25000,
"changePercentage": -0.033
},
"organization": {
"id": "org_123",
"name": "Premier Realty Group"
}
}
Best Practices
1. Property Data Management
Keep property data updated and accurate:// Update property data regularly
await fetch('https://api.winnerr.com/v1/properties/property_123', {
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
analytics: {
views: updatedViews,
inquiries: updatedInquiries
},
listing: {
daysOnMarket: calculateDaysOnMarket(listDate)
}
})
});
2. Photo Management
Optimize photos for better performance:// Upload photos with proper ordering and captions
const formData = new FormData();
photos.forEach((photo, index) => {
formData.append('photos', photo.file);
formData.append('captions', photo.caption);
formData.append('order', index + 1);
});
await fetch(`https://api.winnerr.com/v1/properties/${propertyId}/photos`, {
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' },
body: formData
});
3. Search Optimization
Use efficient search parameters:// Use specific criteria for better performance
const searchCriteria = {
propertyType: ['CONDO'],
priceRange: { min: 400000, max: 800000 },
location: { city: 'Miami Beach', state: 'FL' },
features: ['waterfront'],
limit: 25
};
const properties = await fetch('https://api.winnerr.com/v1/properties/search', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({ criteria: searchCriteria })
});
4. Performance Monitoring
Track property performance metrics:// Monitor key performance indicators
const analytics = await fetch(`https://api.winnerr.com/v1/properties/${propertyId}/analytics`, {
headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' }
});
if (analytics.data.conversionRate < 0.02) {
// Consider price adjustment or marketing changes
console.log('Low conversion rate - review pricing or marketing');
}
Property data is automatically synchronized with MLS systems and marketing platforms. All property activities are tracked for performance optimization and compliance reporting.