latestOpenAPI 3.0.02026-08-1284111344.5 KB

14666f4db0f8

Jobs

Create a new Job

Creates a new Job and returns the created Job object.

Client Matching & Creation Logic:

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
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.

post/v2/jobs

Headers

Authorizationstring required

Example:Bearer <token>

Bearer Token

Request body

datestring 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.

endDatestring 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.

isAllDayboolean

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

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

isScheduledboolean

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.

namestring

The name of the job.

descriptionstring

The description of the job.

timeZonestring

The timezone of the job.

jobTypeIdstring required

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

adGroupIdstring

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

createdBystring

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

createdDatestring date-time

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

Example request

{
  "date": "2022-01-01 10:00:00",
  "endDate": "2022-01-01 10:00:00",
  "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

The created Job.

idstring

The ID of the job (prefix JOB-).

uuidstring

The UUID of the job.

serialIdnumber

The serial ID of the job.

namestring

The name of the job.

statusstring

The status of the job.

datestring date-time

The date and time when the job is scheduled.

endDatestring date-time

The date and time when the job is scheduled to end.

isAllDayboolean

Whether the job is all day.

isScheduledboolean

Whether the job is scheduled.

descriptionstring

The description of the job.

subTotalnumber

The subtotal of the job before tax and discounts.

discountAmountnumber

The job discount amount.

taxableAmountnumber

The taxable amount of the job.

taxPercentnumber

The tax percentage of the job.

taxAmountnumber

The tax amount of the job.

costingnumber

The cost amount of the job.

techExpensesnumber

The technician expenses of the job.

tipAmountnumber

The tip amount of the job.

totalPricenumber

The total price of the job.

amountDuenumber

The amount due for the job.

amountDueDatestring date-time

The date and time when the job amount is due.

convertedboolean

Whether the job was converted from a lead.

conversionDatestring date-time

The date and time when the job was converted from a lead (based on account timezone).

statusUpdatedstring date-time

The date and time when the job status was last updated (based on account timezone).

updatedAtstring date-time

The date and time when the job was last updated (based on account timezone).

createdAtstring date-time

The date and time when the job was created (based on account timezone).

Example response

{
  "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",
  "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",
  "updatedAt": "2022-01-01 12:00:00",
  "createdAt": "2022-01-01 10:00:00",
  "attachments": [
    {
      "id": "FLE-BA5r7o4bqzR9MONa",
      "name": "file.pdf",
      "fileUrl": "https://example.com/file.pdf"
    }
  ]
}