--- title: "Create a new Lead" method: POST path: "/v2/leads" tags: ["Leads"] --- # Create a new Lead `POST /v2/leads` 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. ## Headers - `Authorization` string, required ## Request body - CreateLeadV2Dto - `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-`). - `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 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. - `customFields` CustomFieldValueV2Dto[] — The custom fields of the lead. - `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 Lead. - ResponseLeadV2Dto - `id` string — The ID of the lead (prefix `LD-`). - `uuid` string — The UUID of the lead. - `serialId` number — The serial ID of the lead. - `status` string — The status of the lead. - `date` string, date-time — The date and time when the lead is scheduled. - `endDate` string, date-time — The date and time when the lead is scheduled to end. - `isAllDay` boolean — Whether the lead is all day. - `isScheduled` boolean — Whether the lead 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 lead. - `leadLost` boolean — Whether the lead was marked as lost. - `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. - `team` ResponseGenericTechV2Dto[] — A list of lead technicians. - `id` string — The ID of the technician (prefix `USR-`). - `name` string — The name of the technician. - `tags` ResponseGenericTagV2Dto[] — A list of Tags. - `id` string — The ID of the tag (prefix `TAG-`). - `name` string — The name of the tag. - `customFields` ResponseGenericCustomFieldV2Dto[] — A list of 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 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. - `statusUpdated` string, date-time — The date and time when the lead status was last updated (based on account timezone). - `updatedAt` string, date-time — The date and time when the lead was last updated (based on account timezone). - `createdAt` string, date-time — The date and time when the lead was created (based on account timezone). ## 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)