Integrations API

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

List integrations

The accounting integrations, QuickBooks Online and Xero: for each, whether the server is configured for it and in which mode (mock, sandbox / production or live), the variables still missing, the connection, mappings, sync counts and records synced; blockedBy names the other one when it is connected (one accounting system at a time). Xero also lists pendingTenants while a consent that connected several Xero organisations waits for the choice. Start with POST /integrations/quickbooks/connect or POST /integrations/xero/connect. Read-only.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Start connecting QuickBooks

Grants access: returns the Intuit consent URL to open (in mock mode, the callback URL directly). After consent Intuit redirects to /integrations/quickbooks/callback with code, state and realmId; finish with POST /integrations/quickbooks/callback. 400 when the server is not configured (see GET /integrations); 409 while Xero is connected (one accounting system at a time).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/connect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Disconnect QuickBooks

Revokes access: revokes and forgets the QuickBooks tokens; nothing more is pushed and waiting syncs are skipped. The mappings of synced records are kept, so reconnecting the same company updates them rather than creating duplicates.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/disconnect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

QuickBooks mappings

The current mappings and the choices from the connected company: income accounts, items, tax codes and deposit accounts. Invoices need the default item before they can be pushed. 409 when not connected. Read-only.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Set the QuickBooks mappings

Choose the QuickBooks item invoice lines are booked to (required), the income account (for reference), the tax code for taxed invoices (default TAX) and the account payments are deposited to (default Undeposited Funds). Ids from GET /integrations/quickbooks/settings; null clears.

Request body

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"item_id","incomeAccountId":"incomeAccount_id","taxCodeId":"taxCode_id"}'

Response

QuickBooks sync log

Every push to QuickBooks, newest first: the record (customer, invoice, payment, refund), what triggered it (an event or a manual resync), status (PENDING, SUCCEEDED, FAILED = will retry, DEAD, SKIPPED with the reason), attempts, the QuickBooks id and the error. Filter by status or record. Read-only.

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/sync-log" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Push a record to QuickBooks now

Pushes one customer, invoice, payment or refund to the connected QuickBooks now (creating it, or updating the copy already there: never a duplicate), with what it depends on (an invoice's customer first). Answers the sync task. Drafts and cancelled invoices are skipped.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/resync" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"CUSTOMER","entityId":"entity_id"}'

Response

Run the QuickBooks sync now

Processes this organization's waiting pushes now instead of on the next scheduler run (it also runs every few seconds in the API service). Answers how many were attempted, succeeded, failed, died or were skipped.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/sync" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

A record's QuickBooks status

Whether a customer, invoice, payment or refund is in QuickBooks: SYNCED (with its QuickBooks id and when), PENDING, ERROR (with the reason), SKIPPED (why), NOT_SYNCED, or NOT_CONNECTED when the organization has no QuickBooks. For the badge on invoices and customers. Read-only.

Permission: invoices.read (Owner, Admin, Dispatcher, Technician (own jobs' invoices), Member); risk read (OAuth scope servflo.read).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/quickbooks/records/{entityType}/{entityId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Start connecting Xero

Grants access: returns Xero's consent URL to open (in mock mode, the callback URL directly). After consent Xero redirects to /integrations/xero/callback with code and state; finish with POST /integrations/xero/callback. 400 when the server is not configured (see GET /integrations); 409 while QuickBooks is connected (one accounting system at a time).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/connect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Choose the Xero organisation

Grants access: connects ServFlo to one of the Xero organisations the last consent connected (pendingTenants of GET /integrations). Choosing a different organisation than before starts with empty mappings. 409 when nothing waits for a choice (connect again) or QuickBooks is connected.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/tenant" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenantId":"tenant_id"}'

Response

Disconnect Xero

Revokes access: removes the connection at Xero and forgets the tokens; nothing more is pushed and waiting syncs are skipped. The ids of synced records are kept, so reconnecting the same Xero organisation updates them rather than creating duplicates. Also cancels a connection waiting for the organisation choice.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/disconnect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Xero mappings

The current mappings and the choices from the connected Xero organisation: revenue accounts (by code), bank accounts for payments, tax rates (TaxType with its rate), items and tracking categories with their options; ratesInUse lists the tax rates on this organization's invoices, for per-rate tax mapping. Invoices need the sales account (and a tax rate when taxed), payments and refunds the bank account. 409 when not connected. Read-only.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Set the Xero mappings

Choose the revenue account invoice lines are booked to (salesAccountCode, required), the Xero tax rate for taxed invoices (taxType, required when invoices carry tax) and for untaxed ones (noTaxType, default NONE), optional per-rate overrides (taxRates: ServFlo rate → TaxType; replaces the list), the bank account payments go into and refunds come out of (paymentAccountId, required for payments and refunds), and optionally an item code and one tracking option for every line (category and option together). Values from GET /integrations/xero/settings; null clears.

Request body

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"salesAccountCode":"string","taxType":"string","noTaxType":"string"}'

Response

Xero sync log

Every push to Xero, newest first: the record (customer → Contact, invoice → ACCREC Invoice, payment → Payment, refund → CreditNote and its refund payment), what triggered it (an event or a manual push), status (PENDING, SUCCEEDED, FAILED = will retry, including a rate-limit pause, DEAD, SKIPPED with the reason), attempts, the Xero id and the error. Filter by status or record. Read-only.

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/sync-log" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Push a record to Xero now

Pushes one customer, invoice, payment or refund to the connected Xero organisation now (creating it, or updating the copy already there: never a duplicate; a first contact push links an existing Xero contact of the same name), with what it depends on (an invoice's contact first). Answers the sync task. Drafts and cancelled invoices are skipped; an invoice already paid in Xero is not changed (Xero locks it).

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/resync" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"CUSTOMER","entityId":"entity_id"}'

Response

Run the Xero sync now

Processes this organization's waiting pushes now instead of on the next scheduler run. Pushes pause when Xero's rate limit (60 calls a minute, 5,000 a day) is reached and resume after the pause Xero asks for. Answers how many were attempted, succeeded, failed, died, were skipped or deferred.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/sync" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

A record's Xero status

Whether a customer, invoice, payment or refund is in Xero: SYNCED (with its Xero id and when), PENDING, ERROR (with the reason), SKIPPED (why), NOT_SYNCED, or NOT_CONNECTED when the organization has no Xero. For the badge on invoices and customers. Read-only.

Permission: invoices.read (Owner, Admin, Dispatcher, Technician (own jobs' invoices), Member); risk read (OAuth scope servflo.read).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/integrations/xero/records/{entityType}/{entityId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response