Sign in
latestOpenAPI 3.0.02026-08-1284111344.5 KB

14666f4db0f8

Leads

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.

post/v2/leads

Headers

Authorizationstring required
Example:Bearer <token>

Bearer Token

Request body

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

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

isAllDayboolean

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

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

isScheduledboolean

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.

descriptionstring

The description of the lead.

timeZonestring

The timezone of the lead.

jobTypeIdstring

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 lead (prefix USR-).

createdDatestring date-time

The date and time when the lead 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,
  "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 Lead.

idstring

The ID of the lead (prefix LD-).

uuidstring

The UUID of the lead.

serialIdnumber

The serial ID of the lead.

statusstring

The status of the lead.

datestring date-time

The date and time when the lead is scheduled.

endDatestring date-time

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

isAllDayboolean

Whether the lead is all day.

isScheduledboolean

Whether the lead is scheduled.

descriptionstring

The description of the lead.

leadLostboolean

Whether the lead was marked as lost.

statusUpdatedstring date-time

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

updatedAtstring date-time

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

createdAtstring date-time

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

Example response

{
  "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",
  "updatedAt": "2022-01-01 12:00:00",
  "createdAt": "2022-01-01 10:00:00"
}