JobTread Integration

Connects JobTread with the Newo AI agent so callers can start a new construction project, check on an existing one, or pull up their account — entirely by voice or chat, no office staff required.

What the AI can do

• Recognize returning customers. When a caller rings in, the agent looks them up by phone in JobTread and greets them with context: their projects, statuses, and contact info already loaded.
• Start a new project. Once the customer describes what they want (kitchen remodel, roof repair, deck addition…), the agent collects name, phone, email, and job-site address, then creates the customer record, the location, and the job in JobTread — a project manager sees it immediately.
• Check project status. Customer asks "how's my project going?" — agent reads back the latest from JobTread: job number and status, estimates / invoices with amounts, and how many tasks have been completed.
• Look up an account on demand. If the caller asks the agent to "find their account," the agent searches JobTread by name or phone and reads back what's on file.

Customer records in JobTread

The agent manages JobTread customer profiles automatically — no manual data entry:

Action	When it happens
Find customer (by phone)	On every inbound call and at the start of project creation. If a profile exists, the agent reuses it.
Create customer	During project creation, if no profile matches the caller's phone. Name, phone, email, and job-site address are copied into a new JobTread customer record.
Add location	During project creation, if the address the caller provided is new — the integration adds a job-site location to the customer's profile.

Duplicates aren't created. Historical jobs stay visible. The job notes and project description from the conversation appear in JobTread exactly where a project manager expects them.

Features at a glance

Feature	Included
Identify returning caller by phone	✅
Show caller's existing jobs at the start of a call	✅
Create a new construction job (customer + location + job in one go)	✅
Check job status, documents, and task progress	✅
Search customer on demand by name or phone	✅
Auto-fill project notes from the conversation	✅
DevMode (offline emulation for demos)	✅
Cancel an existing job	❌ (not yet supported)
Reschedule an appointment	❌ (JobTread is project-based, not slot-based)

Scenarios

The integration ships with three editable scenarios on the canvas. Operators can tweak them in the Newo UI; the agent picks up the changes on the next publish.

Scenario 10 — Creating Construction Job via Agent

Runs when the caller wants a new project. Rough flow:

1. Ask what work they need (kitchen, roof, deck, etc.) and a short description.
2. Collect first/last name → phone → email (optional).
3. Collect the job-site address (street, city, state, ZIP).
4. Confirm everything with the customer: "I have all the details. Shall I create this project for you now?"
5. Customer confirms → agent says "I'm creating your construction job now." → JobTread chain runs (find / create customer → add location → create job).
6. Agent reads back the new job number once JobTread responds.

Triggered by intent "[T] Create Job via Agent".

Scenario 11 — Checking Job Status via Agent

Runs when the caller wants the latest on an existing project. Rough flow:

1. Agent says "Let me check on your project status." → JobTread lookup runs.
2. If no jobs found: tell the caller, offer to start a new project.
3. If jobs found: read back each job's number, status, documents (estimates / invoices with amounts and statuses), and how many tasks are done.
4. Ask if anything else is needed.

Triggered by intent "[T] Check Job Status via Agent".

Scenario 12 — Searching Customer Account via Agent

Runs when the caller asks to look up their account directly. Rough flow:

1. Agent says "Let me look up your account." → JobTread search runs by name (and phone, if available).
2. If a profile is found: read back name, email, phone, and recent jobs.
3. If no profile: offer to start a new project.

Triggered by intent "[T] Search Customer via Agent".

Each scenario's exact code-phrase is required — it's what signals the agent to actually call JobTread (vs. just talk about it). If you rewrite a scenario, keep those phrases intact.

Example dialogs

Example 1 — Create a new project

Customer: Hi, I want to get a kitchen remodel started. New cabinets, countertops, flooring. Job site is 742 Evergreen Terrace, Springfield, IL. Agent: Hello! That sounds great. Could I get your full name, phone number, and email please? Customer: Mike Johnson, +15551234567, mike@example.com. Agent: I have all the details. Shall I create this project for you now? Customer: Yes please. Agent: I'm creating your construction job now. Please give me a moment, and I'll get back to you shortly. Agent: Fantastic, Mike! Your kitchen remodel project, job number 1042, has been successfully created. Is there anything else I can help you with today?

What lands in JobTread:

• New customer Mike Johnson (or his existing profile if a phone match was found).
• New location 742 Evergreen Terrace, Springfield, IL under that customer.
• New job #1042 — Kitchen Remodel with the conversation summary in the description.

Example 2 — Returning customer, status check

Customer: Hi, this is Sarah. I'm calling to check on my kitchen remodel project. Agent: Hello Sarah! Let me check on your project status. Please give me a moment. Agent: I found two projects for you. Your Kitchen Remodel, job #1042, is currently active. The estimate was sent for $25,000, and there's an unpaid invoice for $12,500. One of three tasks has been completed. You also have a Bathroom Addition, job #1043 which is pending. Do you need any details on a specific job?

Example 3 — Look up an account

Customer: Can you look up my account? My name is John Smith. Agent: Let me look up your account. Please give me a moment. Agent: Hi John! I found your account. Email john@example.com, phone +15551234567. You have two active projects: a Kitchen Remodel (active) and a Bathroom Addition (pending). How can I help you today?

Setup

Create the Newo project

If this project already exists in Newo Builder, skip this subsection and continue with the integration-specific settings below.

1. In Newo Builder, open the projects list and click Create Project (or Create New Project from the top-right menu).

2. Fill IDN and Title. The exact names do not matter; use any clear names your team will recognize.
3. In Registry, choose the release channel:
   • staging — the newest module fixes appear here first. Use it when you need the latest fix, but expect possible unfinished changes.
   • production — the final stable version for live projects.
4. In Module, select the module for this integration.

5. Leave Module version on Latest version unless support tells you to pin a specific version, then click Create.

1. Get your JobTread grant key

1. Log in to JobTread.
2. Go to Settings → API Keys.
3. Click Create new grant key.
4. Copy the key immediately — JobTread shows it only once.
5. The key starts with grant_.

Grant keys expire after 3 months of inactivity. Any successful call resets the timer, so an actively used integration never hits the expiry. If a key does expire, generate a new one in JobTread and paste it back into Newo.

2. Configure in Newo

1. Open the project and find the Module - JobTread attribute group.
2. Paste the grant key into jt_grant_key.
3. (Optional) review the feature toggles:

Setting	Purpose	Default
Enable Job Creation	Turns the create new project tool on or off.	on
Enable Job Status Lookup	Turns the check my project tool on or off.	on
Enable Customer Search	Turns the look up my account tool on or off.	on
Check Existing Client	Looks up returning callers by phone on inbound calls.	on
Auto-Setup Canvas Scenarios	Publishes the default create / status / search scenarios on first install.	on
Mode (jt_mode)	Production hits the real JobTread API. DevMode emulates responses for demos / smoke tests without using a live grant key.	Production

3. Hit Publish All

The agent will:

• create the connection to JobTread,
• register the create-job, status-lookup, and customer-search tools,
• add the three scenarios and three intents to the canvas (only if no conflicting items are already there — existing customizations are preserved).

That's it — place a test call or chat message to confirm.

Customizing the agent

The scenario bodies on canvas are fully editable. Common tweaks:

• Ask for more info during job creation. Add steps like "ask for square footage" or "ask whether there's a budget range". Whatever the agent collects ends up in the JobTread job description.
• Change the project type wording. Replace "kitchen remodel" examples with whatever is most common for your business (siding, roofing, decks…).
• Restore defaults. If you break a scenario, delete it from the canvas and republish — the original is restored from the integration's library.

FAQ

Q: Does the agent ever charge the customer? A: No. It only creates jobs, looks up status, and searches customers. Estimates, invoices, and payments stay with the JobTread project manager as normal.

Q: What happens if a customer with the same phone already exists? A: The agent reuses the existing JobTread profile — no duplicate. If the address the caller provides is new, the agent adds a new job-site location to that profile and uses it for the job.

Q: What if the caller doesn't want to share an email? A: The scenario treats email as optional. The agent will continue without it, and the JobTread customer record is created without an email.

Q: Can the caller cancel a job from the agent? A: Not yet — cancellation is on the roadmap. Today the agent can find the job and read back its status; cancellation has to happen in JobTread directly.

Q: My agent says "I'm creating your construction job now" but nothing happens. What's wrong? A: The most common causes are: (1) jt_grant_key is empty or wrong, (2) Enable Job Creation is off, or (3) the grant key has expired (3 months of inactivity). Check those first, then re-publish.

Q: What does DevMode do? A: With Mode set to DevMode, the integration does not call JobTread — it returns realistic-looking emulated responses instead. Useful for demos and smoke tests without burning real grant-key activity. Switch back to Production before going live.

Q: How does the agent see returning callers? A: When Check Existing Client is on, the integration looks up the caller by phone the moment a call starts and surfaces their profile and recent jobs to the agent — so the agent can greet them by name and recall context immediately.

Limitations

• Cancellation is not yet supported. Customers wanting to cancel are routed to a human (or a manager-message scenario) rather than auto-cancelled in JobTread.
• No appointment slots. JobTread is project-based, not appointment-based. The agent does not propose specific time slots — it captures a preferred start date if mentioned and stores it in the job description.
• Grant key only. OAuth is not used — the integration relies on a single static grant key. If the key changes, update jt_grant_key and republish.
• Returning-customer lookup is by phone only. Web-chat sessions without a phone number skip the inbound lookup; the agent collects info during the conversation instead.

All settings reference

Every attribute the integration adds to the Module - JobTread group in Newo. Operators typically only touch the "Primary" rows; the rest are good out of the box.

Primary (set these during setup)

Attribute	Title in UI	Purpose	Default
jt_grant_key	Grant Key	Authenticates every call to JobTread. Must be filled in before anything works.	(empty)
jt_enable_booking	Enable Job Creation	Turns the create-job tool on or off.	on
jt_enable_job_status	Enable Job Status Lookup	Turns the status-check tool on or off.	on
jt_enable_search_customer	Enable Customer Search	Turns the customer-lookup tool on or off.	on
jt_check_existing_client	Check Existing Client	Look up the caller by phone on inbound calls.	on
jt_setup_scenarios	Setup Scenarios	Publishes the create / status / search scenarios and intents on first install.	on
jt_mode	Mode	Production hits the real JobTread API. DevMode emulates responses for demos / smoke tests.	Production

Operational defaults

Attribute	Title in UI	Purpose	Default
jt_api_endpoint	API Endpoint	The JobTread API URL. Change only if JobTread support gives you a non-production endpoint.	https://api.jobtread.com/pave
jt_project_info	Integration Info	Read-only. Shows the integration version and a link to the docs.	auto-filled

Advanced fine-tuning (hidden by default)

There are a couple of advanced settings — labelled Advanced — for admins only in the UI — that let you fine-tune what the agent extracts from the conversation when creating a job (which fields, how relative dates are interpreted, etc.). They're hidden by default and only worth touching if you want to change the wording the agent uses internally.

If you accidentally edit one and the agent starts misbehaving, clear the value and Publish All to restore the default.

The integration also stores a few internal settings (a setup persona id, the active connector name) that are managed automatically. These never need manual editing.

Changelog

v1.3.0 — HCP-style prompt sections + reliability

• The agent now observes dedicated prompt sections — <JobCreationResult>, <JobStatusResult>, <CustomerSearchResult> — for each of the three tools. Each section shows In progress while the call runs and the result (or an error) once it returns, so the agent reacts immediately and doesn't get stuck waiting.
• Scenarios 10 / 11 / 12 now spell out the loading / success / error branches explicitly (Case1 / Case2 / Case3) so the agent's behaviour is consistent across loading states.
• New Enable Customer Search toggle — the customer-lookup tool can now be switched off independently of the others.

v1.2.0 — slimmed flow architecture

• Internal architecture aligned with the Housecall Pro pattern. The integration now has a single thin API layer instead of two redundant flows. Functionally the user-facing behaviour is unchanged; the change makes the integration easier to maintain and faster to extend.
• Per-feature result handling: each scenario's success and error logic is now isolated to its own flow, so a hiccup in one tool can't affect another.

v1.1.x — earlier JobTread integration work

Historical versions before the v1.2.0 architecture refactor. Full commit history: branch 882-job-tread.