Workiz Logo
API docs by Redocly

Developer API (2.0)

The API is built to allow you to create a functional application or integration quickly and easily.

Search

Search across multiple entity types

Returns a list of matching results across entity types based on the provided search term.

By default, results are returned from all entity types (jobs, leads, clients, invoices) up to the specified limit per type.

Use the type parameter to restrict results to a single entity type. Requesting type=lead requires the Leads add-on to be enabled on the account.

Results are ranked by relevance score. The entityId field is an ID that can be used with other API endpoints.

query Parameters
term
required
string
Example: term=john doe

Search term matched against name, phone, email, address, serial numbers, and custom fields across entity types.

type
string
Enum: "job" "lead" "client" "invoice"

Restrict results to a single entity type. Omit to search across all types.

  • job — returns only jobs (excludes leads)
  • lead — returns only leads (requires Leads add-on)
  • client — returns only clients
  • invoice — returns only invoices
limit
number
Default: 5
Example: limit=5

Maximum number of results to return per entity type. Defaults to 5, maximum 15.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "limit": 5,
  • "totalResults": 10,
  • "data": [
    • {
      • "entityType": "job",
      • "entityId": "JOB-LwqGJnRwvZPaNe5E",
      • "uuid": "GD87TS",
      • "serialId": 1042,
      • "name": "Fix leaking pipe",
      • "status": "pending",
      • "date": "2026-04-28 09:00:00",
      • "totalPrice": 250,
      • "amountDue": 100,
      • "companyName": "Acme Corp",
      • "email": "client@example.com",
      • "primaryPhone": "6195551234",
      • "fullAddress": "123 Main St, San Diego, CA 92101",
      • "clientInfo": {
        • "serialId": 1023,
        • "fullName": "John Doe",
        • "companyName": "Sample Company name",
        • "email": "client@workiz.com",
        • "primaryPhone": "6195555555",
        • "fullAddress": "123 Main St, New York, NY 10001"
        }
      }
    ]
}

AdGroups

Retrieve a list of Ad Groups

Retrieves a paginated list of Ad Groups.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

disabled
boolean

Filter by disabled state. When true, returns only disabled ad groups; when false, returns only enabled ad groups.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "AG-71b8d7310acbf8cc",
      • "name": "Group A",
      • "displayOrder": 1,
      • "description": "This is a sample ad group.",
      • "disabled": false
      }
    ]
}

Create a new Ad Group

Creates a new Ad Group and returns the created Ad Group object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Ad Group data to create.

name
required
string

The name of the ad group.

displayOrder
required
number

The position of the ad group in the display list.

description
string

The description of the ad group.

disabled
boolean

Indicates whether the ad group is disabled or not.

Responses

Request samples

Content type
application/json
{
  • "name": "Group 1",
  • "displayOrder": 1,
  • "description": "This is an ad group.",
  • "disabled": false
}

Response samples

Content type
application/json
{
  • "id": "AG-71b8d7310acbf8cc",
  • "name": "Group A",
  • "displayOrder": 1,
  • "description": "This is a sample ad group.",
  • "disabled": false
}

Retrieve a single Ad Group

Retrieves a single Ad Group by its ID.

path Parameters
id
required
string
Example: AG-71b8d7310acbf8cc

The ad group ID (prefix AG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "AG-71b8d7310acbf8cc",
  • "name": "Group A",
  • "displayOrder": 1,
  • "description": "This is a sample ad group.",
  • "disabled": false
}

Update an existing Ad Group

Updates an existing Ad Group and returns the updated Ad Group.

path Parameters
id
required
string
Example: AG-71b8d7310acbf8cc

The ad group ID (prefix AG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Ad Group fields to update.

name
string

The name of the ad group.

displayOrder
number

The position of the ad group in the display list.

description
string

The description of the ad group.

disabled
boolean

Indicates whether the ad group is disabled or not.

Responses

Request samples

Content type
application/json
{
  • "name": "Group 1",
  • "displayOrder": 1,
  • "description": "This is an ad group.",
  • "disabled": false
}

Response samples

Content type
application/json
{
  • "id": "AG-71b8d7310acbf8cc",
  • "name": "Group A",
  • "displayOrder": 1,
  • "description": "This is a sample ad group.",
  • "disabled": false
}

Disable an Ad Group

Disables an Ad Group by its ID.

path Parameters
id
required
string
Example: AG-71b8d7310acbf8cc

The ad group ID (prefix AG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Availability

Retrieve booking availability Beta

Beta: This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.

Returns the list of available booking slots for the account within the requested date range.

Only slots that still have open capacity are returned, so a day with no returned slots is fully booked or unavailable.

Each slot includes a userIds array containing the IDs of users who are already occupying capacity in that slot.

Use jobTypes to restrict availability to the technicians who can perform those job types, and availableBased/totalSpots/scheduleOffset/showHolidays to override account booking settings for the request without changing them.

The range cannot exceed 60 days.

query Parameters
startDate
string
Example: startDate=2026-01-15

The first date of the range to return availability for, in YYYY-MM-DD format. Defaults to today when omitted.

endDate
string
Example: endDate=2026-01-31

The last date of the range to return availability for, in YYYY-MM-DD format. Must be on or after the start date, and the range cannot exceed 60 days. Defaults to 31 days after the start date when omitted.

slotLength
number
Example: slotLength=60

The slot length in minutes. Must be between 30 and 480 (8 hours) in steps of 30. Defaults to the account configured slot length when omitted.

jobTypes
string
Example: jobTypes=JT-8718036049ec4c4d

Comma-separated list of job type IDs (prefix JT-). When provided, availability is restricted to the technicians who can perform any of those job types.

availableBased
number
Example: availableBased=1

Overrides the account capacity mode for this request only: 0 = no capacity limit, 1 = based on available technicians, 2 = maximum jobs per slot. Defaults to the account configured mode when omitted.

totalSpots
number
Example: totalSpots=3

Overrides the total capacity per slot for this request only. Mainly useful together with availableBased=2 to set the maximum jobs per slot without changing the account settings.

scheduleOffset
number
Example: scheduleOffset=24

Overrides the minimum notice window in hours for this request only. Allowed values: 0 (none), 1–10 (hours), or 24/48/72/96/120/144/168 (1–7 days). Slots earlier than now plus this offset are excluded. Defaults to the account configured schedule offset when omitted.

showHolidays
number
Example: showHolidays=1

Overrides whether public holidays block slots for this request only: 0 = ignore holidays, 1 = apply the holiday calendar. Defaults to the account configured setting when omitted.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "totalResults": 100,
  • "data": [
    • {
      • "startTime": "2026-01-15 09:00",
      • "startTimestamp": 1768460400,
      • "slotLength": 60,
      • "totalSpots": 3,
      • "openSpots": 2,
      • "userIds": [
        • "USR-83510a9930f203f4",
        • "USR-a4f86bf1deefec12",
        • "USR-d59dbcd34aa19dce"
        ]
      }
    ]
}

Retrieve blocking entities for a date Beta

Beta: This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.

Returns the entities (jobs, leads, tasks, events, recurrences, time-offs) that are occupying capacity on the requested date, including fully booked slots.

Use this endpoint to investigate why a specific date has reduced or no availability. Each entity includes a ID that can be used with the corresponding resource endpoint.

query Parameters
date
required
string
Example: date=2026-01-15

The date to retrieve blocking entities for, in YYYY-MM-DD format. Cannot be in the past.

slotLength
number
Example: slotLength=60

The slot length in minutes. Must be between 30 and 480 (8 hours) in steps of 30. Defaults to the account configured slot length when omitted.

jobTypes
string
Example: jobTypes=JT-8718036049ec4c4d

Comma-separated list of job type IDs (prefix JT-). When provided, availability is restricted to the technicians who can perform any of those job types.

availableBased
number
Example: availableBased=1

Overrides the account capacity mode for this request only: 0 = no capacity limit, 1 = based on available technicians, 2 = maximum jobs per slot. Defaults to the account configured mode when omitted.

totalSpots
number
Example: totalSpots=3

Overrides the total capacity per slot for this request only. Mainly useful together with availableBased=2 to set the maximum jobs per slot without changing the account settings.

scheduleOffset
number
Example: scheduleOffset=24

Overrides the minimum notice window in hours for this request only. Allowed values: 0 (none), 1–10 (hours), or 24/48/72/96/120/144/168 (1–7 days). Slots earlier than now plus this offset are excluded. Defaults to the account configured schedule offset when omitted.

showHolidays
number
Example: showHolidays=1

Overrides whether public holidays block slots for this request only: 0 = ignore holidays, 1 = apply the holiday calendar. Defaults to the account configured setting when omitted.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "totalResults": 100,
  • "data": [
    • {
      • "startTime": "2026-01-15 09:00",
      • "startTimestamp": 1768460400,
      • "blockingEntities": [
        • {
          • "type": "job",
          • "id": "JOB-BA5r7o4bqzR9MONa",
          • "name": "Plumbing repair"
          }
        ]
      }
    ]
}

Client Notes

Retrieve a list of Client Notes

Returns a paginated list of notes for the given client, ordered by creation date descending.

path Parameters
clientId
required
string
Example: CL-OvmDp2yvv1yqMwRl

The client ID (prefix CL-).

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "CLN-211d1676f4b90c40",
      • "note": "Customer requested a follow-up call.",
      • "pin": false,
      • "techName": "John Doe",
      • "createdAt": "2021-01-01 00:00:00"
      }
    ]
}

Create a new Client Note

Creates a new note for the given client.

path Parameters
clientId
required
string
Example: CL-OvmDp2yvv1yqMwRl

The client ID (prefix CL-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Client Note data to create.

note
required
string

The note content.

pin
boolean

Whether the note is pinned to the top of the list.

Responses

Request samples

Content type
application/json
{
  • "note": "Customer requested a follow-up call.",
  • "pin": false
}

Response samples

Content type
application/json
{
  • "id": "CLN-211d1676f4b90c40",
  • "note": "Customer requested a follow-up call.",
  • "pin": false,
  • "techName": "John Doe",
  • "createdAt": "2021-01-01 00:00:00"
}

Get a client note by ID

Returns a single note belonging to the given client.

path Parameters
clientId
required
string
Example: CL-OvmDp2yvv1yqMwRl

The client ID (prefix CL-).

noteId
required
string
Example: CLN-211d1676f4b90c40

The client note ID (prefix CLN-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "CLN-211d1676f4b90c40",
  • "note": "Customer requested a follow-up call.",
  • "pin": false,
  • "techName": "John Doe",
  • "createdAt": "2021-01-01 00:00:00"
}

Update a Client Note

Updates the content and/or pinned state of a note belonging to the given client.

path Parameters
clientId
required
string
Example: CL-OvmDp2yvv1yqMwRl

The client ID (prefix CL-).

noteId
required
string
Example: CLN-211d1676f4b90c40

The client note ID (prefix CLN-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Client Note fields to update.

note
string

The note content.

pin
boolean

Whether the note is pinned to the top of the list.

Responses

Request samples

Content type
application/json
{
  • "note": "Customer requested a follow-up call.",
  • "pin": true
}

Response samples

Content type
application/json
{
  • "id": "CLN-211d1676f4b90c40",
  • "note": "Customer requested a follow-up call.",
  • "pin": false,
  • "techName": "John Doe",
  • "createdAt": "2021-01-01 00:00:00"
}

Delete a Client Note

Deletes a note belonging to the given client.

path Parameters
clientId
required
string
Example: CL-OvmDp2yvv1yqMwRl

The client ID (prefix CL-).

noteId
required
string
Example: CLN-211d1676f4b90c40

The client note ID (prefix CLN-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Clients

Retrieve a list of Clients

Returns a paginated list of clients. Supports full-text search, tag filtering, due-balance filtering, sorting, and date-range filtering. Results are sourced from Elasticsearch and include basic contact and address information.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

searchQuery
string
Example: searchQuery=John Doe

Free-text search string matched against full name, company name, full address, parent full name, custom fields, primary phone, and email address.

isDue
string
Enum: "PastDue" "Due"

Filter clients by outstanding balance status. Due returns clients with any open balance; PastDue returns clients whose balance is overdue.

tags
string
Example: tags=TAG-16a94b03317f6e64,TAG-211d1676f4b90c40

Comma-separated list of tag IDs to filter by. Only clients that have all specified tags are returned.

field
string
Enum: "serialId" "firstName" "fullName" "clientCompany" "primaryPhone"

Field to sort results by. When omitted the default sort is by serialId descending.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending
  • order=DESC - Descending (default)

Sort direction. Defaults to DESC.

dateProperty
string
Value: "created"

The client date field to apply the date filter to. Must be combined with dateOperator and date.

dateOperator
string
Enum: "prev" "next" "between"
Examples:
  • dateOperator=prev - On or before the given date
  • dateOperator=next - On or after the given date
  • dateOperator=between - Between two dates (maximum range: 1 year)

Comparison operator for the date filter. Must be combined with dateProperty and date.

date
string
Examples:
  • date=2025-01-13 - prev: Filter clients by dateProperty before date
  • date=2025-01-13 - next: Filter clients by dateProperty after date
  • date=2025-01-13_2025-01-14 - between: Filter clients by dateProperty between dates max 1 year

Date value(s) for the filter. Format depends on dateOperator: prev / next accept a single date (YYYY-MM-DD); between accepts two dates separated by _ (YYYY-MM-DD_YYYY-MM-DD).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "CL-OvmDp2yvv1yqMwRl",
      • "serialId": 1023,
      • "firstName": "John",
      • "lastName": "Doe",
      • "fullName": "John Doe",
      • "companyName": "John Doe Inc.",
      • "email": "john.doe@example.com",
      • "primaryExt": "123",
      • "primaryPhone": "1234567890",
      • "secondaryExt": "456",
      • "secondaryPhone": "1234567890",
      • "country": "USA",
      • "state": "NY",
      • "city": "New York",
      • "zipcode": "10001",
      • "unit": "100",
      • "address": "123 Main St",
      • "fullAddress": "123 Main St, New York, NY 10001",
      • "clientContacts": [
        • {
          • "firstName": "John",
          • "lastName": "Doe",
          • "fullName": "John Doe",
          • "email": "john.doe@example.com",
          • "primaryPhone": "1234567890",
          • "secondaryPhone": "1234567890",
          • "country": "USA",
          • "state": "NY",
          • "city": "New York",
          • "zipcode": "10001",
          • "address": "123 Main St",
          • "role": "Property Manager",
          • "note": "Prefers contact by email."
          }
        ],
      • "created": "2026-01-01 00:00:00"
      }
    ]
}

Create a new Client Beta

Beta: This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.

Creates a new client and returns the created client object. Either email or primaryPhone must be provided. The client's service location is created from addressDetails. Optionally accepts a billing address, an ad group, a parent client, tax exemption details, and custom field values.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Client data to create.

firstName
required
string

The first name of the client.

lastName
string

The last name of the client.

companyName
string

The company name of the client.

email
string

The email address of the client. Either email or primaryPhone must be provided.

primaryExt
string

The extension number for the primary phone number.

primaryPhone
string

The primary phone number of the client. Either email or primaryPhone must be provided.

secondaryExt
string

The extension number for the secondary phone number.

secondaryPhone
string

The secondary phone number of the client.

object

The service address details of the client. When provided, a service location is created for the client.

object

The billing address details of the client. When different from the service address, a separate billing location is created.

adGroupId
string

The ID of the ad group (prefix AG-).

allowBilling
boolean

Whether the client allows billing. Defaults to the account-level setting when omitted.

parentClientId
string

The ID of the parent client (prefix CL-). The created client is set as a sub-client of it.

taxExempt
boolean

Whether the client is tax exempt.

taxExemptReason
string
Enum: "1" "2" "3" "4" "5" "6" "7" "8" "9" "10" "11" "12" "13" "14" "15" "99"

The tax exemption reason code. Can only be provided when taxExempt is true; defaults to 99 (Other) when taxExempt is true and no reason is provided. Allowed values: 1 = Federal Government, 2 = State Government, 3 = Local Government, 4 = Tribal Government, 5 = Charitable Organization, 6 = Religious Organization, 7 = Educational Organization, 8 = Hospital, 9 = Resale, 10 = Direct Pay Permit, 11 = Multiple Points Of Use, 12 = Direct Mail, 13 = Agricultural Production, 14 = Industrial Production / Manufacturing, 15 = Foreign Diplomat, 99 = Other.

description
string

The description of the client.

Array of objects (CustomFieldValueV2Dto)

The custom fields of the client.

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "companyName": "Example Inc.",
  • "email": "john.doe@example.com",
  • "primaryExt": "123",
  • "primaryPhone": "1234567890",
  • "secondaryExt": "456",
  • "secondaryPhone": "1234567890",
  • "addressDetails": {
    • "country": "US",
    • "state": "NY",
    • "city": "New York",
    • "zipCode": "10001",
    • "address": "123 Main St",
    • "unit": "100"
    },
  • "billingAddressDetails": {
    • "country": "US",
    • "state": "NY",
    • "city": "New York",
    • "zipCode": "10001",
    • "address": "123 Main St",
    • "unit": "100"
    },
  • "adGroupId": "AG-59kGnmvvyamryw1O",
  • "allowBilling": true,
  • "parentClientId": "CL-OvmDp2yvv1yqMwRl",
  • "taxExempt": false,
  • "taxExemptReason": "9",
  • "description": "This is a description",
  • "customFields": [
    • {
      • "id": "CF-DNr3zVoKWod6abEn",
      • "value": "test"
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "CL-OvmDp2yvv1yqMwRl",
  • "serialId": 1023,
  • "firstName": "John",
  • "lastName": "Doe",
  • "fullName": "John Doe",
  • "companyName": "John Doe Inc.",
  • "email": "john.doe@example.com",
  • "primaryExt": "123",
  • "primaryPhone": "1234567890",
  • "secondaryExt": "456",
  • "secondaryPhone": "1234567890",
  • "country": "USA",
  • "state": "NY",
  • "city": "New York",
  • "zipcode": "10001",
  • "unit": "100",
  • "address": "123 Main St",
  • "serviceAddress": "123 Main St, New York, NY 10001",
  • "billingAddress": "123 Main St, New York, NY 10001",
  • "allowBilling": true,
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "tags": [
    • {
      • "id": "TAG-211d1676f4b90c40",
      • "name": "Tag 1",
      • "color": "#edce4c"
      }
    ],
  • "parentClient": {
    • "id": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John",
    • "lastName": "Doe",
    • "fullName": "John Doe",
    • "companyName": "John Doe Inc.",
    • "email": "john.doe@example.com",
    • "primaryExt": "123",
    • "primaryPhone": "1234567890",
    • "secondaryExt": "456",
    • "secondaryPhone": "1234567890",
    • "country": "USA",
    • "state": "NY",
    • "city": "New York",
    • "zipcode": "10001",
    • "unit": "100",
    • "address": "123 Main St",
    • "serviceAddress": "123 Main St, New York, NY 10001",
    • "billingAddress": "123 Main St, New York, NY 10001",
    • "allowBilling": true
    },
  • "clientContacts": [
    • {
      • "id": "CLC-211d1676f4b90c40",
      • "firstName": "John",
      • "lastName": "Doe",
      • "fullName": "John Doe",
      • "email": "john.doe@example.com",
      • "primaryPhone": "1234567890",
      • "secondaryPhone": "1234567890",
      • "country": "USA",
      • "state": "NY",
      • "city": "New York",
      • "zipcode": "10001",
      • "address": "123 Main St",
      • "role": "Property Manager",
      • "note": "Prefers contact by email."
      }
    ],
  • "notes": [
    • {
      • "id": "CLN-211d1676f4b90c40",
      • "note": "Customer requested a follow-up call.",
      • "techName": "John Doe",
      • "createdAt": "2021-01-01 00:00:00"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "created": "2026-01-01 00:00:00"
}

Get a client by ID

Returns a single client including full contact details, service and billing addresses, tags, ad group, notes, additional contacts, and custom field values.

path Parameters
id
required
string
Example: CL-OvmDp2yvv1yqMwRl

The client ID (prefix CL-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "CL-OvmDp2yvv1yqMwRl",
  • "serialId": 1023,
  • "firstName": "John",
  • "lastName": "Doe",
  • "fullName": "John Doe",
  • "companyName": "John Doe Inc.",
  • "email": "john.doe@example.com",
  • "primaryExt": "123",
  • "primaryPhone": "1234567890",
  • "secondaryExt": "456",
  • "secondaryPhone": "1234567890",
  • "country": "USA",
  • "state": "NY",
  • "city": "New York",
  • "zipcode": "10001",
  • "unit": "100",
  • "address": "123 Main St",
  • "serviceAddress": "123 Main St, New York, NY 10001",
  • "billingAddress": "123 Main St, New York, NY 10001",
  • "allowBilling": true,
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "tags": [
    • {
      • "id": "TAG-211d1676f4b90c40",
      • "name": "Tag 1",
      • "color": "#edce4c"
      }
    ],
  • "parentClient": {
    • "id": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John",
    • "lastName": "Doe",
    • "fullName": "John Doe",
    • "companyName": "John Doe Inc.",
    • "email": "john.doe@example.com",
    • "primaryExt": "123",
    • "primaryPhone": "1234567890",
    • "secondaryExt": "456",
    • "secondaryPhone": "1234567890",
    • "country": "USA",
    • "state": "NY",
    • "city": "New York",
    • "zipcode": "10001",
    • "unit": "100",
    • "address": "123 Main St",
    • "serviceAddress": "123 Main St, New York, NY 10001",
    • "billingAddress": "123 Main St, New York, NY 10001",
    • "allowBilling": true
    },
  • "clientContacts": [
    • {
      • "id": "CLC-211d1676f4b90c40",
      • "firstName": "John",
      • "lastName": "Doe",
      • "fullName": "John Doe",
      • "email": "john.doe@example.com",
      • "primaryPhone": "1234567890",
      • "secondaryPhone": "1234567890",
      • "country": "USA",
      • "state": "NY",
      • "city": "New York",
      • "zipcode": "10001",
      • "address": "123 Main St",
      • "role": "Property Manager",
      • "note": "Prefers contact by email."
      }
    ],
  • "notes": [
    • {
      • "id": "CLN-211d1676f4b90c40",
      • "note": "Customer requested a follow-up call.",
      • "techName": "John Doe",
      • "createdAt": "2021-01-01 00:00:00"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "created": "2026-01-01 00:00:00"
}

Custom Fields

Retrieve a list of Custom Fields

Retrieves a paginated list of Custom Fields, optionally filtered by entity type.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

entityType
string
Enum: "JOB" "CLIENT"

Filter results by the entity the custom field belongs to.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "entityType": "JOB",
      • "name": "Custom Field 1",
      • "type": "Text",
      • "groupId": "CFG-eYLPK7198xVp6Z8q",
      • "jobTypes": [
        • {
          • "id": "JT-8718036049ec4c4d",
          • "name": "Repair"
          }
        ],
      • "options": [
        • "option 1",
        • "option 2",
        • "option 3"
        ],
      • "position": 1,
      • "required": false,
      • "requiredClose": false,
      • "searchable": false
      }
    ]
}

Create a new Custom Field

Creates a new Custom Field and returns the created Custom Field.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Custom Field data to create.

entityType
required
string
Enum: "JOB" "CLIENT"

The entity type of the custom field.

name
required
string

The custom field name.

type
required
string
Enum: "Text" "Number" "Date" "Drop Down" "Checkbox" "Large Text" "File Upload"

The type of the custom field.

groupId
string

The ID of the custom fields group (prefix CFG-). Use -1 for no group. Defaults to -1.

jobTypes
Array of strings

Array of job type IDs to associate with the custom field (prefix JT-).

options
Array of strings

The options of the custom field (Drop Down type only).

position
number

The position of the custom field.

required
boolean

Indicates whether the custom field is required or not. (job only)

requiredClose
boolean

Indicates whether the custom field is required to close the job. (job only)

searchable
boolean

Indicates whether the custom field is searchable or not.

Responses

Request samples

Content type
application/json
{
  • "entityType": "JOB",
  • "name": "Custom Field 1",
  • "type": "Text",
  • "groupId": "CFG-KMYQvPr0GZWwke3z",
  • "jobTypes": [
    • "JT-KMYQvPr0GZWwke3z",
    • "JT-AMYQvPr0GZWwke4a"
    ],
  • "options": [
    • "option 1",
    • "option 2",
    • "option 3"
    ],
  • "position": 1,
  • "required": false,
  • "requiredClose": false,
  • "searchable": false
}

Response samples

Content type
application/json
{
  • "id": "CF-eYLPK7198xVp6Z8q",
  • "entityType": "JOB",
  • "name": "Custom Field 1",
  • "type": "Text",
  • "groupId": "CFG-eYLPK7198xVp6Z8q",
  • "jobTypes": [
    • {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      }
    ],
  • "options": [
    • "option 1",
    • "option 2",
    • "option 3"
    ],
  • "position": 1,
  • "required": false,
  • "requiredClose": false,
  • "searchable": false
}

Retrieve a single Custom Field

Retrieves a single Custom Field by its ID.

path Parameters
id
required
string
Example: CF-eYLPK7198xVp6Z8q

The custom field ID (prefix CF-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "CF-eYLPK7198xVp6Z8q",
  • "entityType": "JOB",
  • "name": "Custom Field 1",
  • "type": "Text",
  • "groupId": "CFG-eYLPK7198xVp6Z8q",
  • "jobTypes": [
    • {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      }
    ],
  • "options": [
    • "option 1",
    • "option 2",
    • "option 3"
    ],
  • "position": 1,
  • "required": false,
  • "requiredClose": false,
  • "searchable": false
}

Update an existing Custom Field

Updates an existing Custom Field and returns the updated object.

path Parameters
id
required
string
Example: CF-eYLPK7198xVp6Z8q

The custom field ID (prefix CF-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Custom Field fields to update.

name
string

The custom field name.

groupId
string

The ID of the custom fields group (prefix CFG-). Use -1 for no group. Defaults to -1.

jobTypes
Array of strings

Array of job type IDs to associate with the custom field (prefix JT-).

options
Array of strings

The options of the custom field (Drop Down type only).

position
number

The position of the custom field.

required
boolean

Indicates whether the custom field is required or not. (job only)

requiredClose
boolean

Indicates whether the custom field is required to close the job. (job only)

searchable
boolean

Indicates whether the custom field is searchable or not.

Responses

Request samples

Content type
application/json
{
  • "name": "Custom Field 1",
  • "groupId": "CFG-KMYQvPr0GZWwke3z",
  • "jobTypes": [
    • "JT-KMYQvPr0GZWwke3z",
    • "JT-AMYQvPr0GZWwke4a"
    ],
  • "options": [
    • "option 1",
    • "option 2",
    • "option 3"
    ],
  • "position": 1,
  • "required": false,
  • "requiredClose": false,
  • "searchable": false
}

Response samples

Content type
application/json
{
  • "id": "CF-eYLPK7198xVp6Z8q",
  • "entityType": "JOB",
  • "name": "Custom Field 1",
  • "type": "Text",
  • "groupId": "CFG-eYLPK7198xVp6Z8q",
  • "jobTypes": [
    • {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      }
    ],
  • "options": [
    • "option 1",
    • "option 2",
    • "option 3"
    ],
  • "position": 1,
  • "required": false,
  • "requiredClose": false,
  • "searchable": false
}

Delete a Custom Field

Deletes a Custom Field by its ID.

path Parameters
id
required
string
Example: CF-eYLPK7198xVp6Z8q

The custom field ID (prefix CF-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Custom Fields Groups

Retrieve a list of Custom Fields Groups

Retrieves a paginated list of Custom Fields Groups, optionally filtered by entity type.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

entityType
string
Enum: "JOB" "CLIENT"

Filter results by the entity the custom fields group belongs to.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "CFG-eYLPK7198xVp6Z8q",
      • "entityType": "JOB",
      • "name": "Custom Fields Group 1"
      }
    ]
}

Create a new Custom Fields Group

Creates a new Custom Fields Group and returns the created Custom Fields Group.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Custom Fields Group data to create.

entityType
required
string
Enum: "JOB" "CLIENT"

The entity type of the custom fields group.

name
required
string

The custom fields group name.

Responses

Request samples

Content type
application/json
{
  • "entityType": "JOB",
  • "name": "Custom Fields Group 1"
}

Response samples

Content type
application/json
{
  • "id": "CFG-eYLPK7198xVp6Z8q",
  • "entityType": "JOB",
  • "name": "Custom Fields Group 1"
}

Retrieve a single Custom Fields Group

Retrieves a single Custom Fields Group by its ID.

path Parameters
id
required
string
Example: CFG-eYLPK7198xVp6Z8q

The custom fields group ID (prefix CFG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "CFG-eYLPK7198xVp6Z8q",
  • "entityType": "JOB",
  • "name": "Custom Fields Group 1"
}

Update an existing Custom Fields Group

Updates an existing Custom Fields Group and returns the updated Custom Fields Group.

path Parameters
id
required
string
Example: CFG-eYLPK7198xVp6Z8q

The custom fields group ID (prefix CFG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Custom Fields Group fields to update.

name
string

The custom fields group name.

Responses

Request samples

Content type
application/json
{
  • "name": "Custom Fields Group 1"
}

Response samples

Content type
application/json
{
  • "id": "CFG-eYLPK7198xVp6Z8q",
  • "entityType": "JOB",
  • "name": "Custom Fields Group 1"
}

Delete a Custom Fields Group

Deletes a Custom Fields Group by its ID.

path Parameters
id
required
string
Example: CFG-eYLPK7198xVp6Z8q

The custom fields group ID (prefix CFG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Estimates

Retrieve a list of Estimates

Retrieves a paginated list of Estimates, optionally filtered by date range.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Value: "created"

Beta: This property is subject to change and may contain bugs.

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

Beta: This property is subject to change and may contain bugs.

The sort direction. Must be combined with field. Defaults to DESC.

dateProperty
string
Enum: "updated" "created"

The estimate date field to apply the date filter to. Must be combined with dateOperator and date.

dateOperator
string
Enum: "prev" "next" "between"
Examples:
  • dateOperator=prev - On or before the given date
  • dateOperator=next - On or after the given date
  • dateOperator=between - Between two dates (maximum range: 1 year)

Comparison operator for the date filter. Must be combined with dateProperty and date.

date
string
Examples:
  • date=2025-01-13 - prev: Filter estimates before date
  • date=2025-01-13 - next: Filter estimates after date
  • date=2025-01-13_2025-01-14 - between: Filter estimates between dates (max 1 year)

Date value(s) for the filter. Format depends on dateOperator: prev / next accept a single date (YYYY-MM-DD); between accepts two dates separated by _ (YYYY-MM-DD_YYYY-MM-DD).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "ES-LwqGJnRwvZPaNe5E",
      • "status": "Pending",
      • "serialId": "1-1",
      • "name": "Estimate 1",
      • "description": "This is a description for the estimate",
      • "notes": "This is a note for the estimate",
      • "imageUrl": "https://example.com/image.png",
      • "clientId": "CL-LwqGJnRwvZPaNe5E",
      • "jobId": "JOB-BA5r7o4bqzR9MONa",
      • "taxPercent": 10,
      • "taxableAmount": 100,
      • "taxAmount": 10,
      • "isDepositPercentage": true,
      • "deposit": 100,
      • "subTotal": 10,
      • "total": 10,
      • "declineReason": "This is a decline reason for the estimate",
      • "sentDate": "2026-01-01 00:00:00",
      • "estimateDate": "2026-01-01 00:00:00",
      • "lastViewedDate": "2026-01-01 00:00:00",
      • "statusUpdatedAt": "2026-01-01 00:00:00",
      • "updated": "2026-01-01 00:00:00",
      • "created": "2026-01-01 00:00:00"
      }
    ]
}

Retrieve a single Estimate

Retrieves a single Estimate by its ID.

path Parameters
id
required
string
Example: ES-LwqGJnRwvZPaNe5E

The estimate ID (prefix ES-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "ES-LwqGJnRwvZPaNe5E",
  • "status": "Pending",
  • "serialId": "1-1",
  • "name": "Estimate 1",
  • "description": "This is a description for the estimate",
  • "notes": "This is a note for the estimate",
  • "imageUrl": "https://example.com/image.png",
  • "clientId": "CL-LwqGJnRwvZPaNe5E",
  • "jobId": "JOB-BA5r7o4bqzR9MONa",
  • "discountAmount": 10,
  • "taxPercent": 10,
  • "taxableAmount": 100,
  • "taxAmount": 10,
  • "isDepositPercentage": true,
  • "deposit": 100,
  • "subTotal": 10,
  • "total": 10,
  • "declineReason": "This is a decline reason for the estimate",
  • "lineItems": [
    • {
      • "id": "ELI-BA5r7o4bqzR9MONa",
      • "productId": 1000,
      • "name": "Deadbolt",
      • "description": "Deadbolt replacement, any color and size",
      • "price": 100,
      • "quantity": 1,
      • "total": 100,
      • "cost": 100,
      • "taxable": true,
      • "discountable": true,
      • "inventoryManaged": true,
      • "inventorySync": true,
      • "optionalConverted": true
      }
    ],
  • "payments": [
    • {
      • "id": "PAY-BA5r7o4bqzR9MONa",
      • "type": "Cash",
      • "amount": 100,
      • "tipAmount": 10
      }
    ],
  • "attachments": [],
  • "signatureImage": {},
  • "sentDate": "2026-01-01 00:00:00",
  • "estimateDate": "2026-01-01 00:00:00",
  • "lastViewedDate": "2026-01-01 00:00:00",
  • "statusUpdatedAt": "2026-01-01 00:00:00",
  • "updated": "2026-01-01 00:00:00",
  • "created": "2026-01-01 00:00:00"
}

Events

Retrieve a list of Events

Retrieves a paginated list of Events.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Enum: "start" "status"

Beta: This property is subject to change and may contain bugs.

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

Beta: This property is subject to change and may contain bugs.

The sort direction. Must be combined with field. Defaults to DESC.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "EVT-Dxgp7NRjo6kXb5eG",
      • "status": "Done",
      • "title": "Doctor appointment",
      • "description": "Doctor appointment with Dr. Smith",
      • "start": "2024-07-25 09:00:00",
      • "end": "2024-07-25 11:00:00",
      • "isAllDay": false,
      • "techIds": [
        • "USR-83510a9930f203f4",
        • "USR-a4f86bf1deefec12",
        • "USR-d59dbcd34aa19dce"
        ],
      • "isDeleted": false,
      • "updatedAt": "2024-07-25 09:00:00",
      • "createdAt": "2024-07-25 09:00:00"
      }
    ]
}

Create a new Event

Creates a new Event and returns the created Event object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Event data to create.

status
string
Default: "Open"
Enum: "Done" "Open"

The status of the event.

title
required
string

The title of the event.

description
string
Default: ""

The description of the event.

start
required
string

The time & date when the event starts. Must be before the end date.

end
required
string

The time & date when the event ends. Must be after the start date.

isAllDay
boolean
Default: false

Whether the event is an all-day event.

techIds
Array of strings

Array of tech IDs assigned to the event (prefix USR-).

Responses

Request samples

Content type
application/json
{
  • "status": "Open",
  • "title": "Doctor appointment",
  • "description": "Doctor appointment with Dr. Smith",
  • "start": "2024-07-25 09:00:00",
  • "end": "2024-07-25 11:00:00",
  • "isAllDay": false,
  • "techIds": [
    • "USR-83510a9930f203f4",
    • "USR-a4f86bf1deefec12",
    • "USR-d59dbcd34aa19dce"
    ]
}

Response samples

Content type
application/json
{
  • "id": "EVT-Dxgp7NRjo6kXb5eG",
  • "status": "Done",
  • "title": "Doctor appointment",
  • "description": "Doctor appointment with Dr. Smith",
  • "start": "2024-07-25 09:00:00",
  • "end": "2024-07-25 11:00:00",
  • "isAllDay": false,
  • "techIds": [
    • "USR-83510a9930f203f4",
    • "USR-a4f86bf1deefec12",
    • "USR-d59dbcd34aa19dce"
    ],
  • "isDeleted": false,
  • "updatedAt": "2024-07-25 09:00:00",
  • "createdAt": "2024-07-25 09:00:00"
}

Retrieve a single Event

Retrieves a single Event by its ID.

path Parameters
id
required
string
Example: EVT-Dxgp7NRjo6kXb5eG

The event ID (prefix EVT-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "EVT-Dxgp7NRjo6kXb5eG",
  • "status": "Done",
  • "title": "Doctor appointment",
  • "description": "Doctor appointment with Dr. Smith",
  • "start": "2024-07-25 09:00:00",
  • "end": "2024-07-25 11:00:00",
  • "isAllDay": false,
  • "techIds": [
    • "USR-83510a9930f203f4",
    • "USR-a4f86bf1deefec12",
    • "USR-d59dbcd34aa19dce"
    ],
  • "isDeleted": false,
  • "updatedAt": "2024-07-25 09:00:00",
  • "createdAt": "2024-07-25 09:00:00",
  • "attachments": []
}

Update an existing Event

Updates an existing Event and returns the updated Event.

path Parameters
id
required
string
Example: EVT-Dxgp7NRjo6kXb5eG

The event ID (prefix EVT-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Event fields to update.

status
string
Enum: "Done" "Open"

The status of the event.

title
string

The title of the event.

description
string

The description of the event.

start
string

The time & date when the event starts.

end
string

The time & date when the event ends.

isAllDay
boolean

Whether the event is an all-day event.

techIds
Array of strings

Array of tech IDs assigned to the event (prefix USR-). Pass an empty array to remove all technicians.

Responses

Request samples

Content type
application/json
{
  • "status": "Done",
  • "title": "Doctor appointment",
  • "description": "Doctor appointment with Dr. Smith",
  • "start": "2024-07-25 09:00:00",
  • "end": "2024-07-25 11:00:00",
  • "isAllDay": false,
  • "techIds": [
    • "USR-83510a9930f203f4",
    • "USR-a4f86bf1deefec12",
    • "USR-d59dbcd34aa19dce"
    ]
}

Response samples

Content type
application/json
{
  • "id": "EVT-Dxgp7NRjo6kXb5eG",
  • "status": "Done",
  • "title": "Doctor appointment",
  • "description": "Doctor appointment with Dr. Smith",
  • "start": "2024-07-25 09:00:00",
  • "end": "2024-07-25 11:00:00",
  • "isAllDay": false,
  • "techIds": [
    • "USR-83510a9930f203f4",
    • "USR-a4f86bf1deefec12",
    • "USR-d59dbcd34aa19dce"
    ],
  • "isDeleted": false,
  • "updatedAt": "2024-07-25 09:00:00",
  • "createdAt": "2024-07-25 09:00:00"
}

Delete an Event

Deletes an Event by its ID.

path Parameters
id
required
string
Example: EVT-Dxgp7NRjo6kXb5eG

The event ID (prefix EVT-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Invoices

Retrieve a list of Invoices

Retrieves a paginated list of Invoices, optionally filtered by date range.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Value: "created"

Beta: This property is subject to change and may contain bugs.

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

Beta: This property is subject to change and may contain bugs.

The sort direction. Must be combined with field. Defaults to DESC.

dateProperty
string
Enum: "updated" "created"

The invoice date field to apply the date filter to. Must be combined with dateOperator and date.

dateOperator
string
Enum: "prev" "next" "between"
Examples:
  • dateOperator=prev - On or before the given date
  • dateOperator=next - On or after the given date
  • dateOperator=between - Between two dates (maximum range: 1 year)

Comparison operator for the date filter. Must be combined with dateProperty and date.

date
string
Examples:
  • date=2025-01-13 - prev: Filter invoices before date
  • date=2025-01-13 - next: Filter invoices after date
  • date=2025-01-13_2025-01-14 - between: Filter invoices between dates (max 1 year)

Date value(s) for the filter. Format depends on dateOperator: prev / next accept a single date (YYYY-MM-DD); between accepts two dates separated by _ (YYYY-MM-DD_YYYY-MM-DD).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "IV-bK9r2XyZL54aWDR0",
      • "uuid": "3YBIBO",
      • "serialId": 56,
      • "name": "Invoice 1",
      • "notes": "This is a note for the invoice",
      • "jobId": "JOB-BA5r7o4bqzR9MONa",
      • "subTotal": 946,
      • "taxableAmount": 946,
      • "taxPercent": 10.111,
      • "taxAmount": 10.51,
      • "costing": 10.51,
      • "techExpenses": 12.51,
      • "tipAmount": 43.51,
      • "totalPrice": 956.51,
      • "amountDue": 956.51,
      • "amountDueDate": "2026-01-01 10:00:00",
      • "updated": "2026-01-01 00:00:00",
      • "created": "2026-01-01 00:00:00"
      }
    ]
}

Retrieve a single Invoice

Retrieves a single Invoice by its ID.

path Parameters
id
required
string
Example: IV-LwqGJnRwvZPaNe5E

The invoice ID (prefix IV-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "IV-bK9r2XyZL54aWDR0",
  • "uuid": "3YBIBO",
  • "serialId": 56,
  • "name": "Invoice 1",
  • "notes": "This is a note for the invoice",
  • "jobId": "JOB-BA5r7o4bqzR9MONa",
  • "discountAmount": 10,
  • "subTotal": 946,
  • "taxableAmount": 946,
  • "taxPercent": 10.111,
  • "taxAmount": 10.51,
  • "costing": 10.51,
  • "techExpenses": 12.51,
  • "tipAmount": 43.51,
  • "totalPrice": 956.51,
  • "amountDue": 956.51,
  • "amountDueDate": "2026-01-01 10:00:00",
  • "lineItems": [
    • {
      • "id": "ILI-BA5r7o4bqzR9MONa",
      • "productId": 1000,
      • "name": "Deadbolt",
      • "description": "Deadbolt replacement, any color and size",
      • "price": 100,
      • "quantity": 1,
      • "total": 100,
      • "cost": 100,
      • "taxable": true,
      • "discountable": true,
      • "inventoryManaged": true,
      • "inventorySync": true,
      • "optionalConverted": true
      }
    ],
  • "payments": [
    • {
      • "id": "PAY-BA5r7o4bqzR9MONa",
      • "type": "Cash",
      • "amount": 100,
      • "tipAmount": 10
      }
    ],
  • "attachments": [],
  • "signatureImage": {},
  • "updated": "2026-01-01 00:00:00",
  • "created": "2026-01-01 00:00:00"
}

Job Sub Status

Retrieve a list of Job Sub Statuses

Retrieves a paginated list of Job Sub Statuses.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "JSS-BA5r7o4bqzR9MONa",
      • "name": "Follow Up",
      • "parentName": "In progress",
      • "color": "lavender"
      }
    ]
}

Create a new Job Sub Status

Creates a new Job Sub Status and returns the created Job Sub Status object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Job Sub Status data to create.

name
required
string

The name of the job sub status.

parentName
required
string
Enum: "In progress" "Canceled" "Pending" "done pending approval"

The name of the parent job status.

color
required
string
Enum: "silver" "blue" "green" "orange" "red" "anthracite" "grey" "azure" "denim" "royalBlue" "crimson" "cerise" "apricot" "cream" "bronze" "yellow" "emerald" "forest" "purple" "plum" "lavender" "violet" "slate"

The color key for the job sub status. Available colors:
silver: #cccccc
blue: #004795
green: #6d960c
orange: #cc9707
red: #e35a36
anthracite: #282e36
grey: #666666
azure: #3589E9
denim: #24589B
royalBlue: #000ED2
crimson: #B91C1C
cerise: #E11D48
apricot: #FBAB33
cream: #E8CF63
bronze: #D58E41
yellow: #FFD400
emerald: #22C55E
forest: #3E802B
purple: #9747FF
plum: #B25494
lavender: #D574E4
violet: #391E86
slate: #3B4B52

Responses

Request samples

Content type
application/json
{
  • "name": "New",
  • "parentName": "In progress",
  • "color": "silver"
}

Response samples

Content type
application/json
{
  • "id": "JSS-BA5r7o4bqzR9MONa",
  • "name": "Follow Up",
  • "parentName": "In progress",
  • "color": "lavender"
}

Retrieve a single Job Sub Status

Retrieves a single Job Sub Status by its ID.

path Parameters
id
required
string
Example: JSS-BA5r7o4bqzR9MONa

The job sub status ID (prefix JSS-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "JSS-BA5r7o4bqzR9MONa",
  • "name": "Follow Up",
  • "parentName": "In progress",
  • "color": "lavender"
}

Update an existing Job Sub Status

Updates an existing Job Sub Status and returns the updated Job Sub Status.

path Parameters
id
required
string
Example: JSS-BA5r7o4bqzR9MONa

The job sub status ID (prefix JSS-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Job Sub Status fields to update.

name
string

The name of the job sub status.

color
string
Enum: "silver" "blue" "green" "orange" "red" "anthracite" "grey" "azure" "denim" "royalBlue" "crimson" "cerise" "apricot" "cream" "bronze" "yellow" "emerald" "forest" "purple" "plum" "lavender" "violet" "slate"

The color key for the job sub status. Available colors:
silver: #cccccc
blue: #004795
green: #6d960c
orange: #cc9707
red: #e35a36
anthracite: #282e36
grey: #666666
azure: #3589E9
denim: #24589B
royalBlue: #000ED2
crimson: #B91C1C
cerise: #E11D48
apricot: #FBAB33
cream: #E8CF63
bronze: #D58E41
yellow: #FFD400
emerald: #22C55E
forest: #3E802B
purple: #9747FF
plum: #B25494
lavender: #D574E4
violet: #391E86
slate: #3B4B52

Responses

Request samples

Content type
application/json
{
  • "name": "New",
  • "color": "silver"
}

Response samples

Content type
application/json
{
  • "id": "JSS-BA5r7o4bqzR9MONa",
  • "name": "Follow Up",
  • "parentName": "In progress",
  • "color": "lavender"
}

Delete a Job Sub Status

Deletes a Job Sub Status by its ID.

path Parameters
id
required
string
Example: JSS-BA5r7o4bqzR9MONa

The job sub status ID (prefix JSS-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Jobs

Retrieve a list of Jobs

Retrieves a paginated list of Jobs, optionally filtered by date range.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Enum: "created" "updated" "statusUpdated" "utcUpdated"

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

The sort direction. Must be combined with field.

isOpen
boolean
Default: false
Example: isOpen=true

When true, returns only open jobs. When false, returns only closed (Canceled or Done) jobs. When omitted, no status filter is applied.

dateProperty
string
Enum: "date" "endDate" "utcUpdated" "created"

The job date field to apply the date filter to. Must be combined with dateOperator and date.

dateOperator
string
Enum: "prev" "next" "between"
Examples:
  • dateOperator=prev - On or before the given date
  • dateOperator=next - On or after the given date
  • dateOperator=between - Between two dates (maximum range: 1 year)

Comparison operator for the date filter. Must be combined with dateProperty and date.

date
string
Examples:
  • date=2025-01-13 - prev: Filter jobs before date
  • date=2025-01-13 - next: Filter jobs after date
  • date=2025-01-13_2025-01-14 - between: Filter jobs between dates (max 1 year)

Date value(s) for the filter. Format depends on dateOperator: prev / next accept a single date (YYYY-MM-DD); between accepts two dates separated by _ (YYYY-MM-DD_YYYY-MM-DD).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "JOB-BA5r7o4bqzR9MONa",
      • "uuid": "3YBIBO",
      • "serialId": 12345,
      • "name": "AC Repair",
      • "status": "Submitted",
      • "subStatus": {
        • "id": "JSS-BA5r7o4bqzR9MONa",
        • "name": "Follow Up"
        },
      • "date": "2022-01-01 10:00:00",
      • "endDate": "2022-01-01 10:00:00",
      • "isAllDay": false,
      • "isScheduled": true,
      • "jobType": {
        • "id": "JT-8718036049ec4c4d",
        • "name": "Repair"
        },
      • "adGroup": {
        • "id": "AG-71b8d7310acbf8cc",
        • "name": "Ad Group 1"
        },
      • "description": "This is a description of the job.",
      • "subTotal": 946,
      • "discountAmount": 10,
      • "taxableAmount": 946,
      • "taxPercent": 10.111,
      • "taxAmount": 10.51,
      • "costing": 10.51,
      • "techExpenses": 12.51,
      • "tipAmount": 43.51,
      • "totalPrice": 956.51,
      • "amountDue": 956.51,
      • "amountDueDate": "2022-01-01 10:00:00",
      • "converted": true,
      • "clientInfo": {
        • "clientId": "CL-OvmDp2yvv1yqMwRl",
        • "serialId": 1023,
        • "firstName": "John Doe",
        • "lastName": "Doe",
        • "companyName": "Sample Company name",
        • "email": "client@workiz.com",
        • "primaryExt": "619",
        • "primaryPhone": "6195555555",
        • "secondaryExt": "613",
        • "secondaryPhone": "6195555555",
        • "addressDetails": {
          • "country": "US",
          • "state": "Ohio",
          • "city": "San Francisco",
          • "zipCode": "94102",
          • "address": "462 Powell St",
          • "unit": "3422",
          • "latitude": -76.2768398,
          • "longitude": 36.9669587,
          • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
          },
        • "serviceArea": {
          • "id": "SA-71b8d7310acbf8cc",
          • "name": "San Francisco"
          }
        },
      • "maskedNumber": {
        • "number": "6195551234",
        • "extension": "042",
        • "secondaryExtension": "043"
        },
      • "team": [
        • {
          • "id": "USR-38c1ee5c4efa38a4",
          • "name": "John Doe"
          }
        ],
      • "lineItems": [
        • {
          • "id": "JLI-BA5r7o4bqzR9MONa",
          • "productId": 1000,
          • "type": "product",
          • "name": "Deadbolt",
          • "description": "Deadbolt replacement, any color and size",
          • "price": 100,
          • "quantity": 1,
          • "total": 100,
          • "cost": 100,
          • "taxable": true,
          • "discountable": true,
          • "inventoryManaged": true,
          • "inventorySync": true,
          • "optionalConverted": true
          }
        ],
      • "payments": [
        • {
          • "id": "PAY-BA5r7o4bqzR9MONa",
          • "type": "Cash",
          • "amount": 100,
          • "tipAmount": 10
          }
        ],
      • "tags": [
        • {
          • "id": "TAG-8cddc18e7b0458fa",
          • "name": "Estimate"
          }
        ],
      • "customFields": [
        • {
          • "id": "CF-eYLPK7198xVp6Z8q",
          • "fieldName": "Custom Field 1",
          • "value": "John Doe"
          }
        ],
      • "notes": [
        • {
          • "id": "JNT-8cddc18e7b0458fa",
          • "techName": "John Doe",
          • "note": "This is a note",
          • "timestamp": "2022-01-01 10:00:00"
          }
        ],
      • "conversionDate": "2022-01-01 10:00:00",
      • "statusUpdated": "2022-01-01 12:00:00",
      • "utcUpdatedAt": "2022-01-01 12:00:00",
      • "updatedAt": "2022-01-01 12:00:00",
      • "createdAt": "2022-01-01 10:00:00"
      }
    ]
}

Create a new Job

Creates a new Job and returns the created Job object.

Client Matching & Creation Logic:

  1. If clientInfo.clientId is provided:

    • The job will be associated with that existing client
    • The existing client's data will be used as defaults for any missing information

  2. If clientInfo.clientId is NOT provided:

    • The system first attempts to locate an existing client by matching:
      • Full name (firstName + lastName)
      • Primary phone
      • Email address
      • Company name
      • Address
    • If a matching client is found, that client will be used for the job
    • If NO matching client is found, a new client will be created using the provided information

    When creating a new client, the following fields in clientInfo become required:

    • firstName: Client's first name
    • email or primaryPhone: At least one contact method (email must be valid when provided)
    • addressDetails: Complete address information (country, state, city, zipCode, address)

Property/Address Logic:

  • If a clientId exists, the system first attempts to find a matching property for that client by comparing the provided address details
  • If a matching property is found on the client, that property will be used
  • If NO matching property is found, a new property will be created using the address details from clientInfo.addressDetails
  • When creating a new property, all address fields (country, state, city, zipCode, address) must be provided

Summary: The system intelligently matches existing clients and properties before creating new ones, ensuring data consistency and avoiding duplicates.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Job data to create.

date
string <date-time>

The scheduled start date and time for the job (Must be before the endDate). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

endDate
string <date-time>

The scheduled end date and time for the job (Must be after the start date). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

isAllDay
boolean

Beta: This property is subject to change and may contain bugs.

Whether the job is an all-day event. Defaults to false.

isScheduled
boolean

Beta: This property is subject to change and may contain bugs.

Whether the job is scheduled. When false, the job is created as unscheduled and date/endDate become optional. Defaults to true.

name
string

The name of the job.

description
string

The description of the job.

timeZone
string

The timezone of the job.

jobTypeId
required
string

The ID of the job type (prefix JT-).

adGroupId
string

The ID of the ad group (prefix AG-).

required
object

The client information including address details.

createdBy
string

The ID of the user who created the job (prefix USR-).

createdDate
string <date-time>

The date and time when the job record was created. If not provided, defaults to the current timestamp.

Array of objects (CustomFieldValueV2Dto)

The custom fields of the job.

Responses

Request samples

Content type
application/json
{
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "name": "AC Repair",
  • "description": "This is a description",
  • "timeZone": "America/New_York",
  • "jobTypeId": "JT-38c1ee5c4efa38a4",
  • "adGroupId": "AG-59kGnmvvyamryw1O",
  • "clientInfo": {
    • "clientId": "CL-Lb2R3vrLxBk3YkOJ",
    • "firstName": "John",
    • "lastName": "Doe",
    • "email": "john.doe@example.com",
    • "companyName": "Example Inc.",
    • "primaryExt": "123",
    • "primaryPhone": "1234567890",
    • "secondaryExt": "123",
    • "secondaryPhone": "1234567890",
    • "addressDetails": {
      • "country": "US",
      • "state": "NY",
      • "city": "New York",
      • "zipCode": "10001",
      • "address": "123 Main St",
      • "unit": "100"
      }
    },
  • "createdBy": "USR-laAe5KNY6DZmEnzV",
  • "createdDate": "2022-01-01 10:00:00",
  • "customFields": [
    • {
      • "id": "CF-DNr3zVoKWod6abEn",
      • "value": "test"
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "JOB-BA5r7o4bqzR9MONa",
  • "uuid": "3YBIBO",
  • "serialId": 12345,
  • "name": "AC Repair",
  • "status": "Submitted",
  • "subStatus": {
    • "id": "JSS-BA5r7o4bqzR9MONa",
    • "name": "Follow Up"
    },
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the job.",
  • "subTotal": 946,
  • "discountAmount": 10,
  • "taxableAmount": 946,
  • "taxPercent": 10.111,
  • "taxAmount": 10.51,
  • "costing": 10.51,
  • "techExpenses": 12.51,
  • "tipAmount": 43.51,
  • "totalPrice": 956.51,
  • "amountDue": 956.51,
  • "amountDueDate": "2022-01-01 10:00:00",
  • "converted": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "maskedNumber": {
    • "number": "6195551234",
    • "extension": "042",
    • "secondaryExtension": "043"
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "lineItems": [
    • {
      • "id": "JLI-BA5r7o4bqzR9MONa",
      • "productId": 1000,
      • "type": "product",
      • "name": "Deadbolt",
      • "description": "Deadbolt replacement, any color and size",
      • "price": 100,
      • "quantity": 1,
      • "total": 100,
      • "cost": 100,
      • "taxable": true,
      • "discountable": true,
      • "inventoryManaged": true,
      • "inventorySync": true,
      • "optionalConverted": true
      }
    ],
  • "payments": [
    • {
      • "id": "PAY-BA5r7o4bqzR9MONa",
      • "type": "Cash",
      • "amount": 100,
      • "tipAmount": 10
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "conversionDate": "2022-01-01 10:00:00",
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00",
  • "attachments": []
}

Retrieve a single Job

Retrieves a single Job by its ID.

path Parameters
id
required
string
Example: JOB-BA5r7o4bqzR9MONa

The job ID (prefix JOB-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "JOB-BA5r7o4bqzR9MONa",
  • "uuid": "3YBIBO",
  • "serialId": 12345,
  • "name": "AC Repair",
  • "status": "Submitted",
  • "subStatus": {
    • "id": "JSS-BA5r7o4bqzR9MONa",
    • "name": "Follow Up"
    },
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the job.",
  • "subTotal": 946,
  • "discountAmount": 10,
  • "taxableAmount": 946,
  • "taxPercent": 10.111,
  • "taxAmount": 10.51,
  • "costing": 10.51,
  • "techExpenses": 12.51,
  • "tipAmount": 43.51,
  • "totalPrice": 956.51,
  • "amountDue": 956.51,
  • "amountDueDate": "2022-01-01 10:00:00",
  • "converted": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "maskedNumber": {
    • "number": "6195551234",
    • "extension": "042",
    • "secondaryExtension": "043"
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "lineItems": [
    • {
      • "id": "JLI-BA5r7o4bqzR9MONa",
      • "productId": 1000,
      • "type": "product",
      • "name": "Deadbolt",
      • "description": "Deadbolt replacement, any color and size",
      • "price": 100,
      • "quantity": 1,
      • "total": 100,
      • "cost": 100,
      • "taxable": true,
      • "discountable": true,
      • "inventoryManaged": true,
      • "inventorySync": true,
      • "optionalConverted": true
      }
    ],
  • "payments": [
    • {
      • "id": "PAY-BA5r7o4bqzR9MONa",
      • "type": "Cash",
      • "amount": 100,
      • "tipAmount": 10
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "conversionDate": "2022-01-01 10:00:00",
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00",
  • "attachments": []
}

Update an existing Job

Updates an existing Job and returns the updated Job.

path Parameters
id
required
string
Example: JOB-BA5r7o4bqzR9MONa

The job ID (prefix JOB-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Job fields to update.

status
string
Enum: "Submitted" "In progress" "Pending" "done pending approval" "Canceled" "Done"

The status of the job.

subStatusId
string

The ID of the job sub status (prefix JSS-).

date
string <date-time>

The scheduled start date and time for the job (Must be before the endDate). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

endDate
string <date-time>

The scheduled end date and time for the job (Must be after the start date). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

isAllDay
boolean

Beta: This property is subject to change and may contain bugs.

Whether the job is an all-day event. When omitted, the current value is left unchanged.

isScheduled
boolean

Beta: This property is subject to change and may contain bugs.

Whether the job is scheduled. When false, the job is marked as unscheduled. When omitted, the current schedule state is left unchanged.

name
string

The name of the job.

description
string

The description of the job.

timeZone
string

The timezone of the job.

jobTypeId
string

The ID of the job type (prefix JT-).

adGroupId
string

The ID of the ad group (prefix AG-).

object

The client information including address details.

createdBy
string

The ID of the user who created the job (prefix USR-).

tags
Array of strings

Array of tag IDs to assign to the job (prefix TAG-).

Array of objects (CustomFieldValueV2Dto)

The custom fields of the job.

Responses

Request samples

Content type
application/json
{
  • "status": "Submitted",
  • "subStatusId": "JSS-BA5r7o4bqzR9MONa",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "name": "AC Repair",
  • "description": "This is a description",
  • "timeZone": "America/New_York",
  • "jobTypeId": "JT-38c1ee5c4efa38a4",
  • "adGroupId": "AG-59kGnmvvyamryw1O",
  • "clientInfo": {
    • "firstName": "John",
    • "lastName": "Doe",
    • "email": "john.doe@example.com",
    • "companyName": "Example Inc.",
    • "primaryExt": "123",
    • "primaryPhone": "1234567890",
    • "secondaryExt": "123",
    • "secondaryPhone": "1234567890",
    • "addressDetails": {
      • "country": "US",
      • "state": "NY",
      • "city": "New York",
      • "zipCode": "10001",
      • "address": "123 Main St",
      • "unit": "100"
      }
    },
  • "createdBy": "USR-laAe5KNY6DZmEnzV",
  • "tags": [
    • "TAG-16a94b03317f6e64"
    ],
  • "customFields": [
    • {
      • "id": "CF-DNr3zVoKWod6abEn",
      • "value": "test"
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "JOB-BA5r7o4bqzR9MONa",
  • "uuid": "3YBIBO",
  • "serialId": 12345,
  • "name": "AC Repair",
  • "status": "Submitted",
  • "subStatus": {
    • "id": "JSS-BA5r7o4bqzR9MONa",
    • "name": "Follow Up"
    },
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the job.",
  • "subTotal": 946,
  • "discountAmount": 10,
  • "taxableAmount": 946,
  • "taxPercent": 10.111,
  • "taxAmount": 10.51,
  • "costing": 10.51,
  • "techExpenses": 12.51,
  • "tipAmount": 43.51,
  • "totalPrice": 956.51,
  • "amountDue": 956.51,
  • "amountDueDate": "2022-01-01 10:00:00",
  • "converted": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "maskedNumber": {
    • "number": "6195551234",
    • "extension": "042",
    • "secondaryExtension": "043"
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "lineItems": [
    • {
      • "id": "JLI-BA5r7o4bqzR9MONa",
      • "productId": 1000,
      • "type": "product",
      • "name": "Deadbolt",
      • "description": "Deadbolt replacement, any color and size",
      • "price": 100,
      • "quantity": 1,
      • "total": 100,
      • "cost": 100,
      • "taxable": true,
      • "discountable": true,
      • "inventoryManaged": true,
      • "inventorySync": true,
      • "optionalConverted": true
      }
    ],
  • "payments": [
    • {
      • "id": "PAY-BA5r7o4bqzR9MONa",
      • "type": "Cash",
      • "amount": 100,
      • "tipAmount": 10
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "conversionDate": "2022-01-01 10:00:00",
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00",
  • "attachments": []
}

Retrieve a list of Job Technicians

Retrieves a paginated list of technicians assigned to a job.

path Parameters
jobId
required
string
Example: JOB-BA5r7o4bqzR9MONa

The Job ID

query Parameters
pageSize
number
Example: pageSize=10

The page size

page
number
Example: page=1

The page number

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "USR-BA5r7o4bqzR9MONa",
      • "name": "John Doe",
      • "emailAddress": "john.doe@example.com",
      • "isPrimary": true
      }
    ]
}

Assign a Technician to a Job

Assigns a technician to a job. If the account does not have multi-technician enabled, use replace: true to replace the existing technician.

path Parameters
jobId
required
string
Example: JOB-BA5r7o4bqzR9MONa

The Job ID

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required
technitionId
required
string

The ID of the technician (prefix USR-).

isPrimary
boolean

Whether the technician is the primary technician.

replace
boolean

Whether to replace the existing technician, works only if the option "Allow Multiple Technicians" is disabled in the account settings.

Responses

Request samples

Content type
application/json
{
  • "technitionId": "USR-BA5r7o4bqzR9MONa",
  • "isPrimary": true,
  • "replace": true
}

Response samples

Content type
application/json
{
  • "id": "USR-BA5r7o4bqzR9MONa",
  • "name": "John Doe",
  • "emailAddress": "john.doe@example.com",
  • "isPrimary": true
}

Set a Technician as Primary

Sets the specified technician as the primary technician for the job. All other technicians will be set as non-primary.

path Parameters
jobId
required
string
Example: JOB-BA5r7o4bqzR9MONa

The Job ID

userId
required
string
Example: USR-BA5r7o4bqzR9MONa

The User ID

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "USR-BA5r7o4bqzR9MONa",
  • "name": "John Doe",
  • "emailAddress": "john.doe@example.com",
  • "isPrimary": true
}

Unassign a Technician from a Job

Removes the specified technician from the job.

path Parameters
jobId
required
string
Example: JOB-BA5r7o4bqzR9MONa

The Job ID

userId
required
string
Example: USR-BA5r7o4bqzR9MONa

The User ID

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

JobTypes

Retrieve a list of Job Types

Retrieves a paginated list of Job Types.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

disabled
boolean

Filter by disabled state. When true, returns only disabled job types; when false, returns only enabled job types.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Cleaning",
      • "avgDuration": 60,
      • "displayOrder": 1,
      • "disabled": false
      }
    ]
}

Create a new Job Type

Creates a new Job Type and returns the created Job Type object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Job Type data to create.

name
required
string

The name of the job type.

avgDuration
number

The average duration in minutes.

displayOrder
required
number

The position of the job type in the display list.

disabled
boolean

Indicates whether the job type is disabled or not.

applyToSubAccounts
boolean

When true, the job type is also created on all franchise sub-accounts.

Responses

Request samples

Content type
application/json
{
  • "name": "Some type",
  • "avgDuration": 60,
  • "displayOrder": 1,
  • "disabled": false,
  • "applyToSubAccounts": true
}

Response samples

Content type
application/json
{
  • "id": "JT-8718036049ec4c4d",
  • "name": "Cleaning",
  • "avgDuration": 60,
  • "displayOrder": 1,
  • "disabled": false
}

Retrieve a single Job Type

Retrieves a single Job Type by its ID.

path Parameters
id
required
string
Example: JT-8718036049ec4c4d

The job type ID (prefix JT-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "JT-8718036049ec4c4d",
  • "name": "Cleaning",
  • "avgDuration": 60,
  • "displayOrder": 1,
  • "disabled": false
}

Update an existing Job Type

Updates an existing Job Type and returns the updated Job Type.

path Parameters
id
required
string
Example: JT-8718036049ec4c4d

The job type ID (prefix JT-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Job Type fields to update.

name
string

The name of the job type.

avgDuration
number

The average duration in minutes.

displayOrder
number

The position of the job type in the display list.

disabled
boolean

Indicates whether the job type is disabled or not.

applyToSubAccounts
boolean

When true, the update is also applied to matching job types on all franchise sub-accounts.

Responses

Request samples

Content type
application/json
{
  • "name": "Some type",
  • "avgDuration": 60,
  • "displayOrder": 1,
  • "disabled": false,
  • "applyToSubAccounts": true
}

Response samples

Content type
application/json
{
  • "id": "JT-8718036049ec4c4d",
  • "name": "Cleaning",
  • "avgDuration": 60,
  • "displayOrder": 1,
  • "disabled": false
}

Disable a Job Type

Disables a Job Type by its ID.

path Parameters
id
required
string
Example: JT-8718036049ec4c4d

The job type ID (prefix JT-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Lead Status

Retrieve a list of Lead Statuses

Retrieves a list of Lead Statuses.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "totalResults": 10,
  • "hasMore": false,
  • "data": [
    • {
      • "name": "Submitted"
      }
    ]
}

Create a new Lead Status

Creates a new Lead Status and returns the created Lead Status.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Lead Status data to create.

name
required
string

The name of the lead status.

Responses

Request samples

Content type
application/json
{
  • "name": "Submitted"
}

Response samples

Content type
application/json
{
  • "name": "Submitted"
}

Delete a Lead Status

Deletes a Lead Status by its name.

query Parameters
name
required
string
Example: name=Submitted

The name of the Lead Status to delete.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Leads

Retrieve a list of Leads

Retrieves a paginated list of Leads, optionally filtered by date range.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Enum: "created" "updated" "statusUpdated" "utcUpdated"

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

The sort direction. Must be combined with field.

isOpen
boolean
Default: false
Example: isOpen=true

When true, returns only open (not lost) leads. When false, returns only lost leads. When omitted, no filter is applied.

dateProperty
string
Enum: "date" "endDate" "utcUpdated" "created"

The lead date field to apply the date filter to. Must be combined with dateOperator and date.

dateOperator
string
Enum: "prev" "next" "between"
Examples:
  • dateOperator=prev - On or before the given date
  • dateOperator=next - On or after the given date
  • dateOperator=between - Between two dates (maximum range: 1 year)

Comparison operator for the date filter. Must be combined with dateProperty and date.

date
string
Examples:
  • date=2025-01-13 - prev: Filter leads before date
  • date=2025-01-13 - next: Filter leads after date
  • date=2025-01-13_2025-01-14 - between: Filter leads between dates (max 1 year)

Date value(s) for the filter. Format depends on dateOperator: prev / next accept a single date (YYYY-MM-DD); between accepts two dates separated by _ (YYYY-MM-DD_YYYY-MM-DD).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "LD-LwqGJnRwvZPaNe5E",
      • "uuid": "GD87TS",
      • "serialId": 12345,
      • "status": "Submitted",
      • "date": "2022-01-01 10:00:00",
      • "endDate": "2022-01-01 10:00:00",
      • "isAllDay": true,
      • "isScheduled": true,
      • "jobType": {
        • "id": "JT-8718036049ec4c4d",
        • "name": "Repair"
        },
      • "adGroup": {
        • "id": "AG-71b8d7310acbf8cc",
        • "name": "Ad Group 1"
        },
      • "description": "This is a description of the lead.",
      • "leadLost": true,
      • "clientInfo": {
        • "clientId": "CL-OvmDp2yvv1yqMwRl",
        • "serialId": 1023,
        • "firstName": "John Doe",
        • "lastName": "Doe",
        • "companyName": "Sample Company name",
        • "email": "client@workiz.com",
        • "primaryExt": "619",
        • "primaryPhone": "6195555555",
        • "secondaryExt": "613",
        • "secondaryPhone": "6195555555",
        • "addressDetails": {
          • "country": "US",
          • "state": "Ohio",
          • "city": "San Francisco",
          • "zipCode": "94102",
          • "address": "462 Powell St",
          • "unit": "3422",
          • "latitude": -76.2768398,
          • "longitude": 36.9669587,
          • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
          },
        • "serviceArea": {
          • "id": "SA-71b8d7310acbf8cc",
          • "name": "San Francisco"
          }
        },
      • "team": [
        • {
          • "id": "USR-38c1ee5c4efa38a4",
          • "name": "John Doe"
          }
        ],
      • "tags": [
        • {
          • "id": "TAG-8cddc18e7b0458fa",
          • "name": "Estimate"
          }
        ],
      • "customFields": [
        • {
          • "id": "CF-eYLPK7198xVp6Z8q",
          • "fieldName": "Custom Field 1",
          • "value": "John Doe"
          }
        ],
      • "notes": [
        • {
          • "id": "JNT-8cddc18e7b0458fa",
          • "techName": "John Doe",
          • "note": "This is a note",
          • "timestamp": "2022-01-01 10:00:00"
          }
        ],
      • "statusUpdated": "2022-01-01 12:00:00",
      • "utcUpdatedAt": "2022-01-01 12:00:00",
      • "updatedAt": "2022-01-01 12:00:00",
      • "createdAt": "2022-01-01 10:00:00"
      }
    ]
}

Create a new Lead

Creates a new Lead and returns the created Lead object.

Client Matching & Creation Logic:

  1. If clientInfo.clientId is provided:

    • The lead will be associated with that existing client
    • The existing client's data will be used as defaults for any missing information

  2. If clientInfo.clientId is NOT provided:

    • The system first attempts to locate an existing client by matching:
      • Full name (firstName + lastName)
      • Primary phone
      • Email address
      • Company name
      • Address
    • If a matching client is found, that client will be used for the lead
    • If NO matching client is found, a new client will be created using the provided information

    When creating a new client, the following fields in clientInfo become required:

    • firstName: Client's first name
    • email or primaryPhone: At least one contact method (email must be valid when provided)
    • addressDetails: Complete address information (country, state, city, zipCode, address)

Property/Address Logic:

  • If a clientId exists the system first attempts to find a matching property for that client by comparing the provided address details
  • If a matching property is found on the client, that property will be used
  • If NO matching property is found, a new property will be created using the address details from clientInfo.addressDetails
  • When creating a new property, all address fields (country, state, city, zipCode, address) must be provided

Summary: The system intelligently matches existing clients and properties before creating new ones, ensuring data consistency and avoiding duplicates.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Lead data to create.

date
string <date-time>

The scheduled start date and time for the lead (Must be before the endDate). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

endDate
string <date-time>

The scheduled end date and time for the lead (Must be after the start date). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

isAllDay
boolean

Beta: This property is subject to change and may contain bugs.

Whether the lead is an all-day event. Defaults to false.

isScheduled
boolean

Beta: This property is subject to change and may contain bugs.

Whether the lead is scheduled. When false, the lead is created as unscheduled and date/endDate become optional. Defaults to true.

description
string

The description of the lead.

timeZone
string

The timezone of the lead.

jobTypeId
string

The ID of the job type (prefix JT-).

adGroupId
string

The ID of the ad group (prefix AG-).

required
object

The client information including address details.

createdBy
string

The ID of the user who created the lead (prefix USR-).

createdDate
string <date-time>

The date and time when the lead record was created. If not provided, defaults to the current timestamp.

Array of objects (CustomFieldValueV2Dto)

The custom fields of the lead.

Responses

Request samples

Content type
application/json
{
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "description": "This is a description",
  • "timeZone": "America/New_York",
  • "jobTypeId": "JT-38c1ee5c4efa38a4",
  • "adGroupId": "AG-59kGnmvvyamryw1O",
  • "clientInfo": {
    • "clientId": "CL-Lb2R3vrLxBk3YkOJ",
    • "firstName": "John",
    • "lastName": "Doe",
    • "email": "john.doe@example.com",
    • "companyName": "Example Inc.",
    • "primaryExt": "123",
    • "primaryPhone": "1234567890",
    • "secondaryExt": "123",
    • "secondaryPhone": "1234567890",
    • "addressDetails": {
      • "country": "US",
      • "state": "NY",
      • "city": "New York",
      • "zipCode": "10001",
      • "address": "123 Main St",
      • "unit": "100"
      }
    },
  • "createdBy": "USR-laAe5KNY6DZmEnzV",
  • "createdDate": "2022-01-01 10:00:00",
  • "customFields": [
    • {
      • "id": "CF-DNr3zVoKWod6abEn",
      • "value": "test"
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "LD-LwqGJnRwvZPaNe5E",
  • "uuid": "GD87TS",
  • "serialId": 12345,
  • "status": "Submitted",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": true,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the lead.",
  • "leadLost": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00"
}

Retrieve a single Lead

Retrieves a single Lead by its ID.

path Parameters
id
required
string
Example: LD-LwqGJnRwvZPaNe5E

The lead ID (prefix LD-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "LD-LwqGJnRwvZPaNe5E",
  • "uuid": "GD87TS",
  • "serialId": 12345,
  • "status": "Submitted",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": true,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the lead.",
  • "leadLost": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00"
}

Update an existing Lead

Updates an existing Lead and returns the updated Lead.

path Parameters
id
required
string
Example: LD-LwqGJnRwvZPaNe5E

The lead ID (prefix LD-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Lead fields to update.

status
string
Enum: "new" "scheduled" "in progress" "estimated" "approved" "and any user-defined status"

The status of the lead.

date
string <date-time>

The scheduled start date and time for the lead (Must be before the endDate). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

endDate
string <date-time>

The scheduled end date and time for the lead (Must be after the start date). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.

isAllDay
boolean

Beta: This property is subject to change and may contain bugs.

Whether the lead is an all-day event. When omitted, the current value is left unchanged.

isScheduled
boolean

Beta: This property is subject to change and may contain bugs.

Whether the lead is scheduled. When false, the lead is marked as unscheduled. When omitted, the current schedule state is left unchanged.

description
string

The description of the lead.

timeZone
string

The timezone of the lead.

jobTypeId
string

The ID of the job type (prefix JT-). Pass an empty value to remove the job type from the lead.

adGroupId
string

The ID of the ad group (prefix AG-).

object

The client information including address details.

createdBy
string

The ID of the user who created the lead (prefix USR-).

tags
Array of strings

Array of tag IDs to assign to the lead (prefix TAG-).

Array of objects (CustomFieldValueV2Dto)

The custom fields of the lead.

Responses

Request samples

Content type
application/json
{
  • "status": "new",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "description": "This is a description",
  • "timeZone": "America/New_York",
  • "jobTypeId": "JT-38c1ee5c4efa38a4",
  • "adGroupId": "AG-59kGnmvvyamryw1O",
  • "clientInfo": {
    • "firstName": "John",
    • "lastName": "Doe",
    • "email": "john.doe@example.com",
    • "companyName": "Example Inc.",
    • "primaryExt": "123",
    • "primaryPhone": "1234567890",
    • "secondaryExt": "123",
    • "secondaryPhone": "1234567890",
    • "addressDetails": {
      • "country": "US",
      • "state": "NY",
      • "city": "New York",
      • "zipCode": "10001",
      • "address": "123 Main St",
      • "unit": "100"
      }
    },
  • "createdBy": "USR-laAe5KNY6DZmEnzV",
  • "tags": [
    • "TAG-16a94b03317f6e64"
    ],
  • "customFields": [
    • {
      • "id": "CF-DNr3zVoKWod6abEn",
      • "value": "test"
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "LD-LwqGJnRwvZPaNe5E",
  • "uuid": "GD87TS",
  • "serialId": 12345,
  • "status": "Submitted",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": true,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the lead.",
  • "leadLost": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00"
}

Convert a Lead to a Job

Converts an existing Lead to a Job and returns the resulting Job object.

path Parameters
leadId
required
string
Example: LD-LwqGJnRwvZPaNe5E

The lead ID (prefix LD-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "JOB-BA5r7o4bqzR9MONa",
  • "uuid": "3YBIBO",
  • "serialId": 12345,
  • "name": "AC Repair",
  • "status": "Submitted",
  • "subStatus": {
    • "id": "JSS-BA5r7o4bqzR9MONa",
    • "name": "Follow Up"
    },
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": false,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the job.",
  • "subTotal": 946,
  • "discountAmount": 10,
  • "taxableAmount": 946,
  • "taxPercent": 10.111,
  • "taxAmount": 10.51,
  • "costing": 10.51,
  • "techExpenses": 12.51,
  • "tipAmount": 43.51,
  • "totalPrice": 956.51,
  • "amountDue": 956.51,
  • "amountDueDate": "2022-01-01 10:00:00",
  • "converted": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "maskedNumber": {
    • "number": "6195551234",
    • "extension": "042",
    • "secondaryExtension": "043"
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "lineItems": [
    • {
      • "id": "JLI-BA5r7o4bqzR9MONa",
      • "productId": 1000,
      • "type": "product",
      • "name": "Deadbolt",
      • "description": "Deadbolt replacement, any color and size",
      • "price": 100,
      • "quantity": 1,
      • "total": 100,
      • "cost": 100,
      • "taxable": true,
      • "discountable": true,
      • "inventoryManaged": true,
      • "inventorySync": true,
      • "optionalConverted": true
      }
    ],
  • "payments": [
    • {
      • "id": "PAY-BA5r7o4bqzR9MONa",
      • "type": "Cash",
      • "amount": 100,
      • "tipAmount": 10
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "conversionDate": "2022-01-01 10:00:00",
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00"
}

Activate a Lead Beta

Beta: This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.

Reactivates a lost Lead and returns the updated Lead object.

path Parameters
leadId
required
string
Example: LD-LwqGJnRwvZPaNe5E

The lead ID (prefix LD-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "LD-LwqGJnRwvZPaNe5E",
  • "uuid": "GD87TS",
  • "serialId": 12345,
  • "status": "Submitted",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": true,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the lead.",
  • "leadLost": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00"
}

Mark a Lead as lost Beta

Beta: This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.

Marks an existing Lead as lost and returns the updated Lead object.

path Parameters
leadId
required
string
Example: LD-LwqGJnRwvZPaNe5E

The lead ID (prefix LD-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "LD-LwqGJnRwvZPaNe5E",
  • "uuid": "GD87TS",
  • "serialId": 12345,
  • "status": "Submitted",
  • "date": "2022-01-01 10:00:00",
  • "endDate": "2022-01-01 10:00:00",
  • "isAllDay": true,
  • "isScheduled": true,
  • "jobType": {
    • "id": "JT-8718036049ec4c4d",
    • "name": "Repair"
    },
  • "adGroup": {
    • "id": "AG-71b8d7310acbf8cc",
    • "name": "Ad Group 1"
    },
  • "description": "This is a description of the lead.",
  • "leadLost": true,
  • "clientInfo": {
    • "clientId": "CL-OvmDp2yvv1yqMwRl",
    • "serialId": 1023,
    • "firstName": "John Doe",
    • "lastName": "Doe",
    • "companyName": "Sample Company name",
    • "email": "client@workiz.com",
    • "primaryExt": "619",
    • "primaryPhone": "6195555555",
    • "secondaryExt": "613",
    • "secondaryPhone": "6195555555",
    • "addressDetails": {
      • "country": "US",
      • "state": "Ohio",
      • "city": "San Francisco",
      • "zipCode": "94102",
      • "address": "462 Powell St",
      • "unit": "3422",
      • "latitude": -76.2768398,
      • "longitude": 36.9669587,
      • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
      },
    • "serviceArea": {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    },
  • "team": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Doe"
      }
    ],
  • "tags": [
    • {
      • "id": "TAG-8cddc18e7b0458fa",
      • "name": "Estimate"
      }
    ],
  • "customFields": [
    • {
      • "id": "CF-eYLPK7198xVp6Z8q",
      • "fieldName": "Custom Field 1",
      • "value": "John Doe"
      }
    ],
  • "notes": [
    • {
      • "id": "JNT-8cddc18e7b0458fa",
      • "techName": "John Doe",
      • "note": "This is a note",
      • "timestamp": "2022-01-01 10:00:00"
      }
    ],
  • "statusUpdated": "2022-01-01 12:00:00",
  • "utcUpdatedAt": "2022-01-01 12:00:00",
  • "updatedAt": "2022-01-01 12:00:00",
  • "createdAt": "2022-01-01 10:00:00"
}

Retrieve a list of Lead Technicians

Retrieves a paginated list of technicians assigned to a lead.

path Parameters
leadId
required
string
Example: LD-BA5r7o4bqzR9MONa

The Lead ID

query Parameters
pageSize
number
Example: pageSize=10

The page size

page
number
Example: page=1

The page number

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "USR-BA5r7o4bqzR9MONa",
      • "name": "John Doe",
      • "emailAddress": "john.doe@example.com",
      • "isPrimary": true
      }
    ]
}

Assign a Technician to a Lead

Assigns a technician to a lead. If the account does not have multi-technician enabled, use replace: true to replace the existing technician.

path Parameters
leadId
required
string
Example: LD-BA5r7o4bqzR9MONa

The Lead ID

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required
technitionId
required
string

The ID of the technician (prefix USR-).

isPrimary
boolean

Whether the technician is the primary technician.

replace
boolean

Whether to replace the existing technician, works only if the option "Allow Multiple Technicians" is disabled in the account settings.

Responses

Request samples

Content type
application/json
{
  • "technitionId": "USR-BA5r7o4bqzR9MONa",
  • "isPrimary": true,
  • "replace": true
}

Response samples

Content type
application/json
{
  • "id": "USR-BA5r7o4bqzR9MONa",
  • "name": "John Doe",
  • "emailAddress": "john.doe@example.com",
  • "isPrimary": true
}

Set a Technician as Primary

Sets the specified technician as the primary technician for the lead. All other technicians will be set as non-primary.

path Parameters
leadId
required
string
Example: LD-BA5r7o4bqzR9MONa

The Lead ID

userId
required
string
Example: USR-BA5r7o4bqzR9MONa

The User ID

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "USR-BA5r7o4bqzR9MONa",
  • "name": "John Doe",
  • "emailAddress": "john.doe@example.com",
  • "isPrimary": true
}

Unassign a Technician from a Lead

Removes the specified technician from the lead.

path Parameters
leadId
required
string
Example: LD-BA5r7o4bqzR9MONa

The Lead ID

userId
required
string
Example: USR-BA5r7o4bqzR9MONa

The User ID

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Tags

Retrieve a list of Tags

Retrieves a paginated list of Tags.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

type
string
Enum: "job" "client" "call" "task" "project"
Examples:
  • type=job - Only job tags
  • type=client - Only client tags
  • type=call - Only call tags

Filter tags by type.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "TAG-3e6cca162914f48f",
      • "name": "Opportunity",
      • "color": "#0059a0",
      • "type": "job"
      }
    ]
}

Create a new Tag

Creates a new Tag and returns the created Tag object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Tag data to create.

name
required
string

The name of the tag.

color
required
string
Enum: "#0059a0" "#be2c2c" "#e18a2b" "#37d34d" "#edce4c" "#c04d97" "#198218" "#3d1c8b"

The color of the tag.

type
required
string
Enum: "job" "client" "call" "task" "project"

The type of the tag.

Responses

Request samples

Content type
application/json
{
  • "name": "Opportunity",
  • "color": "#0059a0",
  • "type": "job"
}

Response samples

Content type
application/json
{
  • "id": "TAG-3e6cca162914f48f",
  • "name": "Opportunity",
  • "color": "#0059a0",
  • "type": "job"
}

Update an existing Tag

Updates an existing Tag and returns the updated Tag.

path Parameters
id
required
string
Example: TAG-16a94b03317f6e64

The tag ID (prefix TAG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Tag fields to update.

name
string

The name of the tag.

color
string
Enum: "#0059a0" "#be2c2c" "#e18a2b" "#37d34d" "#edce4c" "#c04d97" "#198218" "#3d1c8b"

The color of the tag.

Responses

Request samples

Content type
application/json
{
  • "name": "Opportunity",
  • "color": "#0059a0"
}

Response samples

Content type
application/json
{
  • "id": "TAG-3e6cca162914f48f",
  • "name": "Opportunity",
  • "color": "#0059a0",
  • "type": "job"
}

Delete a Tag

Deletes a Tag by its ID.

path Parameters
id
required
string
Example: TAG-16a94b03317f6e64

The tag ID (prefix TAG-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

TimeOffs

Retrieve a list of Time Off

Retrieves a paginated list of Time Off based on the applied filters and pagination.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Enum: "id" "techId" "startDate" "endDate" "status" "reason" "details" "isAllDay" "updatedAt" "createdAt"

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

The sort direction. Must be combined with field.

techId
Array of strings
Example: techId=USR-8c65ffdb713ea0ea

Filter by tech ID (prefix USR-). Can be passed multiple times.

baseDate
string <date-time>
Example: baseDate=2025-01-13 13:36:46

The time off start-date boundary for the filter. Must be combined with timeline. Expected format: YYYY-MM-DD HH:MM:SS.

timeline
string
Enum: "prev" "next"
Examples:
  • timeline=prev - Before start date
  • timeline=next - On or after start date

Comparison direction for the date filter. Must be combined with baseDate. prev shows time offs starting before baseDate; next shows time offs starting on or after baseDate.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "TO-de9750285414508f",
      • "techId": "USR-38c1ee5c4efa38a4",
      • "startDate": "2024-07-25 09:00:00",
      • "endDate": "2024-07-25 11:00:00",
      • "status": "approved",
      • "reason": "Vacation",
      • "details": "Doctor appointment",
      • "isAllDay": true,
      • "updatedAt": "2024-07-25 09:00:00",
      • "createdAt": "2024-07-25 09:00:00"
      }
    ]
}

Create a new Time Off

Creates a new Time Off and returns the created Time Off object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Time Off data to create.

techId
required
string

The tech ID to assign the time off to (prefix USR-). Use -1 to assign to all company techs.

startDate
required
string <date-time>

The time & date when the time off starts.

endDate
required
string <date-time>

The time & date when the time off ends.

status
string
Enum: "approved" "pending" "declined"

The status of the time off request.

reason
string
Enum: "Vacation" "Sick day" "Personal" "Company Added" "Other"

Reason for the time off.

details
string

Details about the time off.

isAllDay
boolean

Whether the time off is for the entire day.

Responses

Request samples

Content type
application/json
{
  • "techId": "USR-38c1ee5c4efa38a4",
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 11:00:00",
  • "status": "pending",
  • "reason": "Vacation",
  • "details": "Doctor appointment",
  • "isAllDay": false
}

Response samples

Content type
application/json
{
  • "id": "TO-de9750285414508f",
  • "techId": "USR-38c1ee5c4efa38a4",
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 11:00:00",
  • "status": "approved",
  • "reason": "Vacation",
  • "details": "Doctor appointment",
  • "isAllDay": true,
  • "updatedAt": "2024-07-25 09:00:00",
  • "createdAt": "2024-07-25 09:00:00"
}

Retrieve future time offs

Retrieves a paginated list of future approved time offs based on the current date and pagination.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Enum: "id" "techId" "startDate" "endDate" "status" "reason" "details" "isAllDay" "updatedAt" "createdAt"

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

The sort direction. Must be combined with field.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "TO-de9750285414508f",
      • "techId": "USR-38c1ee5c4efa38a4",
      • "startDate": "2024-07-25 09:00:00",
      • "endDate": "2024-07-25 11:00:00",
      • "status": "approved",
      • "reason": "Vacation",
      • "details": "Doctor appointment",
      • "isAllDay": true,
      • "updatedAt": "2024-07-25 09:00:00",
      • "createdAt": "2024-07-25 09:00:00"
      }
    ]
}

Retrieve a single Time Off

Retrieves a single Time Off by its ID.

path Parameters
id
required
string
Example: TO-de9750285414508f

The time off ID (prefix TO-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "TO-de9750285414508f",
  • "techId": "USR-38c1ee5c4efa38a4",
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 11:00:00",
  • "status": "approved",
  • "reason": "Vacation",
  • "details": "Doctor appointment",
  • "isAllDay": true,
  • "updatedAt": "2024-07-25 09:00:00",
  • "createdAt": "2024-07-25 09:00:00"
}

Update an existing Time Off

Updates an existing Time Off and returns the updated Time Off.

path Parameters
id
required
string
Example: TO-de9750285414508f

The time off ID (prefix TO-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Time Off fields to update.

techId
string

The tech ID to assign the time off to (prefix USR-). Use -1 to assign to all company techs.

startDate
string <date-time>

The time & date when the time off starts.

endDate
string <date-time>

The time & date when the time off ends.

status
string
Enum: "approved" "pending" "declined"

The status of the time off request.

reason
string
Enum: "Vacation" "Sick day" "Personal" "Company Added" "Other"

Reason for the time off.

details
string

Details about the time off.

isAllDay
boolean

Whether the time off is for the entire day.

Responses

Request samples

Content type
application/json
{
  • "techId": "USR-38c1ee5c4efa38a4",
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 11:00:00",
  • "status": "pending",
  • "reason": "Vacation",
  • "details": "Doctor appointment",
  • "isAllDay": false
}

Response samples

Content type
application/json
{
  • "id": "TO-de9750285414508f",
  • "techId": "USR-38c1ee5c4efa38a4",
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 11:00:00",
  • "status": "approved",
  • "reason": "Vacation",
  • "details": "Doctor appointment",
  • "isAllDay": true,
  • "updatedAt": "2024-07-25 09:00:00",
  • "createdAt": "2024-07-25 09:00:00"
}

Delete a Time Off

Deletes a Time Off by its ID.

path Parameters
id
required
string
Example: TO-de9750285414508f

The time off ID (prefix TO-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

TimeSheets

Retrieve a list of Time Sheets

Retrieves a paginated list of Time Sheets based on the applied filters and pagination.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

field
string
Value: "startDate"

Beta: This property is subject to change and may contain bugs.

The field to sort results by. Must be combined with order.

order
string
Enum: "ASC" "DESC"
Examples:
  • order=ASC - Ascending order
  • order=DESC - Descending order

Beta: This property is subject to change and may contain bugs.

The sort direction. Must be combined with field. Defaults to DESC.

techId
string
Example: techId=USR-81ce48127c24fd23

Filter by tech ID (prefix USR-).

jobId
string
Example: jobId=JOB-BA5r7o4bqzR9MONa

Filter by job ID (prefix JOB-).

dateQuery
string
Example: dateQuery=2025-01-01_2025-12-31

Filter by start date range in the format YYYY-MM-DD_YYYY-MM-DD.

withJob
boolean
Examples:
  • withJob=true - With job
  • withJob=false - Without job

When true, only returns shifts associated with a job. Ignored if jobId is provided.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "TS-de9750285414508f",
      • "techId": "USR-81ce48127c24fd23",
      • "techName": "John Doe",
      • "startDate": "2024-01-24 08:00:00",
      • "endDate": "2024-01-24 16:00:00",
      • "notes": "This is a note",
      • "jobId": "JOB-BA5r7o4bqzR9MONa",
      • "laborCost": 34.75,
      • "shiftLength": "08:00"
      }
    ]
}

Create a new Time Sheet

Creates a new Time Sheet and returns the created Time Sheet object.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Time Sheet data to create.

techId
required
string

The ID of the user to clock into this shift (prefix USR-).

jobId
string

The ID of the job associated with this shift (prefix JOB-).

laborCost
number

The labor cost per hour of this shift.

startDate
required
string

The start date and time of the shift.

endDate
required
string

The end date and time of the shift.

notes
string

The notes of the shift.

Responses

Request samples

Content type
application/json
{
  • "techId": "USR-81ce48127c24fd23",
  • "jobId": "JOB-BA5r7o4bqzR9MONa",
  • "laborCost": 25,
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 09:00:00",
  • "notes": "This is a note"
}

Response samples

Content type
application/json
{
  • "id": "TS-de9750285414508f",
  • "techId": "USR-81ce48127c24fd23",
  • "techName": "John Doe",
  • "startDate": "2024-01-24 08:00:00",
  • "endDate": "2024-01-24 16:00:00",
  • "notes": "This is a note",
  • "jobId": "JOB-BA5r7o4bqzR9MONa",
  • "laborCost": 34.75,
  • "shiftLength": "08:00"
}

Retrieve a single Time Sheet

Retrieves a single Time Sheet by its ID.

path Parameters
id
required
string
Example: TS-f4e29a5a3f8a01a6

The time sheet ID (prefix TS-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "TS-de9750285414508f",
  • "techId": "USR-81ce48127c24fd23",
  • "techName": "John Doe",
  • "startDate": "2024-01-24 08:00:00",
  • "endDate": "2024-01-24 16:00:00",
  • "notes": "This is a note",
  • "jobId": "JOB-BA5r7o4bqzR9MONa",
  • "laborCost": 34.75,
  • "shiftLength": "08:00"
}

Update an existing Time Sheet

Updates an existing Time Sheet and returns the updated Time Sheet.

path Parameters
id
required
string
Example: TS-f4e29a5a3f8a01a6

The time sheet ID (prefix TS-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
optional

The Time Sheet fields to update.

techId
string

The ID of the user clocked into this shift (prefix USR-).

laborCost
number

The labor cost per hour of this shift.

startDate
string

The start date and time of the shift.

endDate
string

The end date and time of the shift.

notes
string

The notes of the shift.

Responses

Request samples

Content type
application/json
{
  • "techId": "USR-81ce48127c24fd23",
  • "laborCost": 25,
  • "startDate": "2024-07-25 09:00:00",
  • "endDate": "2024-07-25 09:00:00",
  • "notes": "This is a note"
}

Response samples

Content type
application/json
{
  • "id": "TS-de9750285414508f",
  • "techId": "USR-81ce48127c24fd23",
  • "techName": "John Doe",
  • "startDate": "2024-01-24 08:00:00",
  • "endDate": "2024-01-24 16:00:00",
  • "notes": "This is a note",
  • "jobId": "JOB-BA5r7o4bqzR9MONa",
  • "laborCost": 34.75,
  • "shiftLength": "08:00"
}

Delete a Time Sheet

Deletes a Time Sheet by its ID.

path Parameters
id
required
string
Example: TS-f4e29a5a3f8a01a6

The time sheet ID (prefix TS-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Users

Retrieve a list of Users

Retrieves a paginated list of Users.

query Parameters
pageSize
number
Example: pageSize=10

Number of records to return per page.

page
number
Example: page=1

The page index.

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "pageSize": 10,
  • "page": 1,
  • "totalResults": 50,
  • "hasMore": true,
  • "data": [
    • {
      • "id": "USR-38c1ee5c4efa38a4",
      • "name": "John Smith",
      • "emailAddress": "john.doe@gmail.com",
      • "cellPhone": "1234567890",
      • "address": "1234 Elm Street, Apt 5B, Springfield, IL 62701, USA",
      • "role": "tech",
      • "fieldTech": true,
      • "active": true,
      • "notes": "This is a note",
      • "jobTypes": [
        • {
          • "id": "JT-8718036049ec4c4d",
          • "name": "Repair"
          }
        ],
      • "serviceAreas": [
        • {
          • "id": "SA-71b8d7310acbf8cc",
          • "name": "San Francisco"
          }
        ]
      }
    ]
}

Retrieve a single User

Retrieves a single User by its ID.

path Parameters
id
required
string
Example: USR-A21Lz3rPQxkYqRNo

The user ID (prefix USR-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Responses

Response samples

Content type
application/json
{
  • "id": "USR-38c1ee5c4efa38a4",
  • "name": "John Smith",
  • "emailAddress": "john.doe@gmail.com",
  • "cellPhone": "1234567890",
  • "address": "1234 Elm Street, Apt 5B, Springfield, IL 62701, USA",
  • "role": "tech",
  • "fieldTech": true,
  • "active": true,
  • "notes": "This is a note",
  • "jobTypes": [
    • {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      }
    ],
  • "serviceAreas": [
    • {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    ]
}

Add Job Types to a User

Adds Job Types to a User and returns the updated User object.

path Parameters
id
required
string
Example: USR-A21Lz3rPQxkYqRNo

The user ID (prefix USR-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Job Type IDs to add.

jobTypes
required
Array of strings

Array of job type IDs (prefix JT-).

Responses

Request samples

Content type
application/json
{
  • "jobTypes": [
    • "JT-38c1ee5c4efa38a4",
    • "JT-38c1ee5c4efa38a5"
    ]
}

Response samples

Content type
application/json
{
  • "id": "USR-38c1ee5c4efa38a4",
  • "name": "John Smith",
  • "emailAddress": "john.doe@gmail.com",
  • "cellPhone": "1234567890",
  • "address": "1234 Elm Street, Apt 5B, Springfield, IL 62701, USA",
  • "role": "tech",
  • "fieldTech": true,
  • "active": true,
  • "notes": "This is a note",
  • "jobTypes": [
    • {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      }
    ],
  • "serviceAreas": [
    • {
      • "id": "SA-71b8d7310acbf8cc",
      • "name": "San Francisco"
      }
    ]
}

Remove Job Types from a User

Removes Job Types from a User.

path Parameters
id
required
string
Example: USR-A21Lz3rPQxkYqRNo

The user ID (prefix USR-).

header Parameters
Authorization
required
string
Example: Bearer <token>

Bearer Token

Request Body schema: application/json
required

The Job Type IDs to remove.

jobTypes
required
Array of strings

Array of job type IDs (prefix JT-).

Responses

Request samples

Content type
application/json
{
  • "jobTypes": [
    • "JT-38c1ee5c4efa38a4",
    • "JT-38c1ee5c4efa38a5"
    ]
}

Webhooks

Job webhook payload Webhook

Workiz POSTs this payload to your configured webhook URL whenever a job automation rule fires.

To set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. job_created), add optional conditions, then choose post webhook as the action. See the Workiz help article for a step-by-step guide.

The trigger.type value reflects the automation event (e.g. job_created). The data object is identical to the response from the corresponding GET /:id endpoint.

Authorization header: When an auth key is configured on the automation rule, Workiz includes Authorization: Bearer <authKey> in the request. This header is optional — your endpoint does not need to require it.

Your endpoint should return any 2xx status code to acknowledge receipt.

header Parameters
Authorization
string
Example: Bearer sk_live_1234567890

Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.

Request Body schema: application/json

The webhook payload Workiz sends to your endpoint.

required
object

The trigger event that fired this webhook.

required
object

The full job entity at the time of the event.

required
object

Metadata about the automation rule that triggered this webhook.

Responses

Request samples

Content type
application/json
{
  • "trigger": {
    • "type": "job_created",
    • "timestamp": "2024-03-15T10:30:00Z"
    },
  • "data": {
    • "id": "JOB-BA5r7o4bqzR9MONa",
    • "uuid": "3YBIBO",
    • "serialId": 12345,
    • "name": "AC Repair",
    • "status": "Submitted",
    • "subStatus": {
      • "id": "JSS-BA5r7o4bqzR9MONa",
      • "name": "Follow Up"
      },
    • "date": "2022-01-01 10:00:00",
    • "endDate": "2022-01-01 10:00:00",
    • "isAllDay": false,
    • "isScheduled": true,
    • "jobType": {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      },
    • "adGroup": {
      • "id": "AG-71b8d7310acbf8cc",
      • "name": "Ad Group 1"
      },
    • "description": "This is a description of the job.",
    • "subTotal": 946,
    • "discountAmount": 10,
    • "taxableAmount": 946,
    • "taxPercent": 10.111,
    • "taxAmount": 10.51,
    • "costing": 10.51,
    • "techExpenses": 12.51,
    • "tipAmount": 43.51,
    • "totalPrice": 956.51,
    • "amountDue": 956.51,
    • "amountDueDate": "2022-01-01 10:00:00",
    • "converted": true,
    • "clientInfo": {
      • "clientId": "CL-OvmDp2yvv1yqMwRl",
      • "serialId": 1023,
      • "firstName": "John Doe",
      • "lastName": "Doe",
      • "companyName": "Sample Company name",
      • "email": "client@workiz.com",
      • "primaryExt": "619",
      • "primaryPhone": "6195555555",
      • "secondaryExt": "613",
      • "secondaryPhone": "6195555555",
      • "addressDetails": {
        • "country": "US",
        • "state": "Ohio",
        • "city": "San Francisco",
        • "zipCode": "94102",
        • "address": "462 Powell St",
        • "unit": "3422",
        • "latitude": -76.2768398,
        • "longitude": 36.9669587,
        • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
        },
      • "serviceArea": {
        • "id": "SA-71b8d7310acbf8cc",
        • "name": "San Francisco"
        }
      },
    • "maskedNumber": {
      • "number": "6195551234",
      • "extension": "042",
      • "secondaryExtension": "043"
      },
    • "team": [
      • {
        • "id": "USR-38c1ee5c4efa38a4",
        • "name": "John Doe"
        }
      ],
    • "lineItems": [
      • {
        • "id": "JLI-BA5r7o4bqzR9MONa",
        • "productId": 1000,
        • "type": "product",
        • "name": "Deadbolt",
        • "description": "Deadbolt replacement, any color and size",
        • "price": 100,
        • "quantity": 1,
        • "total": 100,
        • "cost": 100,
        • "taxable": true,
        • "discountable": true,
        • "inventoryManaged": true,
        • "inventorySync": true,
        • "optionalConverted": true
        }
      ],
    • "payments": [
      • {
        • "id": "PAY-BA5r7o4bqzR9MONa",
        • "type": "Cash",
        • "amount": 100,
        • "tipAmount": 10
        }
      ],
    • "tags": [
      • {
        • "id": "TAG-8cddc18e7b0458fa",
        • "name": "Estimate"
        }
      ],
    • "customFields": [
      • {
        • "id": "CF-eYLPK7198xVp6Z8q",
        • "fieldName": "Custom Field 1",
        • "value": "John Doe"
        }
      ],
    • "notes": [
      • {
        • "id": "JNT-8cddc18e7b0458fa",
        • "techName": "John Doe",
        • "note": "This is a note",
        • "timestamp": "2022-01-01 10:00:00"
        }
      ],
    • "conversionDate": "2022-01-01 10:00:00",
    • "statusUpdated": "2022-01-01 12:00:00",
    • "utcUpdatedAt": "2022-01-01 12:00:00",
    • "updatedAt": "2022-01-01 12:00:00",
    • "createdAt": "2022-01-01 10:00:00"
    },
  • "metadata": {
    • "automationId": "auto_789",
    • "ruleName": "New Job Notification"
    }
}

Lead webhook payload Webhook

Workiz POSTs this payload to your configured webhook URL whenever a lead automation rule fires.

To set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. lead_created), add optional conditions, then choose post webhook as the action. See the Workiz help article for a step-by-step guide.

The trigger.type value reflects the automation event (e.g. lead_created). The data object is identical to the response from the corresponding GET /:id endpoint.

Authorization header: When an auth key is configured on the automation rule, Workiz includes Authorization: Bearer <authKey> in the request. This header is optional — your endpoint does not need to require it.

Your endpoint should return any 2xx status code to acknowledge receipt.

header Parameters
Authorization
string
Example: Bearer sk_live_1234567890

Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.

Request Body schema: application/json

The webhook payload Workiz sends to your endpoint.

required
object

The trigger event that fired this webhook.

required
object

The full lead entity at the time of the event.

required
object

Metadata about the automation rule that triggered this webhook.

Responses

Request samples

Content type
application/json
{
  • "trigger": {
    • "type": "job_created",
    • "timestamp": "2024-03-15T10:30:00Z"
    },
  • "data": {
    • "id": "LD-LwqGJnRwvZPaNe5E",
    • "uuid": "GD87TS",
    • "serialId": 12345,
    • "status": "Submitted",
    • "date": "2022-01-01 10:00:00",
    • "endDate": "2022-01-01 10:00:00",
    • "isAllDay": true,
    • "isScheduled": true,
    • "jobType": {
      • "id": "JT-8718036049ec4c4d",
      • "name": "Repair"
      },
    • "adGroup": {
      • "id": "AG-71b8d7310acbf8cc",
      • "name": "Ad Group 1"
      },
    • "description": "This is a description of the lead.",
    • "leadLost": true,
    • "clientInfo": {
      • "clientId": "CL-OvmDp2yvv1yqMwRl",
      • "serialId": 1023,
      • "firstName": "John Doe",
      • "lastName": "Doe",
      • "companyName": "Sample Company name",
      • "email": "client@workiz.com",
      • "primaryExt": "619",
      • "primaryPhone": "6195555555",
      • "secondaryExt": "613",
      • "secondaryPhone": "6195555555",
      • "addressDetails": {
        • "country": "US",
        • "state": "Ohio",
        • "city": "San Francisco",
        • "zipCode": "94102",
        • "address": "462 Powell St",
        • "unit": "3422",
        • "latitude": -76.2768398,
        • "longitude": 36.9669587,
        • "locationKey": "462 Powell St, San Francisco, Ohio 94102"
        },
      • "serviceArea": {
        • "id": "SA-71b8d7310acbf8cc",
        • "name": "San Francisco"
        }
      },
    • "team": [
      • {
        • "id": "USR-38c1ee5c4efa38a4",
        • "name": "John Doe"
        }
      ],
    • "tags": [
      • {
        • "id": "TAG-8cddc18e7b0458fa",
        • "name": "Estimate"
        }
      ],
    • "customFields": [
      • {
        • "id": "CF-eYLPK7198xVp6Z8q",
        • "fieldName": "Custom Field 1",
        • "value": "John Doe"
        }
      ],
    • "notes": [
      • {
        • "id": "JNT-8cddc18e7b0458fa",
        • "techName": "John Doe",
        • "note": "This is a note",
        • "timestamp": "2022-01-01 10:00:00"
        }
      ],
    • "statusUpdated": "2022-01-01 12:00:00",
    • "utcUpdatedAt": "2022-01-01 12:00:00",
    • "updatedAt": "2022-01-01 12:00:00",
    • "createdAt": "2022-01-01 10:00:00"
    },
  • "metadata": {
    • "automationId": "auto_789",
    • "ruleName": "New Job Notification"
    }
}

Invoice webhook payload Webhook

Workiz POSTs this payload to your configured webhook URL whenever a invoice automation rule fires.

To set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. invoice_sent), add optional conditions, then choose post webhook as the action. See the Workiz help article for a step-by-step guide.

The trigger.type value reflects the automation event (e.g. invoice_sent). The data object is identical to the response from the corresponding GET /:id endpoint.

Authorization header: When an auth key is configured on the automation rule, Workiz includes Authorization: Bearer <authKey> in the request. This header is optional — your endpoint does not need to require it.

Your endpoint should return any 2xx status code to acknowledge receipt.

header Parameters
Authorization
string
Example: Bearer sk_live_1234567890

Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.

Request Body schema: application/json

The webhook payload Workiz sends to your endpoint.

required
object

The trigger event that fired this webhook.

required
object

The full invoice entity at the time of the event.

required
object

Metadata about the automation rule that triggered this webhook.

Responses

Request samples

Content type
application/json
{
  • "trigger": {
    • "type": "job_created",
    • "timestamp": "2024-03-15T10:30:00Z"
    },
  • "data": {
    • "id": "IV-bK9r2XyZL54aWDR0",
    • "uuid": "3YBIBO",
    • "serialId": 56,
    • "name": "Invoice 1",
    • "notes": "This is a note for the invoice",
    • "jobId": "JOB-BA5r7o4bqzR9MONa",
    • "discountAmount": 10,
    • "subTotal": 946,
    • "taxableAmount": 946,
    • "taxPercent": 10.111,
    • "taxAmount": 10.51,
    • "costing": 10.51,
    • "techExpenses": 12.51,
    • "tipAmount": 43.51,
    • "totalPrice": 956.51,
    • "amountDue": 956.51,
    • "amountDueDate": "2026-01-01 10:00:00",
    • "lineItems": [
      • {
        • "id": "ILI-BA5r7o4bqzR9MONa",
        • "productId": 1000,
        • "name": "Deadbolt",
        • "description": "Deadbolt replacement, any color and size",
        • "price": 100,
        • "quantity": 1,
        • "total": 100,
        • "cost": 100,
        • "taxable": true,
        • "discountable": true,
        • "inventoryManaged": true,
        • "inventorySync": true,
        • "optionalConverted": true
        }
      ],
    • "payments": [
      • {
        • "id": "PAY-BA5r7o4bqzR9MONa",
        • "type": "Cash",
        • "amount": 100,
        • "tipAmount": 10
        }
      ],
    • "attachments": [],
    • "signatureImage": {},
    • "updated": "2026-01-01 00:00:00",
    • "created": "2026-01-01 00:00:00"
    },
  • "metadata": {
    • "automationId": "auto_789",
    • "ruleName": "New Job Notification"
    }
}

Estimate webhook payload Webhook

Workiz POSTs this payload to your configured webhook URL whenever a estimate automation rule fires.

To set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. estimate_created), add optional conditions, then choose post webhook as the action. See the Workiz help article for a step-by-step guide.

The trigger.type value reflects the automation event (e.g. estimate_created). The data object is identical to the response from the corresponding GET /:id endpoint.

Authorization header: When an auth key is configured on the automation rule, Workiz includes Authorization: Bearer <authKey> in the request. This header is optional — your endpoint does not need to require it.

Your endpoint should return any 2xx status code to acknowledge receipt.

header Parameters
Authorization
string
Example: Bearer sk_live_1234567890

Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.

Request Body schema: application/json

The webhook payload Workiz sends to your endpoint.

required
object

The trigger event that fired this webhook.

required
object

The full estimate entity at the time of the event.

required
object

Metadata about the automation rule that triggered this webhook.

Responses

Request samples

Content type
application/json
{
  • "trigger": {
    • "type": "job_created",
    • "timestamp": "2024-03-15T10:30:00Z"
    },
  • "data": {
    • "id": "ES-LwqGJnRwvZPaNe5E",
    • "status": "Pending",
    • "serialId": "1-1",
    • "name": "Estimate 1",
    • "description": "This is a description for the estimate",
    • "notes": "This is a note for the estimate",
    • "imageUrl": "https://example.com/image.png",
    • "clientId": "CL-LwqGJnRwvZPaNe5E",
    • "jobId": "JOB-BA5r7o4bqzR9MONa",
    • "discountAmount": 10,
    • "taxPercent": 10,
    • "taxableAmount": 100,
    • "taxAmount": 10,
    • "isDepositPercentage": true,
    • "deposit": 100,
    • "subTotal": 10,
    • "total": 10,
    • "declineReason": "This is a decline reason for the estimate",
    • "lineItems": [
      • {
        • "id": "ELI-BA5r7o4bqzR9MONa",
        • "productId": 1000,
        • "name": "Deadbolt",
        • "description": "Deadbolt replacement, any color and size",
        • "price": 100,
        • "quantity": 1,
        • "total": 100,
        • "cost": 100,
        • "taxable": true,
        • "discountable": true,
        • "inventoryManaged": true,
        • "inventorySync": true,
        • "optionalConverted": true
        }
      ],
    • "payments": [
      • {
        • "id": "PAY-BA5r7o4bqzR9MONa",
        • "type": "Cash",
        • "amount": 100,
        • "tipAmount": 10
        }
      ],
    • "attachments": [],
    • "signatureImage": {},
    • "sentDate": "2026-01-01 00:00:00",
    • "estimateDate": "2026-01-01 00:00:00",
    • "lastViewedDate": "2026-01-01 00:00:00",
    • "statusUpdatedAt": "2026-01-01 00:00:00",
    • "updated": "2026-01-01 00:00:00",
    • "created": "2026-01-01 00:00:00"
    },
  • "metadata": {
    • "automationId": "auto_789",
    • "ruleName": "New Job Notification"
    }
}