Job lifecycle management — creation, scheduling, assignment, status updates, and route optimization
openapi: 3.0.3
info:
title: Zuper REST Assets Jobs API
description: The Zuper REST API provides programmatic access to the Zuper field service management platform. It covers jobs, scheduling, route optimization, customers, organizations, assets, inventory, purchase orders, invoices, proposals, quotes, timesheets, projects, properties, service tasks, service contracts, webhooks, and communications. Authentication uses API keys passed via the x-api-key header. Region-specific base URLs are discovered by POSTing to the accounts endpoint.
version: 1.0.0
contact:
name: Zuper Developer Support
url: https://developers.zuper.co/discuss
x-api-evangelist-ratings:
design: 7
consistency: 7
documentation: 8
servers:
- url: https://{dc_region}.zuperpro.com/api
description: Region-specific API server (dc_region obtained from accounts endpoint)
variables:
dc_region:
default: us1
description: Data-center region identifier returned by the config endpoint
- url: https://accounts.zuperpro.com/api
description: Accounts / configuration endpoint
security:
- ApiKeyAuth: []
tags:
- name: Jobs
description: Job lifecycle management — creation, scheduling, assignment, status updates, and route optimization
paths:
/jobs:
get:
summary: Get Jobs
operationId: getJobs
description: Retrieve a paginated, filterable list of jobs.
tags:
- Jobs
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/CountParam'
- $ref: '#/components/parameters/SortParam'
- name: sort_by
in: query
schema:
type: string
enum:
- work_order_number
- job_priority
- scheduled_start_time
- due_date
default: work_order_number
- name: date_type
in: query
schema:
type: string
enum:
- scheduled_date
- created_date
- current_status_updated_at
default: scheduled_date
- name: filter.priority
in: query
schema:
type: string
enum:
- URGENT
- HIGH
- MEDIUM
- LOW
- name: filter.customer
in: query
schema:
type: string
- name: filter.category
in: query
schema:
type: string
- name: filter.keyword
in: query
schema:
type: string
- name: filter.job_tags
in: query
schema:
type: string
- name: filter.job_status
in: query
schema:
type: string
- name: filter.from_date
in: query
schema:
type: string
format: date-time
- name: filter.to_date
in: query
schema:
type: string
format: date-time
- name: filter.updated_at
in: query
schema:
type: string
format: date-time
- name: filter.assigned_to
in: query
schema:
type: string
- name: filter.assigned_to_team
in: query
schema:
type: string
- name: filter.is_deleted
in: query
description: Show deleted jobs (max 90 days)
schema:
type: boolean
- name: filter.is_invoiced
in: query
schema:
type: boolean
- name: filter.job_type
in: query
schema:
type: string
enum:
- NEW
- REVISIT
- name: filter.due_date_from
in: query
schema:
type: string
format: date-time
- name: filter.due_date_to
in: query
schema:
type: string
format: date-time
- name: filter.customer_feedback
in: query
schema:
type: string
enum:
- HAPPY
- NEUTRAL
- UNHAPPY
- VERY_HAPPY
- VERY_UNHAPPY
- name: filter.asset
in: query
schema:
type: string
- name: filter.property
in: query
schema:
type: string
- name: filter.project
in: query
schema:
type: string
- name: filter.business_unit
in: query
schema:
type: string
responses:
'200':
description: Paginated list of jobs
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Job'
'400':
description: Bad request
post:
summary: Create a Job
operationId: createJob
description: Create a new job in the field service management system.
tags:
- Jobs
parameters:
- name: check_assignment_conflict
in: query
schema:
type: boolean
default: false
description: Check for scheduling conflicts before creating
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- job_title
- job_category
properties:
job_title:
type: string
job_category:
type: string
job_priority:
type: string
enum:
- URGENT
- HIGH
- MEDIUM
- LOW
job_type:
type: string
enum:
- NEW
- REVISIT
job_description:
type: string
job_tags:
type: array
items:
type: string
scheduled_start_time:
type: string
format: date-time
scheduled_end_time:
type: string
format: date-time
due_date:
type: string
format: date-time
assigned_to:
type: array
items:
type: string
assigned_to_team:
type: array
items:
type: string
customer_uid:
type: string
format: uuid
customer:
type: object
assets:
type: array
items:
type: string
products:
type: array
items:
type: string
skills:
type: array
items:
type: string
attachments:
type: array
items:
type: object
service_task:
type: string
service_contract:
type: string
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomField'
responses:
'200':
description: Job created successfully
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: success
message:
type: string
example: New Job Created successfully
job_uid:
type: string
format: uuid
customer_uid:
type: string
format: uuid
'400':
description: Bad request - customer or organization data required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/jobs/{job_uid}:
get:
summary: Get Job Details
operationId: getJobDetails
description: Retrieve detailed information for a specific job.
tags:
- Jobs
parameters:
- name: job_uid
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Job details
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'404':
description: Job not found
put:
summary: Update a Job
operationId: updateJob
description: Update an existing job record.
tags:
- Jobs
parameters:
- name: job_uid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'200':
description: Job updated successfully
'400':
description: Bad request
delete:
summary: Delete a Job
operationId: deleteJob
description: Delete a job record.
tags:
- Jobs
parameters:
- name: job_uid
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Job deleted successfully
'404':
description: Job not found
components:
parameters:
CountParam:
name: count
in: query
description: Number of records per page (max 1000)
schema:
type: integer
default: 10
maximum: 1000
PageParam:
name: page
in: query
description: Page number (1-based)
schema:
type: integer
default: 1
SortParam:
name: sort
in: query
schema:
type: string
enum:
- DESC
- ASC
default: DESC
schemas:
Job:
type: object
properties:
job_uid:
type: string
format: uuid
job_title:
type: string
job_category:
type: string
job_priority:
type: string
enum:
- URGENT
- HIGH
- MEDIUM
- LOW
job_type:
type: string
enum:
- NEW
- REVISIT
job_description:
type: string
job_tags:
type: array
items:
type: string
scheduled_start_time:
type: string
format: date-time
scheduled_end_time:
type: string
format: date-time
due_date:
type: string
format: date-time
assigned_to:
type: array
items:
type: string
assigned_to_team:
type: array
items:
type: string
customer_uid:
type: string
format: uuid
assets:
type: array
items:
type: string
products:
type: array
items:
type: string
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomField'
CustomField:
type: object
properties:
label:
type: string
value:
type: string
type:
type: string
module_name:
type: string
PaginatedResponse:
type: object
properties:
type:
type: string
total_records:
type: integer
current_page:
type: integer
total_pages:
type: integer
ErrorResponse:
type: object
properties:
type:
type: string
example: error
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key generated from Zuper Settings > Developer Hub > API Keys