Properties API - Winnerr CRM

The Properties API provides comprehensive property management functionality for real estate professionals, enabling listing management, MLS integration, automated valuations, and property analytics through a robust set of endpoints.

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"

Query Parameters:

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”)

Response:

{
  "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"

Path Parameters:

Parameter	Type	Description
`id`	string	Property ID

Query Parameters:

Parameter	Type	Description
`include`	string	Include related data (e.g., “photos,agent,analytics,comparables”)

Response:

{
  "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"
    }
  }'

Request Body:

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

Response:

{
  "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"
    }
  }'

Delete Property

Delete a property listing.

curl -X DELETE "https://api.winnerr.com/v1/properties/property_123" \
  -H "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"

Response:

{
  "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}
    ]
  }'

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"

Response:

{
  "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"

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"

Response:

{
  "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
  }'

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"

Response:

{
  "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
  }'

Response:

{
  "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.created
property.updated
property.status_changed
property.price_changed
property.photos_uploaded
property.inquiry_received
property.showing_scheduled
property.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.

​Property Object

​Property Properties

​Property Types

​Listing Status

​Endpoints

​List Properties

​Get Property

​Create Property

​Update Property

​Delete Property

​Property Photos

​Upload Property Photos

​Reorder Property Photos

​Property Valuations

​Get Property Valuation

​Request New Valuation

​Property Analytics

​Get Property Analytics

​Property Search

​Advanced Property Search

​MLS Integration

​Sync with MLS

​Property Reports

​Generate Property Report

​Webhooks

​Property Events

​Webhook Payload Example

​Best Practices

​1. Property Data Management

​2. Photo Management

​3. Search Optimization

​4. Performance Monitoring

Property Object

Property Properties

Property Types

Listing Status

Endpoints

List Properties

Get Property

Create Property

Update Property

Delete Property

Property Photos

Upload Property Photos

Reorder Property Photos

Property Valuations

Get Property Valuation

Request New Valuation

Property Analytics

Get Property Analytics

Property Search

Advanced Property Search

MLS Integration

Sync with MLS

Property Reports

Generate Property Report

Webhooks

Property Events

Webhook Payload Example

Best Practices

1. Property Data Management

2. Photo Management

3. Search Optimization

4. Performance Monitoring