EspoCRM Lead capture and Preflight Checks.

Circles And Lambdas — Mon, 11 May 2026 15:36:50 +0000

Last week as I was trying to integrate EspoCRM's lead capture form with my website, I ran into a peculiar issue. Every time I would try to submit a form, whether filled or not, it wouldn't go through to my CRM. I kept getting a CORS Policy Error: My domain wasn't matching something called Access-Control-Allow-Origin.

In my years of development, I was abstracted from CORS issues by frameworks and now it had caught up to me. Trying to diagnose the problem led me deeper and deeper into something I wasn't familiar with.

Here is how I manage to get my CRM and my website to communicate with each other.

In EspoCRM, there is a way to capture leads through an HTML form and have potential leads logged into the system. It uses an API token to identify the source of the lead and who is the owner once a lead fills the form. Once a web lead capture API is created, a link is created and it will be used for the connection and capture.
EspoCRM, to their credit, also provides a composer package that handles the form submission. I however opted for the JavaScript fetch option as it was more flexible for my project and way efficient to implement.

I created the API link, created the web form and wrote the JavaScript lines to send the data.

JavaScript
const webToLeadFormElement = document.getElementById("lead_capture");
    let isSubmitting = false;

    webToLeadFormElement.addEventListener("submit", (e) => {
        e.preventDefault();

        if (isSubmitting) return;

        const formData = new FormData(webToLeadFormElement);
        const data = Object.fromEntries(formData.entries());

        const hasEmpty = Object.entries(data).some(([k, v]) => k !== "website" && !v.trim());
        if (hasEmpty) {
            showError("Please fill in all fields before submitting.");
            return;
        }

        isSubmitting = true;
        setButtonState("loading");
        submitLead(data);
    });

    const submitLead = async (data) => {
        const url = "API_LINK";
        try {
            const response = await fetch(url, {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                },
                body: JSON.stringify(data)
            });

            if (response.ok) {
                setButtonState("success");
                webToLeadFormElement.reset();
            } else {
                showError("Something went wrong. Please try again.");
                setButtonState("idle");
            }
        } catch (error) {
            console.error("Capture failed:", error);
            showError("Network error. Please check your connection.");
            setButtonState("idle");
        } finally {
            isSubmitting = false;
        }
    };

All was LGTM until I hit the send Inquiry button.
Instead of a submitted form, nothing happened. The test data remained as it was. A process that I thought would be seamless and straight forward suddenly became not. As an experienced console.log() tester, I immediately went to the console to see what was up on that side. That is when I saw the following message:

Console Log
    Submitting: {firstName: '', lastName: '', email: '', phoneNumber: '', inquiry: '', …}
    index.html:1 Access to fetch at 'http://localhost/espocrm/api/v1/LeadCapture/9dfb865ed229b56b2c053b27409ba6e8' from origin 'http://127.0.0.1:5500' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
    index.html:567  POST http://localhost/espocrm/api/v1/LeadCapture/9dfb865ed229b56b2c053b27409ba6e8 net::ERR_FAILED
    submitLead @ index.html:567
    (anonymous) @ index.html:560Understand this error
    index.html:580 Capture failed: TypeError: Failed to fetch
        at submitLead (index.html:567:36)
        at HTMLFormElement.<anonymous> (index.html:560:9)

My first thought was I was missing some headers on my JS fetch call, so I added Access-Control-Allow-Origin: * as part of the headers, but the same error persisited. My forms were not submitting. I decided to go look for some other unfortunate developer with the same predicament as I had on the internet. Turns out there are request headers and response headers. Request Headers are sent by the browser, and Response headers MUST be sent by the server. I seem to forgot the back part in the back and forth of the Server-Client relationship.

I came across an EspoCRM forum talking about the exact issue I had, and I was ready to hit the classic ctrl+c, ctrl+v move. My hopes were tested again, I did not find a code block to copy or any lines to paste. The only thing of use was a github issue link that discussed the problem. Following through the GitHub issue, A solution was proposed that included pasting a line, 'leadCaptureAllowOrigin' => '*' into data\config.php file, assuming it would allow the Access-Control-Allow-Origin header to be "*".

I followed the official workaround, cleared my cache, rebuilt my backend and went to test my patch. Still the same issue arose: No 'Access-Control-Allow-Origin' header is present on the requested resource. It was at this point that I was getting a bit worried of the whole lead capture idea.

Frustrated, I copied the entire JS code, along with the error, and went crying to mother Claude.

She was fortunate to hear my problems, and suggested I attempt to access a section that was not existent in my CRM, or I could use the official workaround leadCaptureAllowOrigin and a third, more precise and elaborate idea of reconfiguring my .htaccess file. I had never touched the file in all my life, as my years of programming did not direct me to that file once. This made me a bit cautious, I did not want to take part in a all night diagnosis of a failed server.

CORS or Cross Origin Resource Sharing is an HTTP-header based browser security mechanism that allows a server to indicate any origins(domain, scheme, or port) other than it own from which a browser should permit loading resources. The browser enforces this, it checks whether the server's response includes permission for the requesting origin before allowing the request to go through.

From my understanding though, my website was not allowed to POST formData because it wasn't on the server's list. The leadCaptureAllowOrigin line was incharge of telling the EspoCRM to allow all sites to send data to it.

Claude suggested I reconfigure the file to include these lines into the .htaccess file in the server:

    Header always set Access-Control-Allow-Origin "MY_WEBSITE_LINK"
    Header always set Access-Control-Allow-Methods "GET, POST, OPTIONS"
    Header always set Access-Control-Allow-Headers "Content-Type, Authorization"

    RewriteEngine On
    RewriteCond %{REQUEST_METHOD} OPTIONS
    RewriteRule ^(.*)$ - [R=204,L]

I sort of understood the First three lines, but now the .htaccess directives is where I was getting lost. The third one specifically was where I was getting no connection to it, so I went runnin' for answers.

Browser sends an OPTIONS request to the server, server matches ^(.*)$ to the API_LINK, R=204 tells Apache when the method is OPTIONS, return a 204 No Content Response immediately, - means don't rewrite the URL, R=204 sets the status Code and L stops further rewrite processing.

Now this is the preflight check, that happens before the actual POST request, it ensures security by asking the server for permission before the actual request, according to Google.

Once I pasted the code, and restarted my server, a different error now took the throne. A win is a win.

That was indication that the code worked and the request was going through. I followed the error to EspoCRM logs and found out the code responsible for capturing the POST data from the form was appending the leadCaptureAllowOrigin value as the origin, causing the error.

    if (!$apiKey) {
        throw new BadRequest('No API key provided.');
    }

    $allowOrigin = $this->config->get('leadCaptureAllowOrigin', '*');

    // $response->setHeader('Access-Control-Allow-Origin', $allowOrigin);

    $this->getCaptureService()->capture($apiKey, $data);

    return true;

I commented out the assignment code, restarted my server, and rebuilt my backend. And Voila, the Leads were posting on my backend, hours of debugging, lots of syndromes, and Mother's help lead to it. That's what I consider a good session.

I started with a simple goal of connecting my CRM and website lead to my interest on CORS being piqued. The .htaccess file I have always avoided came to the rescue (for today).

If you are hitting the same CORS problem with EspoCRM(V 9.1.8) Web Lead Capture, here's the TLDR:

1.Don't add CORS headers to your JavaScript fetch call - Not how it works.
2.The leadCaptureAllowOrigin in config.php doesnt work.
3.Handle the OPTIONS preflight in .htaccess and set the CORS headers there - That's where they belong.

Let me settle down and learn what is .htaccess, I need more niche developer points. God knows there are few going around this days.

DEV Community: Circles And Lambdas

EspoCRM Lead capture and Preflight Checks.