DEV Community

Smarfle Team for Smarfle

Posted on

Send website form leads into a field service CRM with one webhook

If you build sites for plumbers, cleaners or pest control companies, the contact form is the part the owner cares about most. Each form entry is a job they could win. Too often that entry lands in an inbox nobody checks on a busy day, and the lead goes cold.

This tutorial sends every form entry straight into the business's CRM as a new lead, so the office sees it next to their calls, bookings and jobs. The CRM here is Smarfle, field service software for home service businesses, but the pattern (a server route that forwards a form with a private key) works for any CRM with a lead webhook.

What you need

  • Node 18 or newer (it has fetch built in)
  • A Smarfle API key. In Smarfle, open Company Settings, then Integrations, find API key and press Generate API Key. Keys start with rk_.
  • A contact form on the site

Keep the key on the server

Never put the API key in front-end JavaScript. Anyone can open the browser tools and copy it. The form posts to your own server, and your server adds the key.

<form method="POST" action="/contact">
  <input name="first_name" placeholder="First name" required>
  <input name="last_name" placeholder="Last name" required>
  <input name="email" type="email" placeholder="Email">
  <input name="phone" type="tel" placeholder="Phone">
  <input name="address" placeholder="Service address">
  <textarea name="message" placeholder="What do you need done?"></textarea>
  <label>
    <input type="checkbox" name="sms_consent" value="yes">
    Text me about this request. Message and data rates may apply. Reply STOP to opt out.
  </label>
  <button>Send</button>
</form>
Enter fullscreen mode Exit fullscreen mode

The server route

This uses Express to keep it short. The same logic works in a Next.js route handler, a Cloudflare Worker or a WordPress wp_remote_post call.

// server.mjs: SMARFLE_API_KEY=rk_... node server.mjs
import express from "express";

const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/contact", async (req, res) => {
  const f = req.body;
  const lead = {
    first_name: (f.first_name || "").trim(),
    last_name: (f.last_name || "").trim(),
    email: f.email || undefined,
    phone: f.phone || undefined,
    address: f.address || undefined, // one line, split into street, city, state and ZIP for you
    message: f.message || undefined,
    source_page: req.get("referer"),
    sms_consent: f.sms_consent === "yes",
    sms_consent_source: f.sms_consent === "yes" ? "Website contact form checkbox" : undefined,
  };

  const r = await fetch("https://www.smarfle.com/api/webhook/leads", {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-key": process.env.SMARFLE_API_KEY },
    body: JSON.stringify(lead),
  });
  const body = await r.json().catch(() => ({}));

  if (r.ok || r.status === 409) {
    // 409 means a client with this email already exists. The request is still saved on that client.
    return res.redirect("/thanks");
  }
  if (r.status === 429) return res.status(503).send("Busy for a moment, please try again.");
  console.error("Lead failed", r.status, body);
  res.status(500).send("Something went wrong. Please call us instead.");
});

app.listen(3000);
Enter fullscreen mode Exit fullscreen mode

A few details matter here.

Duplicates are not errors. When someone fills in the form twice, or an existing customer asks for a second job, the API answers 409 with the existing client_id and request_saved: true. Treat it as success, because the office still sees the new request on that customer.

Text consent is opt in. Leads arrive with sms_consent: false unless you send true, and the CRM will not text a lead without it. Only send true when the form showed a clear consent line and the person ticked it, and describe where it came from in sms_consent_source. That record is what protects the business if anyone asks later.

Rate limits are per address. More than 20 requests a minute from one IP gets a 429. A real contact form never gets near that, but a bot will, so keep your usual spam protection (a honeypot field or reCAPTCHA) in front of the route.

Send more than the basics

The lead body takes a few extra fields that make the office's life easier.

const lead = {
  // ...the fields above
  custom_fields: { "Home size": "3 bedrooms", "Pets": "Dog" }, // saved to the business's custom fields of the same name
  details: { "Preferred day": "Saturday morning" },            // extra lines shown with the request
  utm_source: req.query.utm_source,
  utm_campaign: req.query.utm_campaign,
};
Enter fullscreen mode Exit fullscreen mode

custom_fields fill custom fields the business already created in Smarfle. details are free-form lines shown with the request. UTM values give the owner first-touch attribution, so they can see which ads and pages bring jobs.

No server at all

Some form builders can only send to a URL and cannot add headers. For those there is a second endpoint with the key in the path, and it matches common field names (name, your-name, email, your-email, tel, message and so on) by itself.

https://www.smarfle.com/api/webhook/leads/rk_your_key
Enter fullscreen mode Exit fullscreen mode

Paste that into the webhook setting of Contact Form 7, Elementor, WPForms or Gravity Forms. The key lives in the site's settings, never in the page, so the earlier rule still holds.

Test it

curl -X POST https://www.smarfle.com/api/webhook/leads \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SMARFLE_API_KEY" \
  -d '{"first_name":"Morgan","last_name":"Ellis","email":"morgan@example.com","message":"Quote for a move-out clean"}'
Enter fullscreen mode Exit fullscreen mode

A 200 with a client_id means the lead is in. In Smarfle it shows up as a client with the status Lead, with the request at the top of the client page and an alert to the office.

What the owner sees

The lead lands in the same inbox as calls and booking requests, so nothing sits in a forgotten email folder. This two-minute video shows that side of it.

If the business is still tracking leads in a spreadsheet while you set this up, this free lead tracker template for Google Sheets has the same columns the webhook fills, which makes the move later easy.

Cost and limits

Each lead sent counts as one API call, at $0.003 from the business's Smarfle wallet. The examples in this post, plus Python, PHP and Zapier versions, are in the smarfle-lead-api repo.

Top comments (0)