Workiz Integration

Connect your Workiz account so KarmaFlow agents can look up jobs and leads, check who is free, and book appointments for callers — on the phone, in chat, over SMS, or from a task agent.

Workiz has no booking or availability API of its own, so KarmaFlow builds that capability itself from three channels you connect on the Workiz side. That makes setup a short checklist rather than a single "connect" button, and the connector is not finished when credentials verify — the steps after it are what make booking safe.

How It Works

KarmaFlow keeps a local mirror of your Workiz jobs, leads and schedule, and answers from it. Three channels keep that mirror true, and each one carries something the others cannot:

flowchart LR
  A[Workiz Automations<br/>webhooks] -->|"changes as they happen<br/>invoices + estimates"| M[(KarmaFlow mirror)]
  B[Calendar Sync feed<br/>iCal] -->|"future schedule<br/>tasks + events"| M
  C[Developer API<br/>REST, on demand] -->|"lookups + writes<br/>at the moment an agent answers"| M
  M --> D[Agents: look up, check availability, book]

What You'll Need

Open Settings in the top bar — the gear icon, which shows the word Settings beside it on wide screens — then the Integrations group, then Workiz. You can also go straight to /settings/workiz. Every step below is a numbered section on that one page, and each has a status chip showing where it stands.

The readiness banner on an incomplete setup: it names what is off — booking unguarded, invoices not captured, no forward schedule — and which step clears each one.

A banner at the top of the page states what is still missing and what it costs you, so an incomplete setup cannot quietly look finished. It disappears once every step is done.

Step 1 · Connect your credentials

In Workiz, go to Settings → Integrations → Developer and copy your API token and auth secret.

  1. In KarmaFlow, paste both values into section 1 of the Workiz page.
  2. Select Save credentials.

KarmaFlow verifies them immediately with a live call to Workiz, so a wrong value fails here rather than in front of a customer. On success the chip reads Connected with the number of team members found.

Credentials are stored encrypted and are never shown back to you — the fields stay blank afterwards, and leaving them blank on a later save keeps the stored values.

Step 2 · Turn on real-time updates (webhooks)

Workiz sends changes to KarmaFlow through Automations. There is no API to create these for you, so each one is set up by hand once.

In KarmaFlow, section 2 shows a Webhook URL and an Auth key, each with a Copy button. Then, in Workiz:

  1. Go to Automations → Add automation.
  2. Choose the trigger you want.
  3. Under do this, choose Post webhook.
  4. Paste the Webhook URL from KarmaFlow.
  5. Paste the Auth key into the automation's own Auth key field — the dedicated field beside the URL, not into the request body or a header you add yourself. Workiz sends it as an Authorization: Bearer header, and KarmaFlow rejects a delivery that arrives without it.
  6. Save, and repeat for each trigger.

At minimum, create automations for job created and lead created. Add invoice and estimate triggers if you want financial records to reach KarmaFlow — those two are the only way financial data ever reaches us.

A limitation to check as you go: Workiz's own documentation states that status-based automation rules "can only be set to send notifications" and cannot post webhooks. If the Automation Center offers you a webhook action on a status-change trigger, use it. If it does not, that is a Workiz restriction rather than a setup mistake — status changes will still reach KarmaFlow, just when an agent next reads the job rather than the moment they happen.

The chip in section 2 flips from Waiting for first delivery to Receiving, with a timestamp, once the first automation fires.

Do this early. Webhooks are the only source of invoices and estimates, and there is no way to fetch past ones later. Anything raised in Workiz before these automations exist is never captured.

Field map for a Workiz webhook automation: the trigger and action come first, the KarmaFlow webhook URL goes in the URL field, and the auth key goes in the automation's own Auth key field.

The diagram above shows the shape to look for rather than a pixel-exact copy of Workiz's screen, which changes over time.

Step 3 · Connect the schedule feed (Calendar Sync)

  1. In Workiz, go to Settings → Integrations → Calendar sync.
  2. Enable the add-on and choose All users — a per-user feed hides other technicians' work, which makes availability wrong.
  3. Copy the API URL.
  4. Paste it into section 3 in KarmaFlow and select Save feed.

The chip reads Syncing with the number of entries found.

Without this feed, agents cannot see any future schedule, and cannot see tasks or events at all — even though those occupy technician calendars. Availability answers will be incomplete.

Step 4 · Mirror your booking availability settings

Workiz offers no API to read your scheduling settings, so KarmaFlow cannot copy them for you. Mirror them here from Workiz's Online booking → Availability screen.

In section 4, set:

Field What it means
Timezone (IANA) Your business timezone, e.g. America/Toronto. All times agents quote are computed in it.
Slot duration (minutes) The length of a standard booking slot.
Advance notice (hours) How far ahead of now a booking may be made.
Availability preference Based on tech availability, Set number of jobs per slot, or Allow double booking — match whichever Workiz uses.
Jobs per slot Only shown when the preference is Set number of jobs per slot.
Business hours When you open and when you stop working — not when you stop starting jobs. A slot must fit entirely inside the window, so with two-hour slots and an 18:00 close, the last bookable start is 16:00. Set the close to the end of your working day or you will silently lose your last slot every day. Leave a day blank to mark it closed — a blank row shows Closed.

Select Save scheduling settings. The chip shows when the settings were last confirmed.

This step is what makes booking safe. Workiz accepts a double-booked time without complaint, so KarmaFlow's slot check is the only thing preventing one — and that check needs business hours. Until they are set, the chip reads Not configured — booking is unguarded. Because Workiz has no delete, a job booked into a conflict cannot be removed afterwards; it can only be rescheduled or cancelled in Workiz.

Keep these in sync by hand. If you change availability in Workiz, change it here too, or agents will offer times you cannot serve.

Section 4 before setup: every day blank and marked Closed, with the status chip warning that booking is unguarded.

The screenshot above shows the section before anything is filled in — every day blank, every row marked Closed, and the chip warning that booking is unguarded. That is what you will see on arrival, and what you are clearing.

Step 5 · Enable the background connection check

Agents read live data on demand, so this is not a sync — nothing polls Workiz on a timer. The background check exists so a revoked token or a rotated feed URL surfaces on this page rather than in the middle of a customer conversation.

  1. Tick Enable background connection check.
  2. Set Check every (hours) — 12 is the default and is appropriate for most workspaces.

Step 6 · Booking defaults (optional)

Section 5 also holds the booking defaults. Everything in this group is optional and off until you enter a value — with nothing set, agents book exactly as they did before, and no agent asks a customer a new question.

Field What it does Notes
Booking source stamp (JobSource) The Job Source written on every agent booking when no customer source applies. Must exist under Job Sources in Workiz, spelled exactly; otherwise the booking is created without it and the mismatch appears under Recent problems.
Default job type for bookings The Job Type when the agent does not name one. Must exist in Workiz.
Time display for agents 24-hour (14:00) or 12-hour (2:00 PM) when agents read times to customers. With 12-hour on, tool results carry a spoken label beside each time. Tell your agent to quote the label — in its prompt, in the same change — or it may keep reading the 24-hour value.
Note appended to agent bookings Text added to the job notes after whatever the agent wrote, e.g. Booked by KarmaFlow AI. Visible on the job in Workiz. No extra API call.
Tag agent bookings A tag applied to every agent-created job, e.g. KarmaFlow AI. Create the tag in Workiz first. Workiz cannot set tags when a job is created, so this is a second update after each booking. If it fails, the job stays booked and untagged, and the failure appears under Recent problems — a tag never costs a booking.
Customer job sources The Job Sources a customer can be attributed to, e.g. Google, Facebook, Referred. Spell each exactly as in Workiz. With a list here, agents ask the customer how they heard about you and stamp their answer instead of the fixed stamp. Leave empty to keep the fixed stamp.
When nothing matches, stamp Which of the sources above to use when the customer's answer fits none of them. Must be one of the sources above, so Workiz will accept it. Add an Other source in Workiz if you want one here.
Phrases customers use Optional phrase → source pairs, e.g. saw your truck → Truck. Matched before the built-in matching runs.

Select Save booking defaults. The list, its fallback and the phrases are checked against each other on save, so a fallback that is not in the list is refused here rather than failing inside a customer's booking.

Why the source stamp and the tag are separate. A job in Workiz has one Job Source. Once customers' answers go there, the tag is what still marks a job as agent-booked — which is what you filter a Workiz report on. If you leave the tag off, the appended note still says it on the job itself; it is just not something you can filter by.

Step 7 · Booking notifications (optional)

Workiz does not reliably send its own confirmation for a job created through its API, so a customer who books with an agent may hear nothing. KarmaFlow can tell both sides the moment a booking is written — no AI involved, it is sent by the platform with the exact values that went into Workiz.

Your team. Every agent booking and every reschedule raises An agent booked a Workiz job / An agent moved a Workiz job under Settings (gear) → Channels → Notification Preferences. They are on for email by default for anyone who can manage settings, and you can add addresses that have no login (a dispatch inbox) as extra recipients there. The alert carries the customer, the time window, the address, the job type, the notes the agent left for the crew, a link to the job in Workiz, and whether the customer received a confirmation.

Section 6 shows who gets it now, resolved the way the alert is actually delivered — each person's own preference, so the list never names someone the alert would skip. Add an address with no login (a dispatch inbox) right there, and press Send me a sample alert to see one.

Your customer. In section 6:

  1. Choose Send as — either one of your sender identities (created under Settings (gear) → Channels → Notification Senders; each uses a verified sending domain, so a mistyped address is impossible), or an agent's identity: any chat, SMS, voice, task or mail agent that already has a from address, listed as it sends today. If your chat agent already writes to customers as info@yourbusiness.com, pick it here and there is nothing to create. An agent whose address is not on one of your verified sending domains is listed but cannot be chosen (it says domain not verified), because the platform would otherwise have to send it from its own domain and the email would fail authentication. Replies come back to the chosen address; the agent's CC/BCC come along; and the agent's From name fills {{business_name}} — with no From name, the templates fall back to "us".
  2. Optionally pick a Signature. When you send as an agent that has one, the default is the agent's own signature; choose No signature for none, or any other signature to replace it — the same rule the campaign wizard uses when it borrows an agent's identity.
  3. Edit the two templates, Booked and Moved — a subject line and a rich-text body. Click a tag to insert it: {{first_name}}, {{when}}, {{date}}, {{start_time}}, {{end_time}}, {{address}}, {{job_type}}, {{business_name}}. A tag can carry a fallback for an empty value: {{address|the address you gave us}}. Crew notes are deliberately not available — they are written for the crew.
  4. Watch the preview on the right: it is rendered by the same code that sends, against a fixed sample booking, so what you see is what a customer gets. Send me a test mails the current draft to you.
  5. Tick Email the customer when an agent books or moves their job and select Save booking notifications.

A template with a tag that nothing fills is refused at save, so a customer can never receive literal braces. Reset to default restores the built-in text for either template. The confirmation only goes to customers who gave an email address when booking, and never includes a price. A send that fails appears under Recent problems, and the team alert says so too. Every confirmation is listed under Recent confirmations in the section and in Sent Emails → Platform in the reports.

Agents see the result in their tool response, so an agent can tell a customer "you'll get a confirmation at that address" only when one was actually sent.

What Agents Can Do Once Connected

With all five steps complete, agents on any channel can find jobs and leads by phone, email or name; read job details; check availability; book, reschedule and assign work; create and convert leads; and record payments. Every record an agent creates carries a link back to the conversation that produced it, so you can always see which call, chat or SMS thread caused a booking.

Agent tools appear only when Workiz is connected, and only for this workspace.

Troubleshooting

The chip in section 1 says the credentials could not be verified. The most common cause is that the Developer API add-on is not active in your Workiz Feature Center — without it Workiz will not honour the token. Confirm the add-on, then re-copy both values, as the token and secret are easy to transpose.

Section 2 still says "Waiting for first delivery." No automation has reached KarmaFlow yet. Check that the automation is enabled in Workiz, that the URL was pasted whole, and that the Auth key went into the automation's Auth key field rather than the body. Then trigger the event once in Workiz — for example, create a test job.

Availability looks wrong, or agents offer times you cannot serve. Almost always the settings in section 4 have drifted from Workiz, since nothing keeps them in step automatically. Compare them against Workiz's Online booking → Availability screen. If tasks and events are missing from availability, check that the Calendar Sync feed in section 3 is set to All users.

Agents say they cannot check availability. Business hours are not set. Complete section 4.

You need to change the webhook URL or auth key. Use Regenerate URL & key in section 2. This invalidates the values already pasted into Workiz, so every automation using them must be updated by hand afterwards.

Related

Sign in to KarmaFlow