Lead Storage And Processing

This document describes how the ADP Car Market Hub plugin captures contact-form and test-drive submissions, where they are stored, how their workflow status is managed and which automated emails are sent.

When to use this document

Read this document if you need to:

• Understand the schema and life cycle of a lead generated by the plugin's contact form.
• Map lead data to an external CRM via the leads admin screen or the _as24ci_lead_* post-meta fields.
• Diagnose missing notifications or stuck workflow statuses.
• Migrate leads between environments.

For inbound REST/AJAX endpoints, see REST API Endpoints and AJAX Actions. For outbound notifications, see Webhooks.

Overview

Leads are stored as posts of the custom post type as24ci_lead, implemented in AS24CI\Leads_CPT. The CPT is registered as public => false, show_ui => false and show_in_rest => false, so it is not exposed to the front-end or to the WordPress REST API. The admin Leads tab provides a custom list table for viewing, searching, status changes and deletion.

Each submission flows through the contact form (AS24CI\Contact_Form), which:

1. Validates and sanitises the form input.
2. Sends the dealer notification email and the customer confirmation email (using either the configured custom templates or the built-in defaults).
3. Calls Leads_CPT::save_lead() to persist a new lead record.
4. Records a lead_sent analytics event when a vehicle ID is present.

Lead post fields

Leads_CPT::save_lead() writes the following meta keys:

The post_title is set to the contact name and post_status is publish.

Status workflow

Leads_CPT defines four workflow statuses:

get_lead_status() returns the stored status, defaulting to new when the meta is missing or unrecognised. update_lead_status() rejects unknown values.

The admin status-change action is exposed via the AJAX handler as24ci_update_lead_status (capability: manage_as24_imports, nonce: as24ci_update_lead_status).

Step by step instructions

To review and process a lead:

1. Open the Leads admin tab.
2. Use the search box to filter by name, email, listing ID or vehicle title (server-side LIKE matching against the corresponding meta keys).
3. Use the status dropdown to filter by new, contacted, closed or spam.
4. Open a lead to view its details, then change the status as the workflow progresses.
5. Use the delete action to remove a lead permanently. The record is removed via wp_delete_post( $id, true ); there is no trash step for as24ci_lead.

Email behavior

Two emails are sent per submission:

• Dealer notification — sent to the address configured in as24ci_lead_recipient_email. Uses HTML and includes the vehicle, customer and message details. A custom template can be configured via the Leads admin settings.
• Customer confirmation — sent to the visitor's email address. Has separate templates for standard inquiries and test-drive bookings, and supports a custom template stored in the option as24ci_lead_email_template_customer.

Both emails use wp_mail(). The _as24ci_lead_email_sent meta records whether both messages were dispatched successfully (the wp_mail() boolean return values are AND-combined).

Configuration reference

Additional templating options for the dealer-side email may be exposed in the Leads admin tab. Verify the exact list against the current plugin version before publishing customer-facing copy.

Operational notes

• The CPT is intentionally not exposed in the REST API or the block editor; treat the WP admin Leads tab as the single user interface.
• wp_count_posts( 'as24ci_lead' ) is used by the dashboard widget to display the total lead count.
• Leads are written from the same HTTP request that processed the form submission. A failed wp_mail() does not prevent the lead from being stored; the _as24ci_lead_email_sent flag reflects only the email status.
• The lead_sent analytics event is only recorded when a valid vehicle_id is present in the submission.
• Webhook integration: an outbound new_lead webhook is wired up internally on the as24ci_lead_saved action. Verify in the current plugin version whether this action is dispatched at lead-save time before relying on it for production integrations.

Troubleshooting

• Lead is saved but no emails arrive — check the _as24ci_lead_email_sent meta. If it is 0, wp_mail() failed. Verify SMTP/mailer configuration and the recipient address.
• Test-drive lead has no appointment date — the appointment is only stored when the input matches Y-m-d H:i or Y-m-d and represents a real calendar date. Mistyped dates are silently dropped to keep the lead record consistent.
• Status changes are reverted on reload — confirm the AJAX status update returned success. A 403 indicates the user lacks manage_as24_imports; a 400/Invalid parameters means the lead ID or status was missing or invalid.
• Search returns no results despite matching content — searches use LIKE against four specific meta keys. Search terms that only appear in the message body are not indexed.
• Lead totals on the dashboard widget look wrong — the count is based on publish status only. Spam-marked leads remain publish but with _as24ci_lead_status = spam.

Related documents

• Custom Post Types And Taxonomies
• Webhooks
• AJAX Actions
• Analytics Tracking
• Options And Settings Storage
• Security And Capabilities