WP AgentBox Sync Documentation

Connect AgentBox to WordPress, choose which listings to import, and keep them current with manual sync, scheduled jobs and signed webhooks. This guide also covers listing locks, agent records, enquiries and developer customisation.

Guide version: reviewed against the WP AgentBox Sync 1.4.9 interface on 7 October 2026. Older installations may show different controls. Check your installed version under Plugins and contact support if a setting described here is missing.

WP AgentBox Sync supplies structured WordPress data. Your theme controls the public website. WP Listed provides a compatible presentation layer; a custom theme can also use the synced data.

On this page

• Install and connect
• Choose filters and save sync configurations
• Run and monitor a sync
• Schedule automatic sync
• Set up signed webhooks
• Manage listings, locks and removals
• Images, titles, URLs and agents
• Send enquiries to AgentBox
• Licence status and recovery
• Fields and theme templates
• Troubleshooting and support

1. Install and connect

Before you start

• An AgentBox account with API access, plus the API Key and Client ID supplied by AgentBox. Your Digital Apps licence key is separate from these credentials.
• The WP AgentBox Sync ZIP and your Digital Apps purchase email and licence key.
• WordPress administrator access and a recent backup of your database and uploads. Use a staging site to test changes to an existing integration.
• Confirmation from AgentBox of any IP allowlisting required for your account. If required, provide the web server’s outbound public IP, including the staging server when testing.

Hosting checklist

• Allow outbound HTTPS requests to AgentBox and the Digital Apps licensing and update services.
• Keep WordPress REST requests and loopback requests available. Security rules must allow the specific authenticated integration endpoints.
• Provide a reliable WordPress cron runner. Low-traffic websites should use a server cron or the plugin’s external heartbeat.
• Provide writable uploads storage and sufficient disk space if you enable local image storage.
• Signed webhooks and signed licence checks need working cryptographic verification. Ask your host to check PHP Sodium support if diagnostics report it missing. Confirm WordPress and PHP compatibility for the package you install with Digital Apps.

Install the plugin

1. Download your authorised plugin ZIP from your Digital Apps account or purchase delivery.
2. In WordPress, open Plugins → Add Plugin → Upload Plugin, select the ZIP, install it and activate it.
3. Open WP Agentbox Sync in the WordPress admin menu. Configure credentials and filters before starting your first import.

Verify your Digital Apps licence

1. Open the License tab.
2. Enter your purchase email in Licence email and your key in Licence key.
3. Select Verify and save licence and review the status message. Saved credentials remain hidden; blank credential fields do not mean the saved licence was removed.
4. If the website is already registered to a different licence or its domain has changed, contact support to arrange the change.

Connect AgentBox and find the controls

In API Details, enter the AgentBox API Key and Client ID, then select Submit. These credentials connect to your CRM; licence verification alone does not connect AgentBox.

• Sync: start imports, inspect progress and review cron jobs.
• Filters: choose listing criteria and manage named Sync Configs.
• Settings: configure images, titles, agents, schedules, notifications, webhooks and heartbeat.
• API Details: save AgentBox credentials.
• License: verify access and review subscription status.
• Diagnostics: investigate API, cron, sync and logging issues.

2. Choose filters and save sync configurations

Filters define which source listings your website should contain. Review them carefully before importing or narrowing an existing feed. Changing eligibility can affect both new imports and the cleanup of existing unlocked listings.

1. Open Filters and select Type, Status, Marketing Status, Property Type and Property Category. Review Include Hidden Listings explicitly.
2. Use Agent/Member IDs, inspection dates, created dates or modified dates only when you need that narrower scope. A Fixed Date is a specific boundary; a Trailing Range moves with time.
3. Choose a Batch Size appropriate to your host. Smaller batches can help when image downloads or API responses make processing slow.
4. Select Save and review the returned listing count. An unexpected zero should be investigated before running the import.
5. Under Sync Configs, enter a descriptive Config Name and select Save Current Filters. For example, keep active sales and active rentals as separate named configurations.
6. To change a saved configuration, use its Edit action, adjust the filters, then select Update Sync Config. Saving the general filters alone is not the same as updating an existing named configuration.

The default filters are not an instruction to import every property. Check sale versus lease, available versus sold or leased, and hidden-listing rules against the intended website content. Listings without images are still eligible for sync.

3. Run and monitor a sync

1. Open Sync. Select Sync All to run saved configurations sequentially, or Sync [configuration name] to run one.
2. Watch the progress and result messages. The import runs in background batches and does not require you to keep the dashboard open, provided cron is working.
3. After completion, open Listings in WordPress. Check representative listings for status, address, price, images, agents and inspection times, then inspect their public pages.
4. To refresh one existing listing, open its editor and use the listing’s Sync control. Check its Sync Lock before expecting changes.

If progress stops, inspect cron and diagnostics first. Manual Next Page is a recovery control with a one-minute cooldown. Cancel stops further processing; it does not roll back changes already applied. Avoid starting repeated imports while a job is active.

4. Schedule automatic sync

1. Check the WordPress timezone under Settings → General.
2. In the plugin’s Settings → Sync Schedule, turn on Enable Automatic Sync.
3. Enable the morning, afternoon and evening slots you need, set their times and select Save.
4. Check the scheduled jobs and subsequent completed runs in Sync or Diagnostics. A configured time alone does not prove the job has run.

WordPress cron needs a runner to process due events. For an external runner, use the Heartbeat URL shown under Settings → External Cron Heartbeat and configure your trusted scheduler to call it every minute. This processes due cron work; it does not mean a full listing import runs every minute.

Treat the heartbeat URL and Path Key as credentials. Regenerate Path Key invalidates the previous URL immediately, so update the external scheduler after rotation. Turning off automatic scheduled sync does not disable independently configured webhooks.

5. Set up signed webhooks

Webhooks let AgentBox notify WordPress about listing changes between scheduled imports. They require a publicly reachable callback and AgentBox signing support. Keep scheduled sync available as a fallback.

1. Open Settings → Agentbox Webhooks and review the site’s Webhook Callback URL.
2. Select Enable Webhooks. The plugin provisions this site’s subscriptions and checks signing keys.
3. Use Refresh Status to inspect setup progress, signing keys and any missing events or errors.
4. Pending setup retries through cron. The interface limits setup to ten checks or fifteen minutes. If checks become overdue, investigate cron; use Cancel Setup when appropriate.
5. Confirm an eligible listing change reaches WordPress and review its processing result. Use Disable Webhooks when retiring the integration on that site.

The plugin verifies Ed25519 signatures and rejects invalid deliveries. If the AgentBox account cannot provide signing support, webhooks remain disabled and scheduled sync is the fallback. Do not disable signature checks to make a test pass.

6. Manage listings, locks and removals

AgentBox is the source of truth for synced listings. WordPress holds a display copy identified by the external listing ID. Editing imported values in WordPress does not write those changes back to AgentBox, and a later sync can overwrite unlocked values.

Protect a listing with Sync Lock

1. Open the listing in WordPress.
2. In Listing Meta, enable Sync Lock.
3. Update the post to save the lock. The stored value is sync_lock = on.
4. Remove the lock and save when you want the listing to follow AgentBox again.

A locked listing is protected from sync updates and automated cleanup. It can therefore remain visible with outdated availability or price. Review locked listings regularly; making a manual edit alone does not enable the lock.

Understand automatic removal

Confirmed removal or filter exclusion can permanently delete an unlocked synced listing. It is not moved to Trash. Normal updates modify active listings in place. Temporary API failures, incomplete responses and partial runs are not proof that a listing was removed.

If a removed listing becomes eligible again, it can be imported from fresh source data. Do not rely on its old WordPress post ID or local-only metadata being restored. Keep backups and review filter changes before running them. Licence expiry must not delete or unpublish your existing website content.

7. Images, titles, URLs and agents

Image storage

Under Settings → Images, enable Store Images Locally to download listing images into WordPress. With the setting off, the plugin uses external image URLs supplied by AgentBox. Check storage capacity and frontend image output after changing this setting and syncing representative listings.

Titles and permalinks

Use Listing Title Source and Listing Permalink Template to choose the title and slug. The interface provides available tags, such as street_address, main_headline and combinations like {suburb}-{postcode}. Empty templates default to street_address.

Listing Type Labels lets you customise the sale, lease and leased labels used for taxonomy terms and URLs. Test URL changes on staging and plan redirects for existing public links. These settings are not just cosmetic text changes.

Agent data

Choose Store as Meta Fields to keep agent information with the listing, or Create Agent Post Type to maintain separate agent posts. In create mode, set a suitable Post Type Slug. Check theme support before changing an established setup.

Developers can use wpabs_get_listing_agents($listing_id) to read agents across the supported relationship and legacy metadata formats. Creating agent posts does not itself create a complete public agent-directory design.

8. Send enquiries to AgentBox

The plugin supports website enquiry delivery to AgentBox. This is a separate flow from importing listings. Your theme or form integration must supply the required contact details and the appropriate listing or enquiry context.

For Elementor Pro forms, add the Agentbox action to Actions After Submit, then configure the Agentbox Actions settings, including enquiry type and source. Verify the form integration against your installed version and test with an authorised test contact.

Enable Settings → Email Listing Agents on Enquiry if listing agents should receive a WordPress email after AgentBox accepts an enquiry. Verify CRM receipt and email delivery separately. A public form’s success message alone is not a complete end-to-end delivery check.

9. Licence status and recovery

Use the License tab to see whether the plugin currently allows syncing. Subscription checks run automatically. Under Check details, review the last check and use Check licence now when the cooldown allows another request.

• Active: the verified licence allows listing updates.
• Grace: an inactive subscription has seven days of grace from its verified inactive date. Follow the renewal deadline shown in the plugin. Updating or reinstalling does not restart grace.
• Syncing paused: when enforcement applies after any grace or advance-notice period, new listing updates and enquiry delivery to AgentBox stop. Existing content, licence settings, diagnostics and sync history remain accessible.
• Checks unavailable: a temporary verification failure is not confirmation that the subscription expired. Read the current sync status and investigate connectivity before assuming a payment problem.

Renew or restore paid access through your Digital Apps account, or contact support for a registered-licence change. After verified recovery, the background service resumes and schedules a catch-up sync. Confirm completion in sync history and test enquiry delivery again. Any advance-notice deadline shown is separate from subscription grace.

Your WordPress automatic-update preference is preserved. Publishing a plugin update does not install it on websites where automatic updates are disabled.

10. Fields and theme templates

Keep custom code in a site-specific plugin or child theme and test it on staging. Do not edit the WP AgentBox Sync plugin directly, because updates replace its files. The examples below use hooks present in the reviewed implementation.

Add a simple editable field

Use wpabs_meta_fields to add the field definition and wpabs_meta_fields_whitelist to allow the standard admin saver to store it. The field definition is an item with an id; it is not an associative entry keyed by the field name.

add_filter('wpabs_meta_fields', function ($fields) {
    $fields[] = array(
        'id'    => 'agency_note',
        'label' => 'Agency note',
        'type'  => 'text',
    );
    return $fields;
});

add_filter('wpabs_meta_fields_whitelist', function ($fields) {
    $fields[] = 'agency_note';
    return $fields;
});

This creates a manually editable text field. It does not fetch a new AgentBox field or map API data automatically. Complex fields such as galleries and nested inspection arrays need dedicated handling rather than the simple text-field whitelist.

Transform values already mapped by the sync

The wpabs_wp_update_post_args filter receives one argument: the prepared WordPress post arguments. Use it to transform mapped values. It does not supply the full raw AgentBox response as a second argument. For example, this creates a separate metadata value from the already mapped headline:

add_filter('wpabs_wp_update_post_args', function ($args) {
    if (isset($args['meta_input']['mainHeadline'])) {
        $args['meta_input']['agency_headline'] = sanitize_text_field(
            $args['meta_input']['mainHeadline']
        );
    }
    return $args;
});

The old placeholder hooks your_plugin_listing_fields, your_plugin_listing_whitelist and your_plugin_agentbox_mapping are not plugin APIs. New upstream fields that are absent from the prepared arguments require a reviewed integration change.

Create a listing template

The plugin already registers the listing post type. In a classic PHP child theme, put single-listing.php in the theme root for individual listings, and archive-listing.php in the theme root for their archive. These follow WordPress template hierarchy; they do not need a Template Name header or selection through Page Attributes. Block themes use their own template system.

Read known metadata with get_post_meta() and escape it for its output context. For example, inside the listing loop:

$headline = get_post_meta(get_the_ID(), 'mainHeadline', true);
if (is_string($headline) && $headline !== '') {
    echo '<p>' . esc_html($headline) . '</p>';
}

Override plugin template parts

Plugin parts use a different path from full single templates. For example, copy wp-agentbox-sync/templates/price/price.php to your-child-theme/templates/price/price.php. In your listing template, call the helper where the price should appear:

if (function_exists('wpabs_get_template_part')) {
    wpabs_get_template_part('price');
}

The helper checks templates/{name}/{name}.php in the theme before using the plugin’s matching part. Available parts include price, attributes, inspections, slider, agents, features and tabs. An override is used only where the theme calls the helper. Review your overrides after plugin updates.

XML/REAXML ingestion and Houzez target profiles are separate integration paths. Confirm the compatible package and mapping with Digital Apps before using this native AgentBox API guide for those setups.

11. Troubleshooting and support

Licence verification fails

Check the purchase email, key and registered website domain, then inspect the License status. If checks are unavailable, confirm outbound HTTPS and server time with your host. Use Check licence now after its cooldown. Do not repeatedly reinstall the plugin or replace registered credentials to try to reset grace.

No listings arrive, or progress stops

• Verify AgentBox credentials and account API access. Confirm outbound IP allowlisting when required.
• Review all filters and saved configurations, especially Type, Status, hidden listings, date boundaries and Agent/Member IDs. Compare the returned count with your expectation.
• Check for an active run, overdue cron work or a paused licence. Confirm that the external runner still uses the current heartbeat URL.
• Inspect the affected listing’s Sync Lock and external Agent Box ID.
• For slow processing, try a smaller batch size and check host limits and image-download failures. Use recovery controls only after identifying the cause.

Data exists but the public page is wrong

Compare the stored listing with AgentBox first, then inspect your theme template and image-storage mode. Clear relevant page or object caches after confirming the sync succeeded. For 404s after a route change, review the theme’s archive and permalink configuration; saving WordPress Permalinks can refresh rewrite rules. Plan redirects if URLs changed.

Failure notifications and diagnostics

In Settings, enable Email Notifications on Sync Failure, enter a Notification Email and save. Verify WordPress mail delivery. In Diagnostics, review sync, API and cron information. Keep any diagnostic logging window limited, and remove credentials or personal information from material you share.

Contact Digital Apps

Use Premium Support for help with your installation. Include the site URL, plugin/WordPress/PHP versions, affected listing ID, configuration name, last successful sync time, exact error and steps to reproduce. For API access or account allowlisting, contact AgentBox.

Do not include API keys, licence keys, heartbeat URLs, passwords or unredacted customer enquiry data in a public support request. For implementation or compatibility planning, contact Digital Apps.