Automating Agent Management with WPResidence API

Real estate website management can be time-consuming, especially when handling multiple agent profiles. The WPResidence API offers robust endpoints for automating agent management tasks, improving efficiency and reducing manual data entry. This article explores the complete lifecycle of agent management through API integration.

Introduction to Agent Management

In WPResidence, agents are stored as custom post types (estate_agent) with associated metadata like contact information, social profiles, and property listings. The API allows programmatic access to create, read, update, and delete agents, enabling:

• Batch operations for bulk agent imports
• Synchronization with HR or CRM systems
• Automated profile updates
• Integration with third-party applications

Agent management through the API requires proper authentication using JWT tokens and specific permissions. Different operations require different permission levels, with creation and modification typically restricted to administrators or users with the publish_estate_agents capability.

Fetching Agent Listings: How to Get Agents from the API

The agent listing endpoint allows retrieval of multiple agents with powerful filtering capabilities.

Endpoint: POST /wpresidence/v1/agents

Request Parameters

{
  "page": 1,
  "posts_per_page": 10,
  "fields": "ID,title,description,first_name,last_name,agent_email,agent_phone",
  "meta": {
    "agent_position": {
      "value": "Senior Agent",
      "compare": "=",
      "type": "CHAR"
    },
    "agent_license": {
      "value": ["NY-123456", "NY-789012"],
      "compare": "IN",
      "type": "CHAR"
    },
    "agent_experience": {
      "value": 5,
      "compare": ">",
      "type": "NUMERIC"
    }
  },
  "taxonomies": {
    "property_category": [12, 15],
    "property_action_category": [7]
  }
}

Key parameters include:

• page: Pagination control (default: 1)
• posts_per_page: Results per page (default: 10)
• fields: Comma-separated list of fields to include in response
• meta: Object with metadata-based filters
  • Supports various comparison operators: =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS, NOT EXISTS
  • Data types include: NUMERIC, BINARY, CHAR, DATE, DATETIME, DECIMAL, SIGNED, TIME, UNSIGNED
• taxonomies: Object with taxonomy terms to filter by

Response Structure

{
  "status": "success",
  "query_args": {...},
  "data": [
    {
      "ID": 123,
      "title": "John Smith",
      "description": "Experienced real estate professional...",
      "first_name": "John",
      "last_name": "Smith",
      "agent_email": "john.smith@example.com",
      "agent_phone": "555-1234"
    },
    // Additional agents...
  ],
  "total": 45,
  "pages": 5
}

Best Practices for Agent Listing Retrieval

1. Optimize Field Selection: Only request needed fields to reduce response size
2. Implement Pagination: For large agent lists, use page and posts_per_page parameters
3. Use Targeted Filtering: Leverage meta queries for precise results
4. Cache Results: Store results for frequently accessed agent lists

Viewing Agent Details via API

To retrieve comprehensive information about a specific agent, use the single agent endpoint.

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

Request Parameters

• id: (Required) Agent ID as path parameter
• fields: (Optional) Comma-separated list of fields to include

Example request:

GET /wpresidence/v1/agent/123?fields=ID,title,description,agent_email,agent_phone,agent_mobile,agent_skype,agent_position

Response Example

{
  "ID": 123,
  "title": "John Smith",
  "description": "Experienced real estate professional specializing in residential properties...",
  "agent_email": "john.smith@example.com",
  "agent_phone": "555-1234",
  "agent_mobile": "555-5678",
  "agent_skype": "john.smith.realtor",
  "agent_position": "Senior Agent"
}

Creating New Agents (Fields Required & JSON Payload)

The agent creation endpoint allows adding new agents to the system.

Endpoint: POST /wpresidence/v1/agent/add

Authentication and Permissions

• Valid JWT token required
• User must have publish_estate_agents capability
• Some installations may have membership-based restrictions

Required Fields

• first_name: Agent’s first name
• last_name: Agent’s last name
• agent_email: Valid email address

Complete JSON Payload Example

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "agent_email": "sarah.johnson@example.com",
  "agent_description": "Sarah Johnson is a dedicated real estate professional with over 10 years of experience in the luxury property market.",
  "agent_position": "Luxury Property Specialist",
  "agent_phone": "555-9876",
  "agent_mobile": "555-6543",
  "agent_skype": "sarah.johnson.realtor",
  "agent_address": "123 Main Street, New York, NY 10001",
  "agent_website": "https://sarahjohnson.example.com",
  "agent_facebook": "sarahjohnsonrealtor",
  "agent_twitter": "sarahjohnson_re",
  "agent_linkedin": "sarahjohnson-realtor",
  "agent_instagram": "sarahjohnson.homes",
  "agent_pinterest": "sarahjohnsonhomes",
  "agent_youtube": "SarahJohnsonRealEstate",
  "agent_custom_data": [
    {"label": "Languages", "value": "English, Spanish, French"},
    {"label": "Specialization", "value": "Waterfront Properties"},
    {"label": "Awards", "value": "Top Producer 2022, 2023"}
  ],
  "featured_image": "https://example.com/images/sarah-johnson.jpg",
  "user_registration": {
    "username": "sarahjohnson",
    "email": "sarah.johnson@example.com",
    "password": "securePassword123",
    "role": "agent"
  }
}

Optional Fields

• agent_custom_data: Array of label-value pairs for custom information
• featured_image: URL to image for agent profile
• user_registration: Creates a WordPress user associated with the agent
• Various social media profiles and contact information

Response

{
  "status": "success",
  "agent_id": 456,
  "message": "Agent created successfully."
}

Updating an Agent Profile

The agent update endpoint allows modifying existing agent information.

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

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

Authentication and Permissions

• Valid JWT token required
• User must either be the agent author or have edit_others_posts capability

JSON Payload Example

{
  "first_name": "Sarah",
  "last_name": "Johnson-Williams",
  "agent_description": "Updated bio with recent achievements and specializations.",
  "agent_position": "Director of Luxury Properties",
  "agent_phone": "555-1111",
  "agent_custom_data": [
    {"label": "Languages", "value": "English, Spanish, French, Italian"},
    {"label": "Specialization", "value": "Waterfront and Historic Properties"},
    {"label": "Awards", "value": "Top Producer 2022, 2023, Realtor of the Year 2023"}
  ],
  "featured_image": "https://example.com/images/sarah-johnson-new.jpg"
}

Only include fields that need updating; others remain unchanged.

Response

{
  "status": "success",
  "agent_id": 456,
  "message": "Agent updated successfully."
}

Removing an Agent via API

The agent deletion endpoint allows removing agents from the system.

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

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

Authentication and Permissions

• Valid JWT token required
• User must either be the agent author or have edit_others_posts capability

System Effects on Deletion

When an agent is deleted:

1. The agent post and associated metadata are permanently removed
2. WordPress user association is cleaned up (user_agent_id meta is cleared)
3. Agent is removed from any agency agent lists
4. Properties may need reassignment

Response

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

Connecting Agents to Properties Automatically

While the API doesn’t have a specific endpoint for connecting agents to properties, this can be accomplished through the property API endpoints and meta relationships.

Agent-Property Association Methods

1. During Property Creation/Update: Set the agent ID in the property metadata

{
  "property_title": "Luxury Condo Downtown",
  "property_agent": 456,
  "other_property_fields": "..."
}

2. Batch Association: Create a custom script that:
   • Retrieves properties matching specific criteria
   • Updates each property with the appropriate agent ID
   • Uses property update endpoint with minimal data
3. Rules-Based Assignment: Implement logic for automatic agent assignment based on:
   • Property location
   • Property type
   • Price range
   • Agent specialization

Best Practices for Agent-Property Connections

1. Maintain Consistency: Develop standardized rules for agent assignments
2. Handle Reassignment: Create procedures for when agents leave or change roles
3. Track Relationships: Maintain a record of agent-property relationships for reporting
4. Consider Load Balancing: Distribute properties among agents based on workload

Common API Errors and Troubleshooting

Authentication Errors

• jwt_auth_failed: Invalid or missing JWT token
  • Solution: Verify token is valid and included in headers
• rest_forbidden: Permission issues
  • Solution: Check user has required capabilities

Validation Errors

• rest_missing_field: Required field not provided
  • Solution: Ensure all mandatory fields are included
• rest_invalid_email: Email format invalid
  • Solution: Validate email format before submission
• rest_invalid_agent: Agent ID not found
  • Solution: Verify agent exists before operations

Troubleshooting Strategies

1. Start Simple: Begin with minimal valid requests before adding complexity
2. Check Permissions: Ensure the authenticated user has proper capabilities
3. Validate Input Data: Implement client-side validation before API submission
4. Test Incrementally: Make small changes and test after each modification
5. Error Logging: Implement detailed logging of API interactions
6. Use Test Environment: Test changes in development before production

Common Best Practices

1. Error Handling: Implement robust error handling with user-friendly messages
2. Retry Logic: Add intelligent retry mechanisms for transient failures
3. Rate Limiting: Respect API limits and implement rate limiting
4. Idempotency: Design operations to be safely repeatable

Conclusion

The WPResidence API provides powerful tools for automating agent management, enabling developers to build integrations that streamline operations and reduce manual effort. By understanding the endpoints, parameters, and best practices outlined in this article, you can create robust solutions that enhance your real estate platform’s agent management capabilities.

Whether you’re building a custom agent portal, synchronizing with external HR systems, or creating automated workflows, the WPResidence API offers the flexibility and functionality needed to manage agents efficiently and effectively.

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