JPFLD API

Base URL

https://jpfld.com/api/v1

curl

curl "https://jpfld.com/api/v1/leads?limit=50&updated_since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $JPFLD_API_KEY"

JavaScript

// Node 18+ / Deno / Bun: page through every client.
const key = process.env.JPFLD_API_KEY;
let offset = 0;
for (;;) {
  const res = await fetch(`https://jpfld.com/api/v1/clients?limit=100&offset=${offset}`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  if (res.status === 429) {
    await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 1) * 1000));
    continue;
  }
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  for (const client of body.data) console.log(client.id, client.name);
  if (body.pagination.next_offset === null) break;
  offset = body.pagination.next_offset;
}

Response

{
  "data": [ { "id": "…", "name": "Jane Doe", "status": "new", "created_at": "…", "updated_at": "…" } ],
  "pagination": { "limit": 50, "offset": 0, "has_more": true, "next_offset": 50 }
}

curl: create a lead

curl -X POST "https://jpfld.com/api/v1/leads" \
  -H "Authorization: Bearer $JPFLD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9d2c1e-3b8a-4d55-9b1e-1c2d3e4f5a6b" \
  -d '{
    "name": "Jane Doe",
    "phone": "+1 832 555 0100",
    "email": "jane@example.com",
    "service": "Roof repair",
    "address": "123 Main St, Houston TX 77002",
    "message": "Leak over the garage",
    "source": "Website form",
    "external_id": "form-48213"
  }'

JavaScript: schedule a job

import { randomUUID } from "node:crypto";

// One key per record you mean to create - reuse it on every retry of it.
const idempotencyKey = randomUUID();
const res = await fetch("https://jpfld.com/api/v1/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JPFLD_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    title: "Roof inspection",
    client_name: "Jane Doe",
    scheduled_date: "2026-11-03",
    start_time: "08:00",
    end_time: "10:00",
    address: "123 Main St, Houston TX",
    budget: 450,
  }),
});
const body = await res.json(); // 201 { data: { id, title, ... } }
console.log(res.headers.get("Idempotent-Replayed") === "true" ? "replayed" : "created", body.data?.id);

curl: update a client

curl -X PATCH "https://jpfld.com/api/v1/clients/6f1c0c1e-..." \
  -H "Authorization: Bearer $JPFLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+18325550199", "notes": "Gate code 4411" }'

Error body

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields aren't valid.",
    "details": [ { "field": "scheduled_date", "message": "scheduled_date must be YYYY-MM-DD." } ]
  }
}

Example delivery

POST https://your-app.example.com/jpfld-webhook
Content-Type: application/json
X-JPFLD-Webhook-Event: lead.created
X-JPFLD-Webhook-Delivery: 1b9d6bcd-…
X-JPFLD-Webhook-Timestamp: 1793011200
X-JPFLD-Webhook-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_9f2c…",
  "type": "lead.created",
  "created_at": "2026-10-26T15:20:00.000Z",
  "api_version": "v1",
  "data": { "id": "…", "name": "Jane Doe", "phone": "+18325550100", "status": "new", … }
}

Node.js

// Node.js / Express - verify before trusting the body.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.JPFLD_WEBHOOK_SECRET; // whsec_...

app.post("/jpfld-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-JPFLD-Webhook-Timestamp") ?? "";
  const signature = req.get("X-JPFLD-Webhook-Signature") ?? "";
  const raw = req.body.toString("utf8"); // the exact bytes received

  // 1. Reject old or future timestamps (replay protection, 5 minutes).
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400);

  // 2. HMAC-SHA256 of "<timestamp>.<raw body>" with your signing secret.
  const expected = "v1=" + crypto.createHmac("sha256", SECRET).update(timestamp + "." + raw).digest("hex");
  const ok = signature.split(",").some((s) => {
    const a = Buffer.from(s.trim());
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(raw);
  // 3. Deliveries can repeat - skip event.id values you've already handled.
  console.log(event.type, event.data.id);
  res.sendStatus(200); // any 2xx within 10 seconds counts as delivered
});

Python

# Python / Flask
import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["JPFLD_WEBHOOK_SECRET"].encode()

@app.post("/jpfld-webhook")
def jpfld_webhook():
    ts = request.headers.get("X-JPFLD-Webhook-Timestamp", "")
    sig = request.headers.get("X-JPFLD-Webhook-Signature", "")
    raw = request.get_data()  # raw bytes
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(400)
    expected = "v1=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not any(hmac.compare_digest(s.strip(), expected) for s in sig.split(",")):
        abort(401)
    event = request.get_json()
    return "", 200