Connect PaperForeman to your other tools
Send new leads from your website, put paid invoices in a spreadsheet, or ping your phone when an estimate is approved. Zapier and Make do it without code; this page has what a programmer needs too.
- In PaperForeman, open Settings → API & webhooks and tap Make a key (owner only). Copy it: it’s shown once.
- Paste the key into Zapier, Make or your code.
- For “when something happens”, add a webhook address on the same page (Zapier calls it a “Catch hook”).
Your key
Send it on every request as Authorization: Bearer pf_api_…. A read only key can look; a read + write key can also add leads, clients and notes. Turn a key off any time: anything using it stops at once.
curl https://usepaperforeman.com/api/v1/me \ -H "Authorization: Bearer $PAPERFOREMAN_KEY"
Read your records
Every list comes newest first, 25 at a time (up to 100 with limit). When has_more is true, ask again with cursor set to next_cursor. Money is in cents.
curl "https://usepaperforeman.com/api/v1/jobs?status=active&limit=50" \
-H "Authorization: Bearer $PAPERFOREMAN_KEY"
{
"object": "list",
"data": [ { "id": "…", "object": "job", "number": "JOB-1004", "name": "Carter basement", "status": "active", "contract_amount_cents": 4200000, … } ],
"has_more": true,
"next_cursor": "WyIyMDI2LTEx…"
}| List | One record | Filters |
|---|---|---|
| GET /api/v1/clients | GET /api/v1/clients/:id | |
| GET /api/v1/leads | GET /api/v1/leads/:id | status, source |
| GET /api/v1/jobs | GET /api/v1/jobs/:id | status, client_id |
| GET /api/v1/estimates | GET /api/v1/estimates/:id | status, job_id |
| GET /api/v1/invoices | GET /api/v1/invoices/:id | status, job_id |
| GET /api/v1/payments | GET /api/v1/payments/:id | invoice_id |
| GET /api/v1/schedule-events | GET /api/v1/schedule-events/:id | job_id, crew_id, from, to |
Add a lead, a client or a note
A lead needs a name and a phone or an email. Send an Idempotency-Key so a retry never makes the lead twice. New leads land in Leads and email you, like your website form.
curl https://usepaperforeman.com/api/v1/leads \
-H "Authorization: Bearer $PAPERFOREMAN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: form-2026-11-04-0012" \
-d '{"name":"Pat Lee","phone":"913-555-0101","email":"pat@example.com","service":"Roof replacement","source":"website","estimated_value_cents":1800000}'curl https://usepaperforeman.com/api/v1/clients -H "Authorization: Bearer $PAPERFOREMAN_KEY" -H "Content-Type: application/json" \
-d '{"name":"Greg Carter","email":"greg@example.com","phone":"913-555-0144","address":"11850 W 135th St, Overland Park, KS"}'
curl https://usepaperforeman.com/api/v1/notes -H "Authorization: Bearer $PAPERFOREMAN_KEY" -H "Content-Type: application/json" \
-d '{"job_id":"…","body":"Dumpster drops Tuesday at 7"}'A note goes on a lead’s timeline (lead_id), or in a client’s or job’s conversation in the Inbox (client_id or job_id). Nothing is emailed.
Webhooks: hear about it the moment it happens
PaperForeman POSTs JSON to your address for the events you pick:
lead.created(New lead)lead.stage_changed(Lead stage changed)estimate.sent(Estimate sent)estimate.viewed(Estimate opened)estimate.approved(Estimate approved)job.stage_changed(Job stage changed)invoice.overdue(Invoice past due)payment.received(Payment received)form.submitted(Form filled in)schedule.changed(Schedule changed)
POST https://your-app.example.com/paperforeman
PaperForeman-Event: estimate.approved
PaperForeman-Delivery: 6f1c…
PaperForeman-Signature: t=1762279200,v1=5d1e…
{ "id": "…", "type": "estimate.approved", "created_at": "2026-11-04T18:00:00.000Z",
"data": { "object": { "object": "estimate", "number": 12, "total_cents": 1240000, "status": "approved", … } } }Check the signature with the address’s secret (Settings → API & webhooks → Show the secret): HMAC-SHA256 of "<t>.<raw body>", hex, and refuse anything older than 5 minutes.
import { createHmac, timingSafeEqual } from 'node:crypto';
function fromPaperForeman(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const want = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
const got = Buffer.from(v1, 'hex');
return got.length === want.length && timingSafeEqual(got, want);
}Answer with any 2xx within 8 seconds. Anything else is tried again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, then it stops. Only public https addresses are allowed. Every try is in the delivery log.
Zapier and Make can subscribe themselves (REST hooks) with a read + write key:
curl https://usepaperforeman.com/api/v1/webhooks -H "Authorization: Bearer $PAPERFOREMAN_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://hooks.zapier.com/hooks/catch/123/abc","events":["lead.created"]}'
# → { "id": "…", "secret": "whsec_…", … } (the secret is shown once)
curl -X DELETE https://usepaperforeman.com/api/v1/webhooks/<id> -H "Authorization: Bearer $PAPERFOREMAN_KEY"Limits and errors
120 requests a minute per key and 10,000 a day per company. Too many gets 429 with Retry-After. Errors always look like { "error": { "type": "…", "message": "…" } }: 400 a field is wrong, 401 no key or a wrong one, 403 a read key tried to write or the plan isn’t active, 404 not in your account.
Questions? Write to us; a person answers.