External Properties Webhook

Receive property listings from external automation systems

Endpoint

POST /api/webhooks/external-properties

Headers

Header Value Required
Content-Type application/json Yes
x-api-key Your API key Yes
Note: The API key is uZMXc8dFLfrifpEXsvLSjG0IhGxjBYxVyCCxuUjv60

Request Body

Field Type Required Description
claimId string (UUID) Yes The ID of the claim to associate properties with
properties array Yes Array of property objects (minimum 1)

Property Object Fields

Field Type Required Description
externalId string No Unique ID from the source platform
source string No Source platform name (e.g., "zillow")
address string Yes Full street address
city string No City name
state string No State abbreviation
zipCode string No ZIP/postal code
bedrooms integer No Number of bedrooms
bathrooms number No Number of bathrooms
squareFootage integer No Property size in sq ft
price number No Listing price
priceType string No "monthly", "nightly", etc.
listingUrl string (URL) No URL to original listing
photos array No Array of photo URLs
amenities array No Array of amenity names
description string No Property description
availableFrom string (ISO 8601) No Date available
petsAllowed boolean No Whether pets allowed
furnished string No "FULLY", "PARTIALLY", "UNFURNISHED"
contactEmail string (email) No Contact email for listing
contactPhone string No Contact phone number

Response

Success Response 200

{
  "success": true,
  "count": 2,
  "properties": [
    {
      "id": "23caeb23-1ef6-4d5d-945f-ac25e0e5d651",
      "claimId": "2ab41281-12f8-44a9-a9c7-1cbb00b9b3f2",
      "address": "123 Test Street",
      "status": "NEW",
      ...
    }
  ]
}

Error Responses

Validation Error 400

{
  "success": false,
  "error": "Validation failed",
  "details": [...]
}

Unauthorized 401

{
  "success": false,
  "error": "Unauthorized - Invalid or missing API key"
}

Claim Not Found 404

{
  "success": false,
  "error": "Claim not found with ID: ..."
}

Example Usage

cURL

Bash 
curl -X POST https://app.havnly.ai/api/webhooks/external-properties \
  -H "Content-Type: application/json" \
  -H "x-api-key: uZMXc8dFLfrifpEXsvLSjG0IhGxjBYxVyCCxuUjv60" \
  -d '{
    "claimId": "2ab41281-12f8-44a9-a9c7-1cbb00b9b3f2",
    "properties": [
      {
        "externalId": "listing-123",
        "source": "zillow",
        "address": "123 Main Street",
        "city": "Los Angeles",
        "state": "CA",
        "zipCode": "90001",
        "bedrooms": 3,
        "bathrooms": 2,
        "price": 2500,
        "priceType": "monthly",
        "contactEmail": "landlord@example.com",
        "contactPhone": "+1-555-123-4567"
      }
    ]
  }'

JavaScript / Node.js

JavaScript 
const response = await fetch('/api/webhooks/external-properties', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'uZMXc8dFLfrifpEXsvLSjG0IhGxjBYxVyCCxuUjv60',
  },
  body: JSON.stringify({
    claimId: '2ab41281-12f8-44a9-a9c7-1cbb00b9b3f2',
    properties: [
      {
        externalId: 'listing-123',
        source: 'automation-tool',
        address: '123 Main Street',
        city: 'Los Angeles',
        state: 'CA',
        bedrooms: 3,
        bathrooms: 2,
        price: 2500,
        priceType: 'monthly',
        contactEmail: 'landlord@example.com',
        contactPhone: '+1-555-123-4567',
      },
    ],
  }),
});

const data = await response.json();
console.log(data);

Python

Python 
import requests

response = requests.post(
    'https://app.havnly.ai/api/webhooks/external-properties',
    headers={
        'x-api-key': 'uZMXc8dFLfrifpEXsvLSjG0IhGxjBYxVyCCxuUjv60',
    },
    json={
        'claimId': '2ab41281-12f8-44a9-a9c7-1cbb00b9b3f2',
        'properties': [
            {
                'externalId': 'listing-123',
                'source': 'automation-tool',
                'address': '123 Main Street',
                'city': 'Los Angeles',
                'state': 'CA',
                'bedrooms': 3,
                'bathrooms': 2,
                'price': 2500,
                'priceType': 'monthly',
                'contactEmail': 'landlord@example.com',
                'contactPhone': '+1-555-123-4567',
            }
        ]
    }
)

print(response.json())

Notes