Using WPResidence API for Developer Management: A Step-by-Step Guide

Real estate platforms often need to manage various types of entities, and property developers represent a crucial segment of the market. WPResidence’s API provides comprehensive endpoints for managing developer entities programmatically. This guide explores how to leverage these endpoints for efficient developer management.

Who Are Developers in WPResidence?

In WPResidence real estate theme, developers are entities responsible for creating and developing real estate projects. They’re stored as custom post types (estate_developer) with associated metadata. Developers typically:

• Create multiple properties or developments
• Have company information (contact details, location, etc.)
• Maintain portfolios of past, current, and upcoming projects
• Link to agencies and agents selling their properties

Developers differ from agencies in that they focus on property creation rather than sales, though the system allows for relationships between these entities.

Listing Developers: Retrieving Data via API

To retrieve a list of developers with filtering capabilities, use the developers endpoint.

Endpoint: POST /wpresidence/v1/developers

This endpoint accepts POST requests with a JSON body containing filter parameters.

Request Parameters

{
  "page": 1,
  "posts_per_page": 10,
  "fields": "ID,title,description,developer_email,developer_phone",
  "meta": {
    "developer_city": {
      "value": "Miami",
      "compare": "=",
      "type": "CHAR"
    },
    "developer_projects": {
      "value": 5,
      "compare": ">",
      "type": "NUMERIC"
    }
  },
  "taxonomies": {
    "property_category": [12, 15],
    "property_action_category": [7]
  }
}

Key parameters include:

• page: Pagination control (integer, default: 1)
• posts_per_page: Results per page (integer, default: 10)
• fields: Comma-separated field list to include in response
• meta: Object with metadata filters
  • key: Field name to filter by
  • value: 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)
• taxonomies: Object with taxonomy names as keys and term IDs as values

Response Structure

{
  "status": "success",
  "query_args": {
    "post_type": "estate_developer",
    "paged": 1,
    "posts_per_page": 10,
    "meta_query": [...],
    "tax_query": [...]
  },
  "data": [
    {
      "ID": 345,
      "title": "Coastal Development Group",
      "description": "Luxury beachfront development specialists",
      "developer_email": "info@coastaldevelopment.com",
      "developer_phone": "305-555-1212"
    },
    // Additional developers...
  ],
  "total": 27,
  "pages": 3
}

Viewing Developer Information

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

Endpoint: GET /wpresidence/v1/developer/{id}

Where {id} is the developer’s post ID.

Request Parameters

• id: (Required) Developer ID (path parameter)
• fields: (Optional) Comma-separated field list

Example:

GET /wpresidence/v1/developer/345?fields=ID,title,description,developer_email,developer_phone,developer_website,developer_license

Response Example

{
  "ID": 345,
  "title": "Coastal Development Group",
  "description": "Luxury beachfront development specialists with over 20 years of experience creating premium oceanfront properties.",
  "developer_email": "info@coastaldevelopment.com",
  "developer_phone": "305-555-1212",
  "developer_website": "https://coastaldevelopment.com",
  "developer_license": "FL-DEV-78901"
}

Adding a New Developer (Request Structure & Fields)

New developers can be created using the developer creation endpoint.

Endpoint: POST /wpresidence/v1/developer/add

Authentication Requirements

• Valid JWT token in request header
• User must be logged in
• User must have publish_estate_developers capability

Required Fields

• developer_name: Company/developer name
• developer_email: Valid email address

Full Request Example

{
  "developer_name": "Urban Horizon Developers",
  "developer_email": "contact@urbanhorizon.com",
  "developer_description": "Urban Horizon specializes in sustainable mixed-use developments in metropolitan areas. Our focus is on creating environmentally friendly buildings with modern amenities.",
  "developer_phone": "415-555-7890",
  "developer_mobile": "415-555-7891",
  "developer_skype": "urbanhorizon",
  "developer_address": "525 Market St, San Francisco, CA 94105",
  "developer_website": "https://urbanhorizon.com",
  "developer_license": "CA-DEV-45678",
  "developer_taxes": "47-1234567",
  "developer_facebook": "urbanhorizondev",
  "developer_twitter": "urbanhoriz_dev",
  "developer_linkedin": "urban-horizon-developers",
  "developer_pinterest": "urbanhorizondev",
  "developer_instagram": "urbanhorizon_dev",
  "developer_custom_data": [
    {"label": "Founded", "value": "2009"},
    {"label": "Projects Completed", "value": "27"},
    {"label": "Sustainability Certification", "value": "LEED Platinum"}
  ],
  "featured_image": "https://example.com/images/urban-horizon-logo.jpg",
  "user_registration": {
    "username": "urbanhorizon",
    "email": "contact@urbanhorizon.com",
    "password": "secure_password_here",
    "role": "developer"
  }
}

Optional Fields

• developer_custom_data: Array of label-value pairs for custom information
• featured_image: URL to image for developer profile
• user_registration: Creates WordPress user associated with developer
• Taxonomy terms (by providing taxonomy names as field keys with term IDs)

Response

{
  "status": "success",
  "developer_id": 789,
  "message": "Developer created successfully."
}

Updating Developer Profiles

Developer information can be updated through the developer update endpoint.

Endpoint: PUT /wpresidence/v1/developer/edit/{id}

Where {id} is the developer’s post ID.

Authentication and Permissions

• Valid JWT token
• User must be logged in
• Developer must exist and be correct post type
• User must be developer creator or have admin rights

Request Example

{
  "developer_name": "Urban Horizon Sustainable Developers",
  "developer_description": "Updated company description with new project focus areas and community initiatives.",
  "developer_phone": "415-555-9999",
  "developer_custom_data": [
    {"label": "Founded", "value": "2009"},
    {"label": "Projects Completed", "value": "32"},
    {"label": "Sustainability Certification", "value": "LEED Platinum, Living Building Challenge"},
    {"label": "Community Investment", "value": "$15M"}
  ],
  "featured_image": "https://example.com/images/urban-horizon-new-logo.jpg"
}

Only include fields that need updating; omitted fields remain unchanged.

Response

{
  "status": "success",
  "developer_id": 789,
  "message": "Developer updated successfully."
}

Removing a Developer from the System

Developers can be permanently removed using the deletion endpoint.

Endpoint: DELETE /wpresidence/v1/developer/delete/{id}

Where {id} is the developer’s post ID.

Authentication and Permissions

The API verifies:

• JWT token validity
• User login status
• Developer existence
• User has permission (creator or admin)

System Changes on Deletion

When a developer is deleted:

1. Developer post and all metadata are removed
2. Any WordPress user associations are updated (user_developer_id meta is cleared)
3. Properties may need reassignment if linked to this developer

Response

{
  "status": "success",
  "message": "Developer deleted successfully."
}

Linking Developers to Properties & Agencies

Developer-Property Relationships

Properties can be associated with developers through:

1. Property Meta: A property has a property_developer meta field
2. Developer Projects List: Developers can maintain lists of project IDs

To associate a property with a developer during property creation/update:

{
  "property_title": "Skyline Tower",
  "property_developer": 789,
  "other_property_fields": "..."
}

Developer-Agency Relationships

Developers and agencies can have partnerships through:

1. Cross-referencing: An agency can list preferred developers and vice versa
2. Project-based: Specific properties can link both a developer and selling agency

When creating an agency that represents developers:

{
  "agency_name": "Metropolitan Real Estate",
  "associated_developers": [789, 790, 791],
  "other_agency_fields": "..."
}

Debugging API Errors

Common Error Types

1. Authentication Errors
   • jwt_auth_failed: Invalid/missing JWT token
   • rest_forbidden: User lacks required permissions
2. Validation Errors
   • rest_missing_field: Required field missing
   • rest_invalid_email: Invalid email format
   • rest_invalid_developer: Invalid developer ID
   • rest_developer_not_found: Developer not found
3. Server Errors
   • user_registration_failed: Error during user creation

Troubleshooting Steps

1. Check Request Format
   • Verify endpoint URL is correct
   • Ensure JSON payload is valid
   • Validate required fields are present
2. Verify Authentication
   • Confirm JWT token is valid and included
   • Check user has necessary permissions
3. Review Response Details
   • Error responses include details about the issue:
   { "code": "rest_missing_field", "message": "Missing mandatory field: developer_email", "data": { "status": 400 } }
4. Test with Minimal Data
   • Start with only required fields
   • Add optional fields incrementally
   • Isolate problematic fields
5. Check Server Logs
   • Review WordPress debug logs for additional details
   • Look for PHP errors that might not appear in API responses

Best Practices for Error Handling

1. Implement Retry Logic
   • Add exponential backoff for temporary failures
   • Set maximum retry attempts
2. Log Request/Response Pairs
   • Keep detailed logs for debugging
   • Include timestamps, request IDs, and context
3. Validate Data Before Sending
   • Implement client-side validation
   • Check data types and format
4. Handle Errors Gracefully
   • Display user-friendly error messages
   • Provide recovery options when possible

Conclusion

WPResidence’s API provides robust tools for managing real estate developers programmatically. By understanding the available endpoints, required parameters, and best practices, you can create efficient integrations that automate developer management workflows.

Key takeaways:

• Use field filtering to optimize response payloads
• Implement proper error handling and validation
• Follow security best practices with authentication
• Consider the relationships between developers, properties, and agencies
• Test thoroughly with various data scenarios

With these practices in place, the WPResidence API can significantly enhance your real estate platform’s developer management capabilities, saving time and reducing manual data entry while maintaining data integrity across systems.

Official documentation is here : https://www.postman.com/universal-eclipse-339362/wpresidence/overview

FAQ

How do developers work in WPResidence, and how are they stored in WordPress?

In WPResidence, developers are entities responsible for creating and developing real estate projects. They are stored as a custom post type named estate_developer, with associated metadata for items like contact details, location, and project portfolio information. Developers are distinct from agencies because they focus on property creation rather than sales, but WPResidence supports relationships between developers, agencies, agents, and properties.

How do I list developers via the WPResidence API with filters and pagination?

Use the developers listing endpoint: POST /wpresidence/v1/developers. Send a JSON body with pagination (page, posts_per_page), a comma-separated fields selection, and optional filtering via meta (metadata queries) and taxonomies (taxonomy term IDs). For example, you can filter by metadata such as developer_city using a CHAR type comparison, and by numeric metadata like developer_projects using a NUMERIC comparison, while also restricting results to specific property_category and property_action_category term IDs.

How can I retrieve details for a single developer and limit the fields returned?

To fetch one developer, call GET /wpresidence/v1/developer/{id}, where {id} is the developer post ID. If you want to reduce payload size, include the optional fields query parameter with a comma-separated list, for example: ID,title,description,developer_email,developer_phone,developer_website,developer_license.

What do I need to create a new developer through the WPResidence API, and what fields are required?

Create developers with POST /wpresidence/v1/developer/add. You must include a valid JWT token in the request header, be logged in, and have the publish_estate_developers capability. The required fields are developer_name and developer_email; additional profile fields (such as description, phone, address, website, license, social links), developer_custom_data, featured_image, taxonomy term IDs, and optional user_registration can be provided as needed.

How do updating and deleting developers work, and what happens to linked data?

Update a developer with PUT /wpresidence/v1/developer/edit/{id}. The request requires a valid JWT token and login, the developer must exist and be the correct post type, and the user must be the developer creator or have admin rights. Only send the fields you want to change; omitted fields remain unchanged.

Delete a developer with DELETE /wpresidence/v1/developer/delete/{id}. The API verifies JWT validity, login status, developer existence, and that the user is the creator or an admin. Deletion removes the developer post and all metadata, clears any associated WordPress user linkage by removing the user_developer_id meta, and properties linked to that developer may need reassignment.