Skip to content

Integrations

Jump to bottom
Doug edited this page Jul 16, 2026 · 5 revisions

Integrations

External services GDX talks to. Everything here is optional — the app runs without any of them, and each one lights up when its keys are configured (see Configuration Reference; .env.template documents every variable).

QuickBooks

Two-way sync with QuickBooks Online: customers, invoices, payments, and expenses/bills.

  • Pull — scheduled syncs plus Intuit webhooks on entity changes; incoming customers are matched to local records by fuzzy name + phone.
  • Push — locally created/edited invoices are pushed back on a short cycle (a dirty flag marks what needs pushing).
  • Setup — an OAuth connect flow from the QuickBooks page (server-side token exchange; tokens stored encrypted). Env: QB_CLIENT_ID, QB_CLIENT_SECRET, QB_REDIRECT_URI, QB_ENVIRONMENT, QB_WEBHOOK_VERIFIER_TOKEN.
  • Budgets read the QB P&L for budget-vs-actual comparisons.

Stripe

Online payments for invoices — customers pay via Stripe Checkout from a shared invoice link or the Customer Portal, which also supports saved payment methods and ACH with micro-deposit verification. Stripe Connect onboarding (Express) is available for routing payments to a connected account. Webhooks are signature-verified. Env: STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, STRIPE_WEBHOOK_SECRET.

Phone.com

VoIP integration: inbound/outbound call log, SMS threads, voicemail, faxes, click-to-call, and a cold-leads list of missed callers.

  • Setup — paste your Phone.com API token in Settings → Integrations; the app validates it, discovers your extensions, and stores it encrypted. Pick a default extension/caller ID.
  • Webhooks + nightly reconciliation keep history complete; a nightly job pushes your customers to Phone.com as contacts (desk-phone caller ID shows names), and webhook URL secrets rotate weekly automatically.

Email & Outlook

  • Outbound email — any SMTP provider, configured per tenant in Settings (with a send-test button). The system sends estimate/invoice emails, appointment reminders, review requests, payment reminders, and portal magic links through it.
  • Outlook / Microsoft 365 — optional per-employee mailbox sync via Microsoft Graph OAuth: the Inbox module shows synced email, with webhook subscriptions created on connect, renewed automatically (and re-created if missing), and a 30-minute polling fallback. Graph needs a public HTTPS notification URL — set GDX_PUBLIC_BASE_URL (see Configuration Reference) or subscriptions can't be created.
  • Vendor bills by email — the mailbox sync can turn a supplier's emailed PDF invoice into a bill in the review queue automatically (see Inventory & Purchasing). It is opt-in and off until you list senders: only mail from an address (or domain) you add to the vendor-bill sender allowlist is ever processed — a stranger's attachment is never opened or parsed. Re-seeing the same message won't create a duplicate bill.

Google Maps

Geocoding, drive-time estimates between jobs, route optimization, and service-area (polygon) checks on the dispatch side. Optional API key; the dispatch board works without it, minus traffic-aware features.

AI / local LLM

AI assists (quick estimates, line-item suggestions, message drafts) call any OpenAI-compatible endpoint — a local vLLM/Ollama/LocalAI works. Configure AI_PROVIDER_URL / AI_PROVIDER_MODEL / AI_PROVIDER_KEY, or set a tenant-specific key in Admin → AI Settings (stored encrypted, validated on save). Without a provider, every AI feature degrades gracefully to keyword matching or built-in templates.

Outbound webhooks (Zapier / n8n / anything)

Subscribe your own endpoints to app events: job.* (created/updated/ completed/cancelled), estimate.* (sent/accepted/declined), invoice.* (created/sent/paid/overdue), customer.*, payment.*, appointment.*. Managed under Admin → Webhooks, with a test-send button.

MCP (experimental)

The app mounts a Model Context Protocol server at /mcp (Streamable HTTP) exposing tools over customers, jobs, estimates, invoices, documents, email, and scheduling for AI clients. Access is tenant-bound: every request needs a JWT bearer issued for the instance's host (audience <host>/mcp), signed with the deployment's JWT keys. The OAuth discovery documents are published, but the authorize/token endpoints are not implemented yet, so connector-style onboarding (e.g. from a chat product) can't complete — tokens must be provisioned out of band. Treat MCP as experimental.

Scheduled background jobs

Celery beat drives the recurring machinery: hourly appointment-reminder scans; daily recurring-job generation; Outlook subscription renewal (every 6h) with a 30-minute polling fallback; nightly Phone.com reconciliation, stats rollups, and customer→contact pushes, plus weekly webhook-secret rotation; nightly estimate-draft purge/archive; nightly customer rolling-volume refreshes; daily GPS-location pruning; a half-hourly timeclock sweep that closes forgotten shifts; the per-tenant QuickBooks banking-sync dispatcher; nightly forecasting snapshots and reconciliation; the daily planner digest (when configured); and daily billing follow-up + invoice reminder scans (automatic reminders are opt-in). Two worker queues (priority:high for user-facing sends, priority:low for batch work) — see Architecture.

See also

Clone this wiki locally