Introduction to Property Management via API

The WPResidence REST API offers a comprehensive solution for managing real estate properties programmatically. This powerful interface enables developers to integrate WPResidence’s property management capabilities into custom applications, third-party services, or automated workflows. Whether building a mobile app, integrating with external platforms, or developing custom front-end experiences, the WPResidence API provides the necessary tools.

The API is built on WordPress REST API standards, providing a familiar structure for WordPress developers while offering real estate-specific features. All endpoints are prefixed with /wpresidence/v1/ to identify them as part of the WPResidence ecosystem.

This guide explores all available endpoints for property management, detailing how to:

• List and filter properties
• View detailed property information
• Create new property listings
• Update existing properties
• Delete properties
• Handle media attachments and property images

Each section includes example requests, required parameters, and best practices to help you successfully implement WPResidence API integrations.

Listing Properties: Fetching Available Listings

The properties endpoint retrieves multiple property listings with powerful filtering options.

Endpoint Details

POST /wpresidence/v1/properties

This endpoint uses the POST method to support complex filtering through the request body. This approach allows for more sophisticated queries than would be possible with URL parameters alone.

Key Parameters

The API accepts numerous parameters for filtering and customizing the response:

Parameter	Type	Description
page	integer	Page number for pagination (defaults to 1)
posts_per_page	integer	Number of properties per page (defaults to 10)
order	integer	Sorting order (0 = default)
response_type	string	‘basic’ or ‘full’ (determines amount of data returned)
userID	integer	Filter by property owner
fields	string	Comma-separated list of specific fields to include
taxonomies	object	Filter by taxonomy terms
meta	object	Filter by custom meta fields

Filtering with Meta Parameters

The meta parameter allows for sophisticated querying based on property metadata. Each meta query can include:

• key: The meta field name
• value: The value to compare against
• compare: Comparison operator (=, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS, NOT EXISTS)
• type: Data type (NUMERIC, BINARY, CHAR, DATE, DATETIME, DECIMAL, SIGNED, TIME, UNSIGNED)

Example meta query for properties priced between $200,000 and $500,000:

"meta": {
  "property_price": {
    "value": [200000, 500000],
    "compare": "BETWEEN",
    "type": "NUMERIC"
  }
}

Filtering with Taxonomies

The taxonomies parameter enables filtering by property categories, features, types, and other taxonomies:

"taxonomies": {
  "property_features": ["pool", "garage", "air-conditioning"],
  "property_city": ["miami", "new-york"]
}

Example Request

{
  "page": 1,
  "posts_per_page": 20,
  "response_type": "basic",
  "meta": {
    "property_price": {
      "value": [200000, 500000],
      "compare": "BETWEEN",
      "type": "NUMERIC"
    },
    "property_bedrooms": {
      "value": 3,
      "compare": ">=",
      "type": "NUMERIC"
    }
  },
  "taxonomies": {
    "property_city": ["new-york"],
    "property_features": ["garage"]
  }
}

Response Structure

The response includes:

• status: Success or error
• query_args: The processed query arguments
• data: Array of property objects
• total: Total number of properties matching the criteria
• pages: Total number of pages available

Basic responses include only essential information (ID, title, price, location), while full responses include all property data.

Best Practices for Listing Properties

1. Use pagination for large datasets to improve performance.
2. Limit fields with the fields parameter when you only need specific data.
3. Optimize queries by using precise meta and taxonomy filters.
4. Cache responses when appropriate to reduce API load.
5. Handle empty results gracefully in your application.

Viewing Property Details: Fetching Data for a Single Property

To retrieve detailed information about a specific property, use the single property endpoint.

Endpoint Details

GET /wpresidence/v1/property/{id}

This endpoint returns comprehensive information about a single property identified by its ID.

Key Parameters

Parameter	Type	Description
id	integer	Property ID (required)
response_type	string	‘basic’ or ‘full’ (defaults to ‘full’)
fields	string	Comma-separated list of specific fields to include

Field Selection

The fields parameter allows you to request only specific property data fields, improving performance and reducing response size. Fields can be nested using dot notation:

fields=id,title,meta.property_price,meta.property_bedrooms

Example Request

GET /wpresidence/v1/property/1234?response_type=full&fields=id,title,meta.property_price,meta.property_bedrooms

Response Structure

The response includes all requested property data. A full response contains:

• Basic information (ID, title, status)
• Author information
• Publication date and modification date
• Property meta fields (price, bedrooms, bathrooms, etc.)
• Taxonomy terms (categories, features, etc.)
• Media attachments
• Thumbnail and gallery images

Best Practices for Viewing Property Details

1. Request only needed fields to optimize response size and processing time.
2. Handle missing fields gracefully in your application.
3. Cache property details when appropriate to reduce API calls.
4. Validate property existence before attempting other operations.

Creating a New Property

The property creation endpoint allows you to add new property listings programmatically.

Endpoint Details

POST /wpresidence/v1/property/add

This endpoint requires authentication and proper user permissions.

Required Fields

The API enforces mandatory fields configured in the WPResidence options. Common required fields include:

• title: Property title
• property_description: Detailed description
• Property location details (address, city, etc.)
• Property specifics (price, size, bedrooms, etc.)

Key Parameters

Parameter	Type	Description
title	string	Property title
property_description	string	Detailed property description
Various meta fields	mixed	Property-specific data (price, bedrooms, etc.)
Taxonomy terms	arrays	Categories, features, cities, etc.
images	array	Property images data
custom_fields	array	Additional custom field data

Handling Property Taxonomies

To assign taxonomy terms to a property, include arrays of term values:

{
  "property_city": ["new-york"],
  "property_features": ["pool", "garage", "air-conditioning"]
}

Handling Custom Fields

Custom fields are provided as an array of objects with slug and value properties:

"custom_fields": [
  {"slug": "construction_year", "value": "2020"},
  {"slug": "energy_rating", "value": "A"}
]

Handling Images

Images are provided as an array of objects with id and url properties:

"images": [
  {"id": "main", "url": "https://example.com/property-front.jpg"},
  {"id": "kitchen", "url": "https://example.com/kitchen.jpg"}
]

The API will:

• Download the images
• Validate file types and sizes
• Create WordPress attachments
• Set the first image as the featured image
• Create a property gallery

Example Request

{
  "title": "Luxury Penthouse in Downtown",
  "property_description": "Stunning penthouse with panoramic city views...",
  "property_price": 750000,
  "property_bedrooms": 3,
  "property_bathrooms": 2,
  "property_size": 2000,
  "property_address": "123 Main Street",
  "property_city": ["new-york"],
  "property_features": ["pool", "gym", "concierge"],
  "custom_fields": [
    {"slug": "construction_year", "value": "2019"},
    {"slug": "parking_spaces", "value": "2"}
  ],
  "images": [
    {"id": "main", "url": "https://example.com/penthouse-main.jpg"},
    {"id": "living", "url": "https://example.com/penthouse-living.jpg"},
    {"id": "bedroom", "url": "https://example.com/penthouse-bedroom.jpg"}
  ]
}

Response Structure

On success, the API returns:

{
  "status": "success",
  "property_id": 1234
}

Best Practices for Creating Properties

1. Validate data client-side before submission.
2. Handle membership limitations appropriately (if applicable).
3. Optimize image sizes before upload to improve performance.
4. Use HTTPS URLs only for image sources.
5. Implement proper error handling for failed property creation.
6. Verify all mandatory fields are provided before submission.

Updating Property Information

The property update endpoint allows you to modify existing property listings.

Endpoint Details

PUT /wpresidence/v1/property/edit/{id}

This endpoint requires authentication and property ownership verification.

Key Parameters

Parameter	Type	Description
id	integer	Property ID (required)
All property fields	mixed	Any fields that need updating

Handling Partial Updates

The API supports partial updates, allowing you to modify only specific fields without affecting others. Simply include only the fields you want to update in your request.

Example Request

{
  "title": "Updated Luxury Penthouse",
  "property_price": 800000,
  "property_features": ["pool", "gym", "concierge", "balcony"]
}

This request updates the title, price, and features without affecting other property data.

Response Structure

On success, the API returns:

{
  "status": "success",
  "property_id": 1234,
  "message": "Property updated successfully."
}

Best Practices for Updating Properties

1. Send only changed fields to optimize performance.
2. Verify property ownership before attempting updates.
3. Handle taxonomy terms properly (remember they replace existing terms).
4. Implement proper validation for required fields.
5. Implement proper error handling for failed updates.

Deleting a Property Securely

The property deletion endpoint allows you to permanently remove property listings.

Endpoint Details

DELETE /wpresidence/v1/property/delete/{id}

This endpoint requires authentication and property ownership verification.

Key Parameters

Parameter	Type	Description
id	integer	Property ID (required)

Example Request

DELETE /wpresidence/v1/property/delete/1234

Response Structure

On success, the API returns:

{
  "status": "success",
  "property_id": 1234,
  "message": "Property deleted successfully."
}

Best Practices for Deleting Properties

1. Implement confirmation steps in your application before deletion.
2. Verify property ownership before attempting deletion.
3. Handle errors appropriately if deletion fails.
4. Update related data that might reference the deleted property.
5. Consider soft deletion alternatives when appropriate.

Handling Property Images & Attachments via API

The WPResidence API provides robust handling for property images during creation and updates.

Image Requirements

• URL Format: Must be HTTPS for security
• File Types: JPEG, PNG, GIF, and WebP only
• Size Limits: Maximum 5MB per image
• Validation: MIME type verification and image integrity checking

Image Processing Workflow

1. Validation: Security checks for URLs, file types, and sizes
2. Download: Secure downloading with timeouts and error handling
3. Processing: Creation of WordPress media attachments and thumbnails
4. Gallery Creation: Automatic property gallery generation
5. Featured Image: First image automatically set as featured image

Example Image Data Format

"images": [
  {"id": "main", "url": "https://example.com/property-front.jpg"},
  {"id": "kitchen", "url": "https://example.com/kitchen.jpg"},
  {"id": "bedroom", "url": "https://example.com/bedroom.jpg"}
]

Best Practices for Image Handling

1. Optimize images before uploading to improve performance.
2. Use descriptive IDs to identify image purposes.
3. Implement proper error handling for failed image processing.
4. Verify image URLs are accessible and valid.
5. Host images on reliable servers to ensure availability during API operations.
6. Limit image count to reasonable numbers for better performance.

Error Handling and Best Practices

The WPResidence API uses standard HTTP status codes and WP_Error objects to communicate errors.

Common Error Types

• Authentication Errors (403): Invalid or missing JWT tokens
• Permission Errors (403): Insufficient permissions for the operation
• Validation Errors (400): Invalid or missing required parameters
• Not Found Errors (404): Property or resource not found
• Server Errors (500): Internal processing failures

Error Response Format

{
  "code": "rest_property_not_found",
  "message": "Property not found.",
  "data": {
    "status": 404
  }
}

General Best Practices

1. Implement proper authentication using JWT tokens.
2. Validate input data client-side before submission.
3. Handle all error types appropriately in your application.
4. Use pagination for listing endpoints to improve performance.
5. Request only needed fields to optimize response size.
6. Implement rate limiting in your application to prevent API abuse.
7. Cache responses when appropriate to reduce API load.
8. Follow REST conventions for method usage (GET for reading, POST for creating, etc.).
9. Sanitize and validate all user input before sending to the API.
10. Implement proper logging for debugging API interactions.

Security Best Practices

1. Use HTTPS for all API communications.
2. Validate JWT tokens properly and handle expirations.
3. Implement proper user permission checks in your application.
4. Sanitize all input data to prevent injection attacks.
5. Limit API access to authorized users only.
6. Implement proper error handling without exposing sensitive information.
7. Monitor API usage for unusual patterns or abuse.

By following these guidelines and best practices, you can create robust, efficient, and secure integrations with the WPResidence API for comprehensive property management.