List and retrieve leads and manage their lifecycle - create and update leads and mark a lead as active or lost. Leads are prospective work that can be converted into jobs. List and single-record reads are confirmed in the public API; write and status-change operations are exposed through Workiz integration partners and modeled here.
openapi: 3.0.3
info:
title: Workiz API
description: >-
The Workiz REST API lets home-service businesses read and write their field
service data - jobs, leads, team members, time off, and payments - and
receive outbound webhooks for new jobs and new leads. Workiz is field service
management (FSM) software covering scheduling and dispatch, CRM, estimates and
invoicing, payments, and communications.
All calls are made to https://api.workiz.com/api/v1/ with the account API
token embedded directly in the request path
(https://api.workiz.com/api/v1/{api_token}/...). To obtain credentials, enable
the Developer API add-on from the Workiz Feature Center / Marketplace and copy
the API token (and secret) from Settings > Integrations. Responses are JSON,
and HTTP status codes signal errors.
Endpoint coverage is marked per operation with `x-endpoint-status`:
`confirmed` operations are grounded in Workiz's public developer docs and the
community PHP/Python SDKs; `modeled` operations (some Lead writes, the Payments
detail, and the webhook payloads) reflect capabilities exposed through Workiz's
UI and integration partners (Make, Pipedream) whose exact request/response
shapes are gated behind the authenticated developer portal and are represented
here as a best-effort model.
version: '1.0'
contact:
name: Workiz
url: https://developer.workiz.com/
servers:
- url: https://api.workiz.com/api/v1/{api_token}
description: Workiz REST API. The account API token is part of the base path.
variables:
api_token:
default: YOUR_API_TOKEN
description: >-
The account API token from the Workiz Developer API add-on
(Settings > Integrations). It is placed directly in the URL path; there
is no Authorization header. A paired API secret is issued for signed
requests where required.
tags:
- name: Jobs
description: Work orders - the core scheduling and dispatch entity in Workiz.
- name: Leads
description: Prospective work that can be converted into jobs.
- name: Team
description: Users - technicians, dispatchers, and office staff.
- name: Time Off
description: Technician time-off records that affect availability.
- name: Payments
description: Payments recorded against a job.
- name: Webhooks
description: Outbound event notifications for new jobs and new leads.
paths:
/job/all/:
get:
operationId: listJobs
tags:
- Jobs
summary: List jobs
description: >-
Returns a paginated list of jobs. Supports filtering by open state and
status, and offset-based pagination.
x-endpoint-status: confirmed
parameters:
- name: records
in: query
required: false
description: Number of records to return per page.
schema:
type: integer
default: 100
- name: offset
in: query
required: false
description: Number of records to skip for pagination.
schema:
type: integer
default: 0
- name: only_open
in: query
required: false
description: When true, return only open (not closed/cancelled) jobs.
schema:
type: boolean
- name: start_date
in: query
required: false
description: Filter jobs on or after this date (YYYY-MM-DD).
schema:
type: string
format: date
- name: status
in: query
required: false
description: Filter jobs by status label (for example Scheduled, In Progress, Done).
schema:
type: string
responses:
'200':
description: A list of jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/JobListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/job/get/{UUID}/:
parameters:
- $ref: '#/components/parameters/JobUUID'
get:
operationId: getJob
tags:
- Jobs
summary: Get a job
description: Retrieves a single job by its UUID.
x-endpoint-status: confirmed
responses:
'200':
description: The requested job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/job/create/:
post:
operationId: createJob
tags:
- Jobs
summary: Create a job
description: Creates a new job (work order) in the account.
x-endpoint-status: confirmed
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobInput'
responses:
'200':
description: The created job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/job/update/:
post:
operationId: updateJob
tags:
- Jobs
summary: Update a job
description: Updates an existing job. The job UUID is supplied in the request body.
x-endpoint-status: confirmed
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobUpdateInput'
responses:
'200':
description: The updated job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/job/assign/:
post:
operationId: assignJob
tags:
- Jobs
summary: Assign a user to a job
description: Assigns a team member to an existing job.
x-endpoint-status: confirmed
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobAssignmentInput'
responses:
'200':
description: Assignment result.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/job/unassign/:
post:
operationId: unassignJob
tags:
- Jobs
summary: Unassign a user from a job
description: Removes a team member from an existing job.
x-endpoint-status: confirmed
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobAssignmentInput'
responses:
'200':
description: Unassignment result.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/job/addPayment/{UUID}/:
parameters:
- $ref: '#/components/parameters/JobUUID'
post:
operationId: addJobPayment
tags:
- Payments
summary: Add a payment to a job
description: >-
Records a payment against a job by its UUID. The confirmed public
operation is adding a payment; the payment body fields (amount, method,
date) are modeled from Workiz's invoicing and payments behavior.
x-endpoint-status: confirmed
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInput'
responses:
'200':
description: The recorded payment.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/lead/all/:
get:
operationId: listLeads
tags:
- Leads
summary: List leads
description: Returns a paginated list of leads. Supports offset-based pagination.
x-endpoint-status: confirmed
parameters:
- name: records
in: query
required: false
description: Number of records to return per page.
schema:
type: integer
default: 100
- name: offset
in: query
required: false
description: Number of records to skip for pagination.
schema:
type: integer
default: 0
responses:
'200':
description: A list of leads.
content:
application/json:
schema:
$ref: '#/components/schemas/LeadListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/lead/get/{UUID}/:
parameters:
- $ref: '#/components/parameters/LeadUUID'
get:
operationId: getLead
tags:
- Leads
summary: Get a lead
description: Retrieves a single lead by its UUID.
x-endpoint-status: confirmed
responses:
'200':
description: The requested lead.
content:
application/json:
schema:
$ref: '#/components/schemas/LeadResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/lead/create/:
post:
operationId: createLead
tags:
- Leads
summary: Create a lead
description: >-
Creates a new lead. Exposed through Workiz integration partners; request
shape modeled here.
x-endpoint-status: modeled
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LeadInput'
responses:
'200':
description: The created lead.
content:
application/json:
schema:
$ref: '#/components/schemas/LeadResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/lead/update/:
post:
operationId: updateLead
tags:
- Leads
summary: Update a lead
description: >-
Updates an existing lead. Exposed through Workiz integration partners;
request shape modeled here.
x-endpoint-status: modeled
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LeadUpdateInput'
responses:
'200':
description: The updated lead.
content:
application/json:
schema:
$ref: '#/components/schemas/LeadResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/team/all/:
get:
operationId: listTeam
tags:
- Team
summary: List team members
description: Returns all team members (technicians, dispatchers, office users) in the account.
x-endpoint-status: confirmed
responses:
'200':
description: A list of team members.
content:
application/json:
schema:
$ref: '#/components/schemas/TeamListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/team/get/{USER_ID}/:
parameters:
- name: USER_ID
in: path
required: true
description: The user ID of the team member.
schema:
type: string
get:
operationId: getTeamMember
tags:
- Team
summary: Get a team member
description: Retrieves a single team member by user ID.
x-endpoint-status: confirmed
responses:
'200':
description: The requested team member.
content:
application/json:
schema:
$ref: '#/components/schemas/TeamMemberResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/timeoff/get/:
get:
operationId: listTimeOff
tags:
- Time Off
summary: List time off
description: Returns time-off records for the account.
x-endpoint-status: confirmed
responses:
'200':
description: A list of time-off records.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/timeoff/get/{USER_NAME}/:
parameters:
- name: USER_NAME
in: path
required: true
description: The user name whose time off to retrieve.
schema:
type: string
get:
operationId: getUserTimeOff
tags:
- Time Off
summary: Get time off for a user
description: Returns the time-off records for a specific user by name.
x-endpoint-status: confirmed
responses:
'200':
description: The user's time-off records.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
JobUUID:
name: UUID
in: path
required: true
description: The UUID of the job.
schema:
type: string
LeadUUID:
name: UUID
in: path
required: true
description: The UUID of the lead.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
flag:
type: boolean
description: Workiz success flag; false on error.
code:
type: integer
data:
type: string
description: Human-readable error message.
GenericResponse:
type: object
properties:
flag:
type: boolean
description: Success flag.
data:
type: object
additionalProperties: true
Job:
type: object
description: A Workiz job (work order).
properties:
UUID:
type: string
SerialId:
type: integer
JobType:
type: string
JobSource:
type: string
JobDateTime:
type: string
format: date-time
JobEndDateTime:
type: string
format: date-time
Status:
type: string
SubStatus:
type: string
JobTotalPrice:
type: number
JobAmountDue:
type: number
ClientId:
type: integer
FirstName:
type: string
LastName:
type: string
Phone:
type: string
Email:
type: string
Address:
type: string
City:
type: string
State:
type: string
PostalCode:
type: string
Country:
type: string
Latitude:
type: number
Longitude:
type: number
Team:
type: array
items:
type: string
description: Names or IDs of assigned team members.
CreatedDate:
type: string
format: date-time
JobInput:
type: object
required:
- JobType
- JobDateTime
properties:
JobType:
type: string
JobSource:
type: string
JobDateTime:
type: string
format: date-time
JobEndDateTime:
type: string
format: date-time
Comments:
type: string
FirstName:
type: string
LastName:
type: string
Phone:
type: string
Email:
type: string
Address:
type: string
City:
type: string
State:
type: string
PostalCode:
type: string
LineItems:
type: array
items:
$ref: '#/components/schemas/LineItem'
JobUpdateInput:
allOf:
- type: object
required:
- UUID
properties:
UUID:
type: string
- $ref: '#/components/schemas/JobInput'
JobAssignmentInput:
type: object
required:
- UUID
- User
properties:
UUID:
type: string
description: The UUID of the job.
User:
type: string
description: The user (team member) to assign or unassign.
LineItem:
type: object
properties:
name:
type: string
quantity:
type: number
unitPrice:
type: number
taxable:
type: boolean
JobResponse:
type: object
properties:
flag:
type: boolean
data:
$ref: '#/components/schemas/Job'
JobListResponse:
type: object
properties:
flag:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Job'
has_more:
type: boolean
Lead:
type: object
description: A Workiz lead (prospective work).
properties:
UUID:
type: string
SerialId:
type: integer
LeadType:
type: string
LeadSource:
type: string
Status:
type: string
FirstName:
type: string
LastName:
type: string
Phone:
type: string
Email:
type: string
Address:
type: string
City:
type: string
State:
type: string
PostalCode:
type: string
CreatedDate:
type: string
format: date-time
LeadInput:
type: object
required:
- LeadType
properties:
LeadType:
type: string
LeadSource:
type: string
FirstName:
type: string
LastName:
type: string
Phone:
type: string
Email:
type: string
Address:
type: string
City:
type: string
State:
type: string
PostalCode:
type: string
Comments:
type: string
LeadUpdateInput:
allOf:
- type: object
required:
- UUID
properties:
UUID:
type: string
Status:
type: string
enum:
- active
- lost
description: Mark the lead active or lost.
- $ref: '#/components/schemas/LeadInput'
LeadResponse:
type: object
properties:
flag:
type: boolean
data:
$ref: '#/components/schemas/Lead'
LeadListResponse:
type: object
properties:
flag:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Lead'
has_more:
type: boolean
TeamMember:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
role:
type: string
active:
type: boolean
TeamMemberResponse:
type: object
properties:
flag:
type: boolean
data:
$ref: '#/components/schemas/TeamMember'
TeamListResponse:
type: object
properties:
flag:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/TeamMember'
TimeOff:
type: object
properties:
id:
type: string
user:
type: string
startDate:
type: string
format: date-time
endDate:
type: string
format: date-time
reason:
type: string
TimeOffListResponse:
type: object
properties:
flag:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/TimeOff'
PaymentInput:
type: object
description: >-
Payment recorded against a job. Modeled fields - Workiz confirms the
addPayment operation; the exact body is gated behind the developer portal.
required:
- amount
properties:
amount:
type: number
paymentMethod:
type: string
description: For example cash, credit_card, check.
date:
type: string
format: date
note:
type: string
PaymentResponse:
type: object
properties:
flag:
type: boolean
data:
type: object
properties:
paymentId:
type: string
jobUUID:
type: string
amount:
type: number