Listdom Developer API and Frontend Events Documentation

Actions and Data Collections PHP reference

Listdom Core includes a structured PHP action layer used by Data Collections and internal setup operations. It provides consistent capability checks, input validation, optional approval gating, dry-run behavior, logging, and result formatting.

Built-in actions

Action ID	Purpose	Required capability	Mutates data
`create_category`	Create, update, or reuse a Listdom taxonomy term	`manage_categories`	Yes
`create_custom_field`	Create, update, or reuse a Listdom custom field	`manage_categories`	Yes
`create_search_form`	Create, update, or reuse a search form	`manage_options`	Yes
`create_directory_page`	Create, update, or reuse a WordPress page and optionally connect it to a Listdom setting	`publish_pages`	Yes
`create_demo_listing`	Create, update, or reuse a sample listing	`edit_posts`	Yes
`audit_directory_setup`	Inspect the current directory structure and report missing setup items	`manage_options`	No

The directory audit checks configured frontend pages, search forms, directory-view shortcodes, listing categories, and payment checkout configuration. It returns a summary, findings, and a healthy or not-healthy status.

Execute an action

Call LSD_Actions::instance()->execute() with an action ID, an input array, and a context array. Preview a mutation first:

$preview = LSD_Actions::instance()->execute(
    'create_category',
    [
        'name' => 'Restaurants',
        'taxonomy' => LSD_Base::TAX_CATEGORY,
        'reuse_existing' => true,
    ],
    [
        'user_id' => get_current_user_id(),
        'source' => 'my_integration',
        'dry_run' => true,
        'require_approval' => true,
        'approved' => false,
    ]
);

A mutating action in dry-run mode resolves and validates the operation without performing the final write. After obtaining explicit approval, execute the same validated intent with dry_run set to false and approved set to true:

$result = LSD_Actions::instance()->execute(
    'create_category',
    [
        'name' => 'Restaurants',
        'taxonomy' => LSD_Base::TAX_CATEGORY,
        'reuse_existing' => true,
    ],
    [
        'user_id' => get_current_user_id(),
        'source' => 'my_integration',
        'dry_run' => false,
        'require_approval' => true,
        'approved' => true,
    ]
);

Context options

Context key	Purpose
`user_id`	User whose capabilities authorize the action
`dry_run`	Validate and resolve the operation without performing the final mutation
`approved`	Record that the caller approved a guarded mutation
`require_approval`	Block a mutating action until `approved` is true
`source`	Sanitized identifier for the caller or workflow
`request_id`	Correlation identifier; generated automatically when omitted
`blueprint_id`	Data Collection identifier used for generated-item metadata
`application_id`	Data Collection application identifier used for generated-item metadata

Approval gating is opt-in. Any integration that exposes actions to an external system should set require_approval for every mutation and must not treat a successful dry-run result as authorization to write.

Result format

Every action returns a consistent array:

[
    'success' => true,
    'action' => 'create_category',
    'code' => 'ok',
    'message' => 'Category created successfully.',
    'data' => [],
    'warnings' => [],
    'errors' => [],
    'meta' => [],
]

Check success first, then inspect code, errors, warnings, and action-specific data. Creation actions report an operation such as create, update, reuse, or blocked where applicable. A successful preview does not guarantee that Apply will succeed because permissions, content, or site state can change between calls.

Logging

The action layer logs requested, blocked, validation-failed, dry-run, completed, and failed stages. Entries include the action ID, request ID, source, user ID, dry-run status, and relevant payload. Observe log events with:

add_action('lsd_action_logged', function (array $entry) {
    // Forward selected, non-sensitive operational data to your monitoring layer.
});

Review inputs and results for personal or sensitive information before forwarding action data to an external log.

Data Collection execution model

A Data Collection converts its definition into an ordered action plan. Preview executes the plan in dry-run mode; Apply executes approved mutations and stores an application summary.

Definition group	Action
`categories`, `locations`, `labels`	`create_category`
`custom_fields`	`create_custom_field`
`search_forms`	`create_search_form`
`pages`	`create_directory_page`
`demo_listings`	`create_demo_listing`

Listdom provides these extension filters:

lsd_blueprints_registry adds or replaces registered Data Collection objects.
lsd_blueprint_definition_{id} modifies one collection’s definition.
lsd_blueprint_plan modifies the ordered action plan before preview or apply.

A custom collection must implement LSD_Blueprints_Interface, provide an ID, label, description, and definition, and ensure that every plan item maps to an action available in the action registry.

REST API overview

Listdom provides a RESTful API for developers to integrate its listing functionality into external applications and services. The API allows secure operations such as user authentication, retrieving listings, uploading images, and adding or updating listings programmatically. All requests require a valid API token, and many also require a user session token.

Main Variables

Base URL: The base endpoint for all calls is https://your-site.com/wp-json/listdom/v1/. All endpoints below are relative to this base URL.
API Token (lsd-token header) (Required): An API authentication key that must be included in the headers of every request. You can manage tokens in Listdom > Settings > API.
User Token (lsd-user header): A session token for a logged-in user, required for user-specific actions (like adding a listing). This token is obtained by calling the Login or Register endpoints.
Content Type: All requests and responses use JSON format (Content-Type: application/json), except for file uploads which use multipart/form-data.
Encoding for Credentials: For security, sensitive fields like passwords in the Login and Register endpoints must be Base64-encoded.

Authentication model

API token validation compares against configured keys from LSD_Options::api()['tokens'][*]['key'].
User token validation checks user meta lsd_token.
Login key flow uses user meta lsd_login.

Registered core routes

Route	Method(s)	Permission callback	Source
`/listdom/v1/languages`	GET	`guest`	`plugins/listdom/app/includes/api/routes.php`
`/listdom/v1/register`	POST	`guest`	same
`/listdom/v1/login`	POST	`guest`	same
`/listdom/v1/login/key`	POST	`permission`	same
`/listdom/v1/login/redirect/{key}`	GET	`__return_true`	same
`/listdom/v1/forgot`	POST	`guest`	same
`/listdom/v1/password`	POST	`permission`	same
`/listdom/v1/logout`	POST	`permission`	same
`/listdom/v1/profile`	GET / PUT	`permission`	same
`/listdom/v1/taxonomies`	GET	`guest`	same
`/listdom/v1/taxonomies/{taxonomy}`	GET	`guest`	same
`/listdom/v1/images`	POST	`[$taxonomies,'permission']` (as coded)	same
`/listdom/v1/images/{id}`	GET	guest route + numeric validator	same
`/listdom/v1/search-modules` & `/{id}`	GET	`guest`	same
`/listdom/v1/listings`	POST / PUT	`permission`	same
`/listdom/v1/listings/{id}/trash`	DELETE	`permission`	same
`/listdom/v1/listings/{id}`	GET / DELETE	`guest` / `permission`	same
`/listdom/v1/listings/{id}/contact`	POST	`guest`	same
`/listdom/v1/listings/{id}/abuse`	POST	`guest`	same
`/listdom/v1/listings/fields`	GET	`guest`	same
`/listdom/v1/listings/push`	POST	`guest`	same
`/listdom/v1/listings/{id}/map`	GET	`guest`	same
`/listdom/v1/listings/{id}/map-upsert`	GET	`permission`	same
`/listdom/v1/search/map`	GET	`guest`	same
`/listdom/v1/my-listings`	GET	`permission`	same
`/listdom/v1/search`	GET	`guest`	same
`/listdom/v1/addons`	GET	`guest`	same
`/listdom/v1/payments/stripe/webhook`	POST	`__return_true`	same

Practical endpoint guide

The Login API allows a user to authenticate and retrieve a session token.

Endpoint: POST /login
Description: Logs in a user with a username and password.
Required Headers: lsd-token (API token).
Request Body: JSON with the following fields:
- username: The user’s username or email, Base64-encoded.
- password: The user’s password, Base64-encoded.
Response: On success, returns an object with success: 1, the user’s id, and a token string. This token must be sent as the lsd-user header in subsequent requests.

This mechanism allows for seamless web authentication from an external app.

Generate Key: POST /login/key (requires lsd-token and lsd-user headers). Returns a one-time use key.
Redirect Endpoint: GET /login/redirect/{key}?redirect_url={URL}. Use this URL to log the user into the WordPress site in a browser. The key is single-use and expires after use.

Register

The Register API allows creating a new user account.

Endpoint: POST /register
Description: Registers a new user and returns a login token.
Required Headers: lsd-token.
Request Body: JSON with the following fields:
- name: (Optional) The display name of the user, Base64-encoded.
- email: The user’s email address, Base64-encoded.
- password: The user’s chosen password, Base64-encoded.
Response: On success, returns success: 1, the new user’s id, and a token. The user is effectively logged in via the API upon registration.

Languages

Retrieves active language codes if a compatible multilingual plugin (WPML, Polylang) is active.

Endpoint: GET /languages
Required Headers: lsd-token.
Response: An object containing success: 1 and a languages array of language codes (e.g., ["en", "fr"]).

Taxonomies (Categories, Locations, etc.)

These endpoints provide the terms for Listdom’s taxonomies.

Endpoint: GET /taxonomies/{taxonomy_slug}
Description: Fetches a hierarchical list of terms for a given taxonomy.
Examples:
- Listing Categories: GET /taxonomies/listdom-category
- Listing Locations: GET /taxonomies/listdom-location
- Listing Tags: GET /taxonomies/listdom-tag
- Listing Features: GET /taxonomies/listdom-feature
Required Headers: lsd-token.
Response: An array of term objects, each containing fields like id, name, slug, parent, and a childs array for sub-terms.
Query Parameters: You can refine the query with parameters like hide_empty=1 (to exclude terms with no listings) and parent={id} (to fetch only children of a specific term).

Get Listings

Search Listings

Retrieves a list of public listings with support for filtering and pagination.

Endpoint: GET /search
Required Headers: lsd-token.
Query Parameters:
- Text Search: s={keyword}
- Taxonomy Filters: listdom-category[]={id}, listdom-location[]={id}, etc.
- Ordering: orderby=title&order=ASC
- Pagination: page={number} and limit={number}
Response: An object with success: 1, a listings array, and a pagination object.

Current User’s Listings

Retrieves listings belonging to the currently authenticated user.

Endpoint: GET /my-listings
Required Headers: lsd-token and lsd-user.
Response: Returns all listings submitted by the user, regardless of status (including draft, pending, etc.).

Single Listing by ID

Retrieves the details of a specific listing.

Endpoint: GET /listings/{id}
Required Headers: lsd-token.
Response: An object with success: 1 and a listing object containing the listing’s full data. This action increments the listing’s view count.

User Profile

Get Logged-in User Information

Endpoint: GET /profile
Required Headers: lsd-token and lsd-user.
Response: An object with success: 1 and a user object containing profile data (ID, username, email, contact info, social links, roles, etc.).

Update Profile

Endpoint: PUT /profile
Required Headers: lsd-token and lsd-user.
Request Body: A JSON object with any of the profile fields you want to update (e.g., first_name, phone, description).
Response: The updated user object.

Listing Management

Get Add Listing Form Fields

Endpoint: GET /listings/fields
Description: Returns a structured JSON object detailing all available sections and fields for the “Add Listing” form. This is useful for dynamically building a submission UI.
Required Headers: lsd-token.

Upload Image

Endpoint: POST /images
Description: Uploads an image file to the WordPress media library and returns its attachment ID.
Required Headers: lsd-token and lsd-user.
Request: Must be a multipart/form-data request with the file field named image.
Response: An object containing success: 1 and an image object with the id, url, and thumbnail_url. Use this id when adding/updating listings.

Add Listing

Endpoint: POST /listings
Description: Creates a new listing.
Required Headers: lsd-token and lsd-user.
Request Body: A JSON object with listing data. At minimum, title and listing_category (a valid category ID) are required. Other fields like content, taxonomies, featured_image (using an ID from the upload endpoint), and gallery can be included.
Response: A confirmation message and the newly created listing object. The listing status will be pending or publish depending on the user’s permissions.

Update Listing

Endpoint: PUT /listings
Description: Edits an existing listing.
Required Headers: lsd-token and the lsd-user token of the listing owner or an admin.
Request Body: A JSON object containing the id of the listing to update, plus any other fields you want to change.
Response: The updated listing object.

Deleting Listings

Trash Listing: DELETE /listings/{id}/trash - Moves the listing to the trash (soft delete).
Delete Listing: DELETE /listings/{id} - Permanently deletes the listing (hard delete).
Required Headers: lsd-token and lsd-user of an authorized user.

Frontend JavaScript events

Event	Behavior	Source
`listdom:modal:opened`	Fired when `ListdomModal.open` completes.	`plugins/listdom/assets/js/core.js`
`listdom:modal:closed`	Fired when `ListdomModal.close` completes.	`plugins/listdom/assets/js/core.js`
`lsd-autocomplete-select`	Fired on autocomplete selection with selected item payload.	`plugins/listdom/assets/js/core.js`, listened in `frontend.js`
`lsd-mapsearch`	Triggered on `body` for map/search bridge payloads.	`plugins/listdom/assets/js/frontend.js`, listened in `api.js`
`listdom/preview-content`	Triggered in Elementor preview integration.	`plugins/listdom/assets/js/elementor-preview.js`

Example listener:

jQuery(document).on('listdom:modal:closed', '.lsd-cta-modal', function () {
  // Handle modal close lifecycle
});