ServiceTitan API Workflow Documentation
Overview and Integration Goal
Avoca orchestrates post-call workflows, AI responder experiences, scheduling, dispatch, marketing audiences, and messaging by sitting directly on top of ServiceTitan’s APIs. Every major Avoca feature—voice QA, AI booking, Simple Scheduler, dispatch boards, outbound campaigns, texting, and task automation—either reads live ST data or pushes updates back through v2 endpoints. Integration goals- Deliver AI-assisted booking, reschedule, and cancellation flows that write directly to ST jobs, appointments, campaigns, tags, and notes.
- Provide real-time customer, membership, and service-history context to agents and automations during voice or text conversations.
- Sync Telecom calls, job/technician KPIs, and marketing audiences into Avoca’s analytics layer while feeding ST with reclassification decisions, tasks, and notes.
- Keep dispatch capacity, zones, technician rosters, and service areas aligned so Avoca scheduling mirrors ST availability.
- Maintain compliant credential storage (within a managed secrets platform) and scoped API usage for each tenant.
Key Integration Use Cases & Workflows
| # | Use Case | Description | Data Flow | Required ST API Endpoint and Data Fields | Necessary API Scopes (Read/Write) |
|---|---|---|---|---|---|
| 1 | Booking, rescheduling, or cancelling a job | AI or CSR workflows create jobs, reschedule appointments, cancel/hold jobs, assign campaigns/tags, and append summaries. | Avoca ⇌ ST | POST /jpm/v2/tenant/{tenant}/jobs, PATCH /jpm/v2/tenant/{tenant}/appointments/{id}/reschedule, PUT /jpm/v2/tenant/{tenant}/jobs/{id}/cancel, POST /crm/v2/tenant/{tenant}/bookings, GET /dispatch/v2/tenant/{tenant}/capacity, GET /jpm/v2/tenant/{tenant}/job-types, GET /settings/v2/tenant/{tenant}/business-units | READ: CRM, JPM, Dispatch, Marketing, Settings WRITE: JPM (jobs/appointments), CRM (bookings) |
| 2 | Customer & membership intelligence during calls/texts | Lookups by phone/address determine customer identity, locations, contacts, membership eligibility, tags, and guardrails. | ST → Avoca | GET /crm/v2/tenant/{tenant}/customers, /locations, /locations/{id}/contacts, GET /memberships/v2/tenant/{tenant}/customer-memberships, GET /settings/v2/tenant/{tenant}/tag-types, GET /jpm/v2/tenant/{tenant}/jobs | READ: CRM, Memberships, JPM, Settings |
| 3 | Simple Scheduler & booking windows | Avoca reads ACP capacity, arrival windows, shifts, and booking windows before generating ST bookings/jobs. | ST → Avoca then Avoca ⇌ ST when booking | POST /dispatch/v2/tenant/{tenant}/capacity, GET /dispatch/v2/tenant/{tenant}/arrival-windows, /technician-shifts, /non-job-appointments, /zones (final bookings reuse row 1 APIs) | READ: Dispatch, Settings WRITE: CRM/JPM for final booking |
| 4 | Dispatch board & technician (un)assignment | Ops users unassign business units, auto-assign responders, and sync on-call rosters. | Avoca ⇌ ST | GET /settings/v2/tenant/{tenant}/technicians, GET /jpm/v2/tenant/{tenant}/appointments, POST /dispatch/v2/tenant/{tenant}/appointmentassignments/assignTechnicians, /unassignTechnicians, GET /dispatch/v2/tenant/{tenant}/appointment-assignments | READ: Dispatch, JPM, Settings WRITE: Dispatch |
| 5 | Telecom ingestion & QA analytics | Coach, CSR QA, and cron jobs pull Telecom calls/recordings for evaluation. | ST → Avoca | GET /telecom/v3/tenant/{tenant}/calls, /calls/{id}, /calls/{id}/recording | READ: Telecom |
| 6 | Call reclassification & compliance updates | Avoca writes new call reasons and memos via Telecom APIs after QA or AI review. | Avoca ⇌ ST | GET /jbce/v2/tenant/{tenant}/call-reasons, PUT /telecom/v2/tenant/{tenant}/calls/{id} | READ: JBCE, Telecom WRITE: Telecom |
| 7 | Technician performance & revenue analytics | Jobs/appointments/invoices/estimates sync for dashboards; technician metadata powers UI. | ST → Avoca | GET /jpm/v2/tenant/{tenant}/jobs, /appointments, GET /accounting/v2/tenant/{tenant}/invoices, GET /estimates/v2/tenant/{tenant}/estimates, GET /dispatch/v2/tenant/{tenant}/appointment-assignments, GET /settings/v2/tenant/{tenant}/technicians | READ: JPM, Accounting, Dispatch, Settings |
| 8 | Audience building & outbound campaign enrichment | Recurring services, memberships, customers, campaigns, and jobs feed Avoca audiences and outbound workflows. | ST → Avoca (read) then Avoca ⇌ ST for overrides | GET /crm/v2/tenant/{tenant}/customers, /locations, GET /memberships/v2/tenant/{tenant}/memberships, /membership-types, /recurring-service-types, GET /marketing/v2/tenant/{tenant}/campaigns, GET /jpm/v2/tenant/{tenant}/jobs, GET /crm/v2/tenant/{tenant}/bookings | READ: CRM, Memberships, Marketing, JPM WRITE: None unless a new booking/job is created |
| 9 | Messaging, notes, and ST Task automation | Text threads write ST job/customer notes; workflows create ST tasks and fetch metadata. | Avoca ⇌ ST | POST /jpm/v2/tenant/{tenant}/jobs/{id}/notes, POST /crm/v2/tenant/{tenant}/customers/{id}/notes, POST /taskmanagement/v2/tenant/{tenant}/tasks, GET /taskmanagement/v2/tenant/{tenant}/client-side-data | READ: CRM, Task Management WRITE: JPM (job notes), CRM (customer notes), Task Management |
| 10 | Service areas, zones, and technician data | Zones, business units, and technician rosters sync for service areas and on-call rotations. | ST → Avoca | GET /dispatch/v2/tenant/{tenant}/zones, GET /settings/v2/tenant/{tenant}/business-units, GET /settings/v2/tenant/{tenant}/technicians | READ: Dispatch, Settings |
ServiceTitan API Scopes & Data Objects
Essential READ scopes
| Scope | Purpose | Activity Examples |
|---|---|---|
| CRM / READ | Caller identification, contact lookup, bookings. | /customers, /locations/{id}/contacts, /bookings/{id} |
| Dispatch / READ | Capacity, windows, shifts, zones. | /capacity, /arrival-windows, /technician-shifts, /zones |
| JPM / READ | Jobs, job types, cancel/hold reasons. | /appointments, /jobs, /job-types |
| Memberships / READ | Memberships, recurring services. | /memberships, /recurring-service-events |
| Marketing / READ | Campaigns, ST audience exports. | /campaigns, /audience-lists |
| Telecom / READ | Call/recording ingestion. | /calls, /calls/{id}/recording |
| Settings / READ | Business units, technicians, tags, booking tags. | /business-units, /technicians, /tag-types |
| Task Mgmt / READ | Metadata for composing tasks. | /client-side-data |
| Accounting / READ | Invoices for revenue & cancellation guardrails. | /invoices |
Essential WRITE scopes
| Scope | Purpose | Activity Examples |
|---|---|---|
| JPM / WRITE | Job creation, reschedule, cancel, notes, tags. | POST /jobs, PATCH /appointments/{id}/reschedule |
| CRM / WRITE | Customer/location upserts, notes. | POST /customers, /locations, /customers/{id}/notes |
| Dispatch / WRITE | Assign/unassign technicians. | /appointmentassignments/assignTechnicians |
| Bookings / WRITE | Provider-based bookings. | POST /crm/bookings |
| Telecom / WRITE | Reclassification & memos. | PUT /telecom/calls/{id} |
| Task Mgmt / WRITE | Create tasks. | POST /taskmanagement/tasks |
| Settings / WRITE | Admin-created tag types. | POST /settings/tag-types |
ServiceTitan Best Practices
| Question | Answer | Additional Context |
|---|---|---|
| Key rotation frequency | Rotated when ServiceTitan issues new credentials or during quarterly reviews. | Stored only in a managed secrets vault. |
| Hard-coded keys? | No. | Never in source control. |
| Credential storage | Managed secrets platform (US East). | Access via backend-only service accounts. |
| Purging keys on churn | ServiceTitan app removal or removing secrets from vault; credentials become invalid immediately. | Part of formal offboarding. |
| Purging customer data | Not currently purged automatically. | Can be purged on request. |