API Reference

Open House provides a comprehensive REST API that allows you to integrate property management and visitor tracking into your applications. This documentation covers all available endpoints and authentication methods.

Authentication

API Keys

All API requests require authentication using API keys:

• API Key Location: Include in the Authorization header
• Format: Bearer YOUR_API_KEY
• Security: Keep your API key secure and never expose it in client-side code

Getting Your API Key

1. Log into your Open House account
2. Go to Account Settings
3. Click "API Keys"
4. Generate a new API key
5. Copy and store the key securely

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.openhouse.com/v1/properties

Base URL

All API endpoints are relative to the base URL:

https://api.openhouse.com/v1

Properties API

List Properties

Retrieve a list of all properties for the authenticated user.

Endpoint

GET /properties

Parameters

• page (optional): Page number for pagination (default: 1)
• per_page (optional): Number of properties per page (default: 20, max: 100)
• status (optional): Filter by status (active, pending, sold)
• search (optional): Search in property title and address

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "Beautiful Family Home",
      "price": 450000,
      "address": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip_code": "90210",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 50,
    "last_page": 3
  }
}

Get Property

Retrieve a specific property by ID.

Endpoint

GET /properties/{id}

Response

{
  "data": {
    "id": "uuid",
    "title": "Beautiful Family Home",
    "price": 450000,
    "address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210",
    "description": "Rich text description...",
    "property_type": "single_family",
    "bedrooms": 3,
    "bathrooms": 2,
    "square_feet": 2000,
    "lot_size": "0.25 acres",
    "year_built": 2010,
    "mls_number": "MLS123456",
    "status": "active",
    "featured_image": "https://...",
    "gallery_images": ["https://...", "https://..."],
    "public_url": "https://openhouse.com/p/property-slug",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Create Property

Create a new property listing.

Endpoint

POST /properties

Request Body

{
  "title": "Beautiful Family Home",
  "price": 450000,
  "address": "123 Main St",
  "city": "Anytown",
  "state": "CA",
  "zip_code": "90210",
  "description": "Rich text description...",
  "property_type": "single_family",
  "bedrooms": 3,
  "bathrooms": 2,
  "square_feet": 2000,
  "lot_size": "0.25 acres",
  "year_built": 2010,
  "mls_number": "MLS123456",
  "status": "active"
}

Response

{
  "data": {
    "id": "uuid",
    "title": "Beautiful Family Home",
    "price": 450000,
    "address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210",
    "description": "Rich text description...",
    "property_type": "single_family",
    "bedrooms": 3,
    "bathrooms": 2,
    "square_feet": 2000,
    "lot_size": "0.25 acres",
    "year_built": 2010,
    "mls_number": "MLS123456",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Update Property

Update an existing property.

Endpoint

PUT /properties/{id}

Request Body

Include only the fields you want to update.

{
  "price": 475000,
  "status": "pending"
}

Delete Property

Delete a property (this action cannot be undone).

Endpoint

DELETE /properties/{id}

Response

{
  "message": "Property deleted successfully"
}

Visitor Tracking API

List Visitors

Retrieve visitors for a specific property.

Endpoint

GET /properties/{property_id}/visitors

Parameters

• page (optional): Page number for pagination
• per_page (optional): Number of visitors per page
• interest_level (optional): Filter by interest level (high, medium, low)
• date_from (optional): Filter by sign-in date (YYYY-MM-DD)
• date_to (optional): Filter by sign-in date (YYYY-MM-DD)

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "interest_level": "high",
      "timeline": "1-3 months",
      "financing": "cash",
      "notes": "Interested in the backyard",
      "signed_in_at": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 25,
    "last_page": 2
  }
}

Get Visitor

Retrieve a specific visitor by ID.

Endpoint

GET /properties/{property_id}/visitors/{visitor_id}

Create Visitor

Create a new visitor sign-in record.

Endpoint

POST /properties/{property_id}/visitors

Request Body

{
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "interest_level": "high",
  "timeline": "1-3 months",
  "financing": "cash",
  "notes": "Interested in the backyard"
}

File Upload API

Upload Property Images

Upload images for a property.

Endpoint

POST /properties/{property_id}/images

Request

Use multipart/form-data to upload files.

• featured_image (optional): Set as featured image
• gallery_images[] (optional): Array of gallery images

Response

{
  "data": {
    "featured_image": "https://...",
    "gallery_images": ["https://...", "https://..."]
  }
}

Export API

Export Property Data

Export property data in various formats.

Endpoint

GET /properties/{id}/export

Parameters

• format (required): Export format (pdf, csv, json)
• include_images (optional): Include images in export (default: true)

Export Visitor Data

Export visitor data for a property.

Endpoint

GET /properties/{property_id}/visitors/export

Parameters

• format (required): Export format (pdf, csv, json)
• date_from (optional): Filter by date range
• date_to (optional): Filter by date range

Error Handling

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": {
      "field": "Additional error details"
    }
  }
}

Common Error Codes

• 401: Unauthorized (invalid API key)
• 403: Forbidden (insufficient permissions)
• 404: Not found (resource doesn't exist)
• 422: Validation error (invalid request data)
• 429: Rate limit exceeded
• 500: Internal server error

Rate Limiting

API requests are rate limited to ensure fair usage:

• Limit: 1000 requests per hour per API key
• Headers: Rate limit info included in response headers
• Exceeded: Returns 429 status code when limit exceeded

SDKs and Libraries

Official SDKs

We provide official SDKs for popular programming languages:

• JavaScript/Node.js: npm install openhouse-api
• PHP: composer require openhouse/api
• Python: pip install openhouse-api
• Ruby: gem install openhouse-api

Example Usage (JavaScript)

const OpenHouse = require('openhouse-api');

const client = new OpenHouse({
  apiKey: 'YOUR_API_KEY'
});

// List properties
const properties = await client.properties.list();

// Create a property
const property = await client.properties.create({
  title: 'Beautiful Home',
  price: 450000,
  address: '123 Main St',
  city: 'Anytown',
  state: 'CA',
  zip_code: '90210'
});

Webhooks

Setting Up Webhooks

Receive real-time notifications when events occur:

• Property Created: When a new property is created
• Property Updated: When a property is modified
• Visitor Signed In: When a visitor signs in
• Subscription Events: Billing and subscription changes

Webhook Configuration

POST /webhooks
{
  "url": "https://your-app.com/webhooks/openhouse",
  "events": ["property.created", "visitor.signed_in"],
  "secret": "your-webhook-secret"
}

Webhook Payload

{
  "event": "property.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "property": {
      "id": "uuid",
      "title": "Beautiful Home",
      "price": 450000
    }
  }
}