--- title: "Create a new Job" method: POST path: "/v2/jobs" tags: ["Jobs"] --- # Create a new Job `POST /v2/jobs` 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. ## Headers - `Authorization` string, required ## Request body - CreateJobV2Dto - `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` string, required — The ID of the job type (prefix `JT-`). - `adGroupId` string — The ID of the ad group (prefix `AG-`). - `clientInfo` CreateClientInfoV2Dto, required - `clientId` string — The ID of the client (prefix `CL-`). Used to fill in any missing fields from the existing client record. - `firstName` string — The first name of the client. Required when clientId is not provided. - `lastName` string — The last name of the client. - `email` string — The email address of the client. Required when clientId is not provided and primaryPhone is not provided. - `companyName` string — The company name of the client. - `primaryExt` string — The extension number for the primary phone number. - `primaryPhone` string — The primary phone number of the client. Required when clientId is not provided and email is not provided. - `secondaryExt` string — The extension number for the secondary phone number. - `secondaryPhone` string — The secondary phone number of the client. - `addressDetails` CreateUpdateAddressDetailsV2Dto - `country` string — The country of the address. - `state` string — The state of the address. - `city` string — The city of the address. - `zipCode` string — The ZIP code of the address. - `address` string — The street address. - `unit` string — The unit or suite number. - `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. - `customFields` CustomFieldValueV2Dto[] — The custom fields of the job. - `id` string, required — The ID of the custom field (prefix `CF-`). - `value` union, required — The value of the custom field. - string - number - boolean ## Response `201` The created Job. - ResponseOneJobV2Dto - `id` string — The ID of the job (prefix `JOB-`). - `uuid` string — The UUID of the job. - `serialId` number — The serial ID of the job. - `name` string — The name of the job. - `status` string — The status of the job. - `subStatus` ResponseJobJobSubStatusV2Dto - `id` string — The ID of the job sub status (prefix `JSS-`). - `name` string — The name of the job sub status. - `date` string, date-time — The date and time when the job is scheduled. - `endDate` string, date-time — The date and time when the job is scheduled to end. - `isAllDay` boolean — Whether the job is all day. - `isScheduled` boolean — Whether the job is scheduled. - `jobType` ResponseGenericJobTypeV2Dto - `id` string — The ID of the job type (prefix `JT-`). - `name` string — The name of the job type. - `adGroup` ResponseGenericAdGroupV2Dto - `id` string — The ID of the ad group (prefix `AG-`). - `name` string — The name of the ad group. - `description` string — The description of the job. - `subTotal` number — The subtotal of the job before tax and discounts. - `discountAmount` number — The job discount amount. - `taxableAmount` number — The taxable amount of the job. - `taxPercent` number — The tax percentage of the job. - `taxAmount` number — The tax amount of the job. - `costing` number — The cost amount of the job. - `techExpenses` number — The technician expenses of the job. - `tipAmount` number — The tip amount of the job. - `totalPrice` number — The total price of the job. - `amountDue` number — The amount due for the job. - `amountDueDate` string, date-time — The date and time when the job amount is due. - `converted` boolean — Whether the job was converted from a lead. - `clientInfo` ResponseJobLeadDetailsV2Dto - `clientId` string — The ID of the associated client (prefix `CL-`). - `serialId` number — The serial ID of the client. - `firstName` 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. - `primaryExt` string — The primary extension of the client. - `primaryPhone` string — The primary phone of the client. - `secondaryExt` string — The secondary extension of the client. - `secondaryPhone` string — The secondary phone of the client. - `addressDetails` ResponseJobLeadAddressV2Dto - `country` string — The country of the client. - `state` string — The state of the client. - `city` string — The city of the client. - `zipCode` string — The zip code of the client. - `address` string — The address of the client. - `unit` string — The unit of the client. - `latitude` number — The latitude of the client. - `longitude` number — The longitude of the client. - `locationKey` string — The location key of the client. - `serviceArea` ResponseGenericServiceAreaV2Dto - `id` string — The ID of the service area (prefix `SA-`). - `name` string — The name of the service area. - `maskedNumber` ResponseJobMaskedNumberV2Dto - `number` string, required — The call masking phone number. - `extension` string, required — The call masking extension for the primary phone. - `secondaryExtension` string — The call masking extension for the secondary phone. - `team` ResponseGenericTechV2Dto[] — A list of job technicians. - `id` string — The ID of the technician (prefix `USR-`). - `name` string — The name of the technician. - `lineItems` ResponseJobLineItemV2Dto[] — A list of Job Line Items. - `id` string — The ID of the job line item (prefix `JLI-`). - `productId` number — The product ID of the item from which this line item was created. - `type` string — The type of the line item. - `name` string — The name of the line item. - `description` string — The description of the line item. - `price` number — The price of the line item. - `quantity` number — The quantity of the line item. - `total` number — The total of the line item. - `cost` number — The cost of the line item. - `taxable` boolean — Whether the line item is taxable. - `discountable` boolean — Whether the line item is discountable. - `inventoryManaged` boolean — Whether the line item is managed by inventory. - `inventorySync` boolean — Whether the line item is synced to inventory. - `optionalConverted` boolean — Whether the line item was an optional item. - `payments` ResponseGenericPaymentV2Dto[] — The payments of the job. - `id` string — The ID of the payment (prefix `PAY-`). - `type` string — The type of the payment. - `amount` number — The amount of the payment. - `tipAmount` number — The tip amount. - `tags` ResponseGenericTagV2Dto[] — A list of Job Tags. - `id` string — The ID of the tag (prefix `TAG-`). - `name` string — The name of the tag. - `customFields` ResponseGenericCustomFieldV2Dto[] — A list of Job Custom Fields. - `id` string — The ID of the custom field (prefix `CF-`). - `fieldName` string — The name of the custom field. - `value` union — The value of the custom field. Can be string, number, boolean, date string, or an array of file objects. - string — A string value. - number — A number value. - boolean — A boolean value. - object[] - `name` string — The name of the file. - `url` string — The URL of the file. - `notes` ResponseJobLeadNoteV2Dto[] — A list of Job Notes. - `id` string — The ID of the note (prefix `JNT-`). - `techName` string — The name of the technician who created the note. - `note` string — The note. - `timestamp` string, date-time — The date and time when the note was made. - `conversionDate` string, date-time — The date and time when the job was converted from a lead (based on account timezone). - `statusUpdated` string, date-time — The date and time when the job status was last updated (based on account timezone). - `updatedAt` string, date-time — The date and time when the job was last updated (based on account timezone). - `createdAt` string, date-time — The date and time when the job was created (based on account timezone). - `attachments` ResponseGenericAttachmentV2Dto[] — The attachments of the job. - `id` string — The ID of the attachment (prefix `FLE-`). - `name` string — The name of the attachment. - `fileUrl` string — The URL of the attachment. ## Other responses - `400` — Invalid input. - `401` — Missing or invalid authentication token. --- [API](https://skmtc.net/workiz/apis/developer-api.md) · [All operations](https://skmtc.net/workiz/apis/developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/workiz/developer-api/revisions/14666f4db0f8/schema)