Imports 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.

Import sources and fields

What can be imported: the sources (JOBBER, SERVICETITAN, SPREADSHEET = "Other spreadsheet"), each with the steps to export every dataset from that system, and the ServFlo fields of each dataset (mapping targets). The Jobber and ServiceTitan presets come from the vendors' public documentation and are not yet verified against real exports: unknown columns go to AI mapping. Read-only. Next: POST /imports.

Example

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

Response

List imports

The business's imports, newest first (the last 50), with files, progress, results and whether undo is still possible. Read-only.

Example

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

Response

Start an import

Creates a draft import from one source. Nothing is written to customers or jobs until it is applied. Next: add files (POST /imports/{importId}/files), check the mapping, preview, apply. A re-run on cutover day is a new import on fresh exports: records match by their source id (then email/phone, address, code, number) and are updated in place, never duplicated.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"JOBBER"}'

Response

Get an import

One import: its files with their detected dataset and column mapping, the last preview, progress while it runs (progress.done of progress.total rows), the summary and problems when finished, and the undo deadline. Poll it while status is QUEUED or RUNNING. Read-only.

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Delete a draft import

DELETES the draft import and its uploaded files. Only an import never applied (DRAFT); an applied one is undone instead (POST …/undo).

Parameters

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Add a file (content in the request)

Adds an export to the import in one call: text for CSV / TSV, or contentBase64 for any file including .xlsx (each sheet becomes a file of the import). It is stored privately, read, and sniffed: the dataset it holds (customers, properties, pricebook, quotes, jobs, visits, invoices, payments, memberships, contacts, notes) and the mapping from the source's preset, the saved mapping and the name heuristic. Several files may hold one dataset (Jobber splits clients into files of 1,500 rows). The browser uses POST …/uploads instead. Returns the import.

Parameters

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/files" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"string"}'

Response

Get an upload URL

Step 1 of a browser upload: a signed URL to PUT the file to (10 minutes, with the same Content-Type). Then POST …/uploads/{uploadId}/confirm to read and sniff it.

Parameters

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/uploads" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"string","contentType":"string","sizeBytes":1}'

Response

Confirm an upload

Step 2 of a browser upload: reads the uploaded file, sniffs each sheet and maps its columns. Returns the import.

Parameters

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/uploads/{uploadId}/confirm" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Set a file's dataset or mapping

Confirms or corrects what a file holds (dataset; null skips the file; changing it re-maps the columns) and its column mapping (mapping: header → field key from GET /migration/sources, custom:<label> for a new custom field on customers or properties, or null to skip). Confirmed columns are remembered for the next upload of that kind of file. Clears the preview. Returns the import.

Parameters

Request body

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/files/{fileId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"pricebook","mapping":{}}'

Response

Remove a file from an import

DELETES the file (sheet) from the draft import; its stored upload goes when no sheet uses it. Returns the import.

Parameters

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/files/{fileId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

AI column mapping

Columns the preset and the saved mapping do not know go to Claude (headers and up to three sample values each), which proposes a field, a custom field or skip with a confidence; anything below 0.7 is listed in needsReview. Never changes columns the owner set. Uses AI credits. Without AI configured the name heuristic answers (mode HEURISTIC). Returns the file.

Parameters

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/files/{fileId}/suggest-mapping" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Preview an import (dry run)

The dry run: counts per entity (to create, to update, duplicates, kept because edited in ServFlo), every problem with its file, row, column and severity, sample records, opening balances to write and customers who will need a card. Writes no records (only the preview on the import). Required before applying.

Parameters

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/preview" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Apply an import

Writes customer, job and money records: runs the previewed import in the background in dependency order (pricebook → customers → contacts → properties → memberships → quotes → jobs and visits → invoices → payments → notes). Sends nothing to customers: imported records emit no events and are held back from automations, reminders, membership billing and dunning until cutover (POST /migration/cutover/release); webhooks get one import.completed. Invoices keep their numbers, issue dates, tax as charged and balances (an opening-balance payment where only a balance was exported); counters move past the highest imported number. Poll GET /imports/{importId}. Undo within 7 days.

Parameters

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/apply" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Undo an import

DELETES what this import created (within 7 days of finishing), in reverse order. Records edited in ServFlo since, or used by work added since (a new job, a payment), are kept and listed in undoReport. Records the import only updated stay as they are. Returns the import (status UNDONE).

Parameters

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/imports/{importId}/undo" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Cutover checklist

What is left after importing: imported records still held back from automations (heldRecords), customers to ask for a card (customersNeedingCard), active technicians and automations, and the last import. Read-only.

Example

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

Response

Release imported records (cutover)

Customer-visible from now on: imported customers, visits, invoices and memberships join automations, reminders, dunning and membership billing. Do it once the old system has stopped sending (cutover day). Sends nothing by itself. Returns how many records were released.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/migration/cutover/release" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Customers to ask for a card

Customers who paid by card on file or autopay in the old system (needsPaymentMethod): saved cards are not copied, so they are sent the update-card link. The flag clears when they save a card. Read-only.

Example

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

Response

Send update-card links

Sends to customers: emails or texts each customer flagged needsPaymentMethod (or only customerIds) a link to their portal to add a card for automatic payments (Stripe Checkout in setup mode; nothing is charged). Consent, quiet hours and the message log apply; batchKey makes a retry send nothing twice. Needs online payments (Settings → Payments): 409 otherwise.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/migration/update-card-links" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"EMAIL_OR_SMS","customerIds":["customer_id"],"batchKey":"string"}'

Response