Skip to content
PaperForemanFree trial

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.

  1. In PaperForeman, open Settings → API & webhooks and tap Make a key (owner only). Copy it: it’s shown once.
  2. Paste the key into Zapier, Make or your code.
  3. 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…"
}
ListOne recordFilters
GET /api/v1/clientsGET /api/v1/clients/:idemail
GET /api/v1/leadsGET /api/v1/leads/:idstatus, source
GET /api/v1/jobsGET /api/v1/jobs/:idstatus, client_id
GET /api/v1/estimatesGET /api/v1/estimates/:idstatus, job_id
GET /api/v1/invoicesGET /api/v1/invoices/:idstatus, job_id
GET /api/v1/paymentsGET /api/v1/payments/:idinvoice_id
GET /api/v1/schedule-eventsGET /api/v1/schedule-events/:idjob_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.