Most home service businesses run more than one tool. The quote form lives on the website, the books live somewhere else, and the schedule lives in the field service CRM. This tutorial connects your code to that CRM with three moves: find or create the customer, add a job request, and get a webhook when the job changes.
The CRM here is Smarfle, field service software for home service businesses. Everything below uses Node 18 or newer with the built-in fetch, so there is nothing to install.
Get a key
In Smarfle, open Company Settings, then Integrations, then API keys, and press Create API key. Pick Read and write for this tutorial. Keys start with smk_, are shown once, and only ever see one business.
Every call sends the key as a bearer token:
// smarfle.mjs
const BASE = "https://www.smarfle.com/api/v1";
const headers = {
Authorization: `Bearer ${process.env.SMARFLE_KEY}`,
"Content-Type": "application/json",
};
export async function api(method, path, body) {
const res = await fetch(`${BASE}${path}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
const json = await res.json();
if (!res.ok) {
const err = new Error(`${res.status} ${json.error?.code}: ${json.error?.message}`);
err.status = res.status;
err.body = json;
throw err;
}
return json;
}
Check the connection first. GET /me returns the business behind the key:
import { api } from "./smarfle.mjs";
console.log(await api("GET", "/me"));
Find or create the customer
Look the customer up by email before creating one. If two systems race and the create still collides, the API answers 409 conflict with the existing customer's id, so you can use that instead of failing.
export async function findOrCreateCustomer({ first_name, last_name, email, phone }) {
const found = await api("GET", `/customers?email=${encodeURIComponent(email)}`);
if (found.data.length) return found.data[0];
try {
return await api("POST", "/customers", { first_name, last_name, email, phone });
} catch (e) {
if (e.status === 409 && e.body.error?.existing_id) return api("GET", `/customers/${e.body.error.existing_id}`);
throw e;
}
}
Reads are free, so looking up first costs nothing. Each call that adds or changes a record costs $0.003 from the business's Smarfle wallet.
Add a job request
A job created through the API is a request. It lands in the office's queue with the customer attached, and the office picks the time and the technician in Smarfle. That keeps your integration out of the scheduling rules (hours, crews, travel), which the office owns.
const customer = await findOrCreateCustomer({
first_name: "Morgan",
last_name: "Ellis",
email: "morgan@example.com",
phone: "202-555-0101",
});
const job = await api("POST", "/jobs", {
customer_id: customer.id,
title: "Quarterly pest service",
description: "Ants along the back door. Dog in the yard.",
preferred_date: "2026-12-02",
reference: "crm-sync-1042", // your own id, handy when you reconcile later
});
console.log(job.id, job.status); // "requested"
Page through lists
Lists return { data, has_more, next_cursor }. Pass the cursor back until has_more is false. limit goes up to 100.
let cursor = null;
const all = [];
do {
const page = await api("GET", `/customers?limit=100&updated_since=2026-11-01T00:00:00Z${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`);
all.push(...page.data);
cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
updated_since makes incremental syncs cheap: store the time of your last run and ask only for what changed.
Get told when a job changes
Polling works, but webhooks are better. Subscribe once with a public https address and the events you care about:
const hook = await api("POST", "/webhooks", {
url: "https://example.com/smarfle-webhook",
events: ["work_order.status_changed", "invoice.paid"],
});
console.log(hook.secret); // shown once, store it
Every delivery is a POST whose X-Webhook-Signature header is the hex HMAC-SHA256 of the raw body, keyed with that secret. Verify it before trusting the payload, and compare in constant time:
import crypto from "node:crypto";
import http from "node:http";
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const expected = crypto.createHmac("sha256", process.env.SMARFLE_WEBHOOK_SECRET).update(raw).digest("hex");
const got = Buffer.from(String(req.headers["x-webhook-signature"] || ""));
const ok = got.length === expected.length && crypto.timingSafeEqual(got, Buffer.from(expected));
if (!ok) return res.writeHead(401).end();
const payload = JSON.parse(raw); // { event, timestamp, data }
console.log(payload.event, payload.data?.id);
res.writeHead(200).end();
});
}).listen(3000);
Read the body as raw bytes. Parsing JSON first and stringifying it again changes the bytes, and the signature will never match.
What the office sees
The request shows up next to the business's calls and online bookings, ready to schedule. This short video shows the booking side of the same flow:
If the business still keeps jobs in a spreadsheet while you build this, the free job tracker template for Google Sheets uses the same fields, which makes the import later painless.
Limits worth knowing
Each key gets 120 calls a minute. Errors always come back as { "error": { "code", "message" } }, with 403 forbidden for a read-only key trying to write and 429 rate_limited when you go too fast. The full reference and an OpenAPI file live at smarfle.com/docs/api, and runnable examples are in the smarfle-lead-api repo.
Top comments (0)