---
name: kimaai_lead_validate
type: filter
since: 1.6.0
tier: free
feature: lead-capture
area: leads-customer-centre
summary: Refuses a lead before it is stored, with a message the visitor sees under the form.
parameters:
  - name: valid
    type: true|WP_Error
    description: True to store the lead. A WP_Error refuses it; its message is what the visitor sees.
  - name: lead
    type: array
    description: The lead as it would be stored, which is personal data. session_id, user_id, status, email, name, phone, company, trigger_type, post_id, consent_text, consent_at and marketing_opt_in, as in kimaai_lead_saved.
  - name: request
    type: WP_REST_Request
    description: The lead form's REST request.
returns:
  type: true|WP_Error
  description: True to store the lead; anything else refuses it.
surfaces: [chatbot]
---

# kimaai_lead_validate

## When it fires

When a visitor sent the chatbot's lead form, in the request to `POST /kimaai/v1/chatbot/lead`, after the form's own checks (lead capture on, a conversation the visitor holds, at most five leads per IP address and day, a valid email address, consent given to the text the form showed) and before the lead is stored. "Not now" and a form only a bot fills in do not reach it.

Only `true` stores the lead. A `WP_Error` refuses it: the visitor sees its message under the form, with status 400, and can correct the details and send again. Nothing is stored, `kimaai_lead_saved` does not fire, and the refusal does not count towards the five leads per day. Any other answer refuses the lead too, with a general message. Return `$valid` unchanged when it is not `true`, so a refusal of an earlier callback stays.

The filter cannot change the lead, so the stored consent text stays the one the visitor agreed to. Write the message for the visitor, in the site's language, and keep the address out of logs.

## Example

```php
add_filter(
  'kimaai_lead_validate',
  function ($valid, array $lead) {
    if ($valid !== true) {
      return $valid;
    }

    // Addresses of disposable mail services: replace the list with the ones your leads come from.
    $domain = strtolower((string) substr(strrchr((string) $lead['email'], '@'), 1));
    if (in_array($domain, ['throwaway.example', 'tempmail.example'], true)) {
      return new WP_Error('my_theme_disposable_email', __('Please use an email address you read regularly.', 'my-theme'));
    }

    return $valid;
  },
  10,
  2
);
```

## Related

- `kimaai_lead_saved`: fires when a lead passed this filter and was stored.
- `kimaai_lead_free_mail_domains`: the free email domains the lead score (Pro) does not count as business addresses.
