Connecting FieldPulse to QuickBooks

Alright, so you're looking to hook up FieldPulse with QuickBooks. Honestly, this one tripped me up too when I first looked at it — the auth flow is a little weird if you're used to typical API keys. But once you get it running, the bi-directional sync is pretty solid. Let me walk you through what actually works.

What Syncs Where

First, the mental model. Here's what's actually happening under the hood:

FieldPulse → QuickBooks: Work orders (as invoices), customers, line items, tax rates
QuickBooks → FieldPulse: Payment status, invoice numbers, customer updates (if configured)

It's not truly real-time — there's a sync interval, usually 5-15 minutes depending on your plan. So if you're testing, don't panic if something doesn't show up immediately. I definitely panicked the first time.

Step 1: Connect the Integration

Head to Settings → Integrations → Accounting
Click Connect QuickBooks
You'll get bounced to Intuit's OAuth screen — sign in with your QB admin account
Authorize the scopes (invoices, customers, items)

One gotcha: you need Admin or Accountant permissions in QuickBooks, not just "Standard." I've seen folks get stuck here because their QB user doesn't have the right access level.

Step 2: Map Your Service Types

This is where things get interesting. FieldPulse service types need to map to QuickBooks items — specifically Service type items in your QB chart of accounts.

FieldPulse: "HVAC Repair - Emergency"
QuickBooks: "Services:HVAC:Emergency Repair"

If you skip this step, the sync will fail silently or create generic "Sales of Product Income" line items that make your accountant sad. Go to Integration Settings → Item Mapping and do this manually. Yeah, it's tedious if you have a lot of service types.

Step 3: Configure Sync Behavior

In Advanced Settings:

Create invoices as: Draft, Pending, or Final (I recommend Draft until you're confident)
Sync customers: Always create new, or match existing by email/phone
Tax handling: Map FieldPulse tax zones to QB tax codes

The customer matching logic is... okay. It uses email first, then phone, then company name. If you have customers with slightly different emails (like billing@ vs service@), you might get duplicates. There's a bulk customer import article that covers deduplication strategies if you're migrating.

Common Failures and How to Fix Them

Symptom	Usually Means	Fix
Invoice stuck "Pending Sync"	Tax rate mismatch	Double-check tax code mapping
Duplicate invoices in QB	Work order edited after initial sync	Enable "Update existing" in settings, or manually delete dupes
Customer name doesn't match	Special characters in company name	QB is picky about `&`, `#`, etc.
Line items show $0	Service type not mapped to QB item	Check item mapping (see Step 2)

Webhook Hooks (If You're Automating)

If you're building something custom on top of this, the invoice.synced webhook fires when a work order successfully lands in QuickBooks. Payload looks like:

{
  "event": "invoice.synced",
  "data": {
    "fieldpulse_work_order_id": "WO-2026-0042",
    "quickbooks_invoice_id": "1293",
    "quickbooks_invoice_number": "INV-2026-001293",
    "sync_status": "success",
    "synced_at": "2026-04-02T13:45:00Z"
  }
}

Yeah, the quickbooks_invoice_id vs quickbooks_invoice_number distinction matters — one's the internal QB ID, the other's what your customer sees. Store both if you're doing any downstream reporting.

Testing Without Messing Up Your Books

Pro tip: use QuickBooks' Plus or Advanced test company feature. Don't sync to your production QB file until you've run at least 10-15 work orders through and verified the line items, taxes, and customer records look right.

If you're on QBO Simple Start, you can't create a test company — you might need to make a separate trial account. Annoying, I know.