# EspoCRM Lead Capture

**Requires Elementor Pro** — this adds a submit action to Elementor Pro's Forms widget, so it only appears if Elementor Pro's Forms module is active.

## Where to find it

Edit any Elementor Form widget, go to **Content → Actions After Submit**, and add **EspoCRM Webhook** to the list of actions. A new "EspoCRM Webhook" settings section appears further down the panel once it's added.

## Setting it up

1. In EspoCRM, create (or open) a **Lead Capture** entry point and copy its webhook URL.
2. Paste that URL into **Webhook URL** on the form action.
3. Tell it which fields to send — see **Field mapping** below.
4. Save and test with a real submission, checking that the lead appears correctly in EspoCRM.

## Settings

| Setting | Default | What it does |
|---|---|---|
| **Webhook URL** | Empty | Your EspoCRM Lead Capture endpoint. Required — the form shows an error to the visitor if this is empty when they submit. |
| **EspoCRM Payload Example** | Empty | Paste an example payload copied from EspoCRM's Lead Capture setup here — see below. |
| **Or Enter Field IDs Manually** | Empty | A comma-separated list of field IDs to send, as an alternative to pasting a payload. |
| **Format Phone Numbers** | On | Automatically reformats UK phone numbers to `+44 #### ######` before sending. |
| **Enable Debug Logging** | Off | Logs each submission's request and response to your site's debug log — see the warning below before using this on a live site. |

## Field mapping

This integration works by matching each Elementor form field's **ID** directly against the field name EspoCRM expects — there's no visual field-mapping screen, so the IDs need to line up.

**The easiest way:** copy an example payload from your EspoCRM Lead Capture setup (it looks like `{"firstName": "...", "lastName": "...", "emailAddress": "..."}`) and paste it into **EspoCRM Payload Example**. The field names are extracted automatically — you don't need to type them out separately.

**Alternative:** if you don't have an example payload handy, list the field IDs you want sent, comma-separated, in **Or Enter Field IDs Manually** (e.g. `firstName, lastName, emailAddress`).

**If both are left empty**, every field on the form is sent (except Elementor's own internal fields — acceptance checkboxes, terms, reCAPTCHA, honeypot, which are always excluded automatically).

Either way, each Elementor form field's **ID** must match the corresponding EspoCRM field name exactly. To check or change a field's ID: select the field in the form editor → **Advanced** tab → **ID**.

## Phone number formatting

When **Format Phone Numbers** is on, any field whose ID contains "phone" is reformatted to `+44 #### ######` before sending — handling common UK input styles (a leading `0`, `+44`, or `0044`) automatically. If a number doesn't look like a valid 10-digit UK number after cleanup, it's sent as originally entered rather than a mangled result. This formatting is UK-specific; international numbers are passed through unchanged.

## ⚠ Before enabling debug logging

Debug logging writes each submission's field values — potentially including names, emails, and phone numbers — to your site's debug log file. Only enable this temporarily while troubleshooting a specific issue, and turn it off again afterward. Debug logs aren't intended to store personal data long-term, and depending on your hosting, the log file may be more widely accessible than your database.

## What visitors see if something goes wrong

If the webhook URL is missing, unreachable, or EspoCRM returns an error, the visitor sees a generic error message on the form rather than technical details — enable debug logging temporarily to see exactly what EspoCRM returned.

## Good to know

- **Checkbox/toggle-style fields** are converted to `0`/`1` automatically, matching EspoCRM's expected boolean format.
- **Multi-select or checkbox-group fields** are sent as a single comma-separated string.
- **Empty fields are omitted** from the payload entirely rather than sent as blank values.