Leads

Contractors Cloud provides a robust lead system that allows you to accept leads from multiple sources as well as in multiple formats (json, excel, text). Once setup and configured correctly, you will be able to accept / create leads with minimal data and eventually convert them into projects.

Overview

A lead represents a scope of work, job or sale in its early stages. A Lead is not a Project but can be converted into a Project later on. Leads can originate from a variety of different sources such as a spreadsheet, a form on your website, a third-party lead provider, etc. As a result, we have designed our lead system to help you accept leads from anywhere with minimal effort on your part.

Setup

Before you can begin accepting Leads, you must first setup a LeadConnection. A lead connection is a pre-configured endpoint that describes what data format incoming leads will be in, what default attributes should be assigned to leads, as well as how the lead data is parsed via field maps. In short, a lead connection tells Contractors Cloud how to accept and process your leads.

Step 1. Create your lead connection

Start by creating your lead connection. You can do this via our web app or directly through our API. If you are a third-party company or developer tasked with providing leads to a Contractors Cloud customer, this step should ideally be performed by the customer so they can provide all the necessary defaults for the lead connection.

When creating a lead connection, you will need to provide the following data:

Company: This is the Company the lead connection operates under. All projects that are created from leads that use this lead connection will belong to this company.
Data Type: Specifies the format your leads are in. We currently support the following formats: json, excel and text.
Name: Give your lead connection a nice name to describe where leads are coming from. For example, "Spreadsheet Uploads, LeadSource Inc. Connection, Web Form, etc.".

Finally, there are some additional fields that can be filled out:

❗️
Heads Up
All though not required, we strongly recommend that these fields are filled out as they will increase the conversion chances of leads becoming projects.

Default Event: This is the default event that will be assigned to incoming leads when one cannot be determined.
Default Lead Source: This is the default lead source that will be assigned to incoming leads when one cannot be determined.
Default Workflow: This is the default workflow that will be assigned to incoming leads when one cannot be determined.
Default Primary Rep: This is the default user that will be assigned as the primary rep to incoming leads when one cannot be determined.
Site Type: This is the default site type that will be assigned to incoming leads when one cannot be determined.

Step 2. Map your fields (Optional)

Although not required, we recommend setting up field maps for your lead connection. Field maps tell Contractors Cloud how to extract specific key data (target) from your custom lead data (source). When a lead comes in, here are the target fields we try to extract:

city
email
first_name
last_name
phone
site_type
state
street
zip

If your lead data does not have these fields or your fields are named differently, don't worry. That's what fields maps are for. Take for example the following example json lead:

{
  "client_info": {
    "name": {
      "first": "John",
      "last": "Smith"
    },
    "location": {
      "street_address": "12345 Example Street",
      "city_name": "Flavortown",
      "state_code": "MN",
      "postal_code": "55328"
    },
    "contact_details": {
      "primary_phone": "763-555-1234",
      "phone_suffix": "1234",
      "email_address": "[email protected]"
    }
  }
}

We could manually create field maps for this lead via the API or through the web app:

Target: city - Source: client_info.location.city_name
Target: email - Source: client_info.contact_details.email_address

To keep this documentation short, we are mapping only two of the available target fields but the rest would be mapped with a similar approach using json dot notation for the source keys. Once all available fields have been mapped, Contractors Cloud will know exactly how to extract the data it needs (first name, email, etc.) from your custom lead data.

📘
Automatic Field Mapping
If you don't want to setup your field maps manually, we can automatically map them up for you. Just provide us an example of your lead data and we'll do the rest.

Step 3: Configure your lead connection settings (Optional)

Every lead connection also has a few available settings that can be configured to further customize how your leads are parsed and processed. These settings can be changed directly through the API or the web app:

Setting	Allowed Values	Description
`lead_rep_assignment_method`	`default`, `round-robin`	Determines how the primary rep is assigned to incoming leads.
`excel_file_header_row_number`	1-10	If your lead connection is accepting excel based leads, this is the row number that your headers (column titles) are on.
`automatically_convert_leads`	`yes`, `no`	If there is enough data to convert a lead into a project, conversion will happen automatically if this is set to `yes` rather than requiring manually approval.
`ignore_required_custom_fields`	`yes`, `no`	If the corresponding company for the lead connection has custom fields that require values and values for those fields could not be determined from the lead data, setting this to `yes` will ignore those requirements, effectively increasing your lead to project conversion rate.

Sweet! At this point your lead connection is ready to accept leads.

Usage

Once your lead connection has been setup and configured correctly, you are ready to accept leads. You can manually submit leads to your lead connection directly through the web app but more often than not, this process will be done programatically.

Endpoint

We provide a single endpoint to create one or many leads:

POST /api/v1/leads

Headers

You must provide a X-Lead-Connection-Idheader with the id of the lead connection to use when making your call.
You must also provide your API bearer token for proper authentication.

Body

The body of your request will be different depending on the data type your lead connection accepts:

Json Leads

Set your Accept and Content-Type headers to application/json.
In your request body provide your lead data in json format as is. You may also pass multiple leads in json format at once in the same call.

Excel Leads

In your request body provide an excel_filefield with your spreadsheet of leads as the file / value for the field. We currently accept file types of xlsx, csv, ods and xls.

Text Leads

Set your Content-Type header to text/plain.
In your request body, provide the raw text representation of the lead in plain, human readable English.

Response

If your request is successful, you will receive an HTTP status code of 202 Accepted along with the following example response:

{
    "message": "3 leads detected and queued for processing.",
    "transaction_id": "f00c2b11-b92f-4fd6-9ad4-ddf0ab10a117"
}

The response will let you know how many leads where detected. Additionally, a transaction id will also be provided for you to track / reference the leads for later. Leads submitted in the same request will always have the same transaction id.

Lead to Project Conversion

In order to create a full Contractors Cloud Project, a handful of data is required as documented here. To convert a lead into a project, we will aggregate all the data we can from your custom lead data, the defaults specified in your lead connection and also intellectually determine values for any remaining required fields.

Lead Lifecycle

If we determine we have enough data to convert the lead into a project and the automatically_convert_leads lead connection setting is set to yes, the lead will automatically become a project.
If we determine we have enough data to convert the lead into a project and the automatically_convert_leads lead connection setting is set to no, the status of the lead will become ready. At this point, the lead will need to be manually converted into a project.
If we do not have enough data to convert the lead into a project, the lead's status will be set to needs-review. Additionally the validation_errorsattribute on the lead will contain what needs to be fixed before conversion can happen. Leads can be fixed via the API or directly in the web app.

Data Overrides

As mentioned earlier, you do not need to transform your lead data to match the structure that Contractors Cloud is expecting, provided that your lead connection is setup correctly. However, if your use case allows for it, you can append additional data to your custom lead data to override / set any field you want.

Take for example the following example custom json lead:

{
  "client_info": {
    "name": {
      "first": "John",
      "last": "Smith"
    },
    "location": {
      "street_address": "12345 Example Street",
      "city_name": "Flavortown",
      "state_code": "MN",
      "postal_code": "55328"
    },
    "contact_details": {
      "primary_phone": "763-555-1234",
      "phone_suffix": "1234",
      "email_address": "[email protected]"
    }
  }
}

As an example, two of the fields (of many) that we need to convert this lead into a project are "account_id" and "project name". By default, the value for the account_id will be determine by the account_id default set on the lead connection. If no default is set, a new account will be created. The project name will intellectually be derived based on all data we aggregate (John Smith - Flavortown, MN Project).

If the derived values for "account_id" and "project name" are not the ones we want, we can override them when submitting the lead via a contractors_cloud_datakey in our json payload:

{
  "client_info": {
    "name": {
      "first": "John",
      "last": "Smith"
    },
    "location": {
      "street_address": "12345 Example Street",
      "city_name": "Flavortown",
      "state_code": "MN",
      "postal_code": "55328"
    },
    "contact_details": {
      "primary_phone": "763-555-1234",
      "phone_suffix": "1234",
      "email_address": "[email protected]"
    }
  },
  "contractors_cloud_data": {
    "account": {
      "id": 42
    },
    "project": {
      "name": "My Custom Project"
    }
  }
}

When the above lead is submitted, an account id of 42 will be assigned to the lead and ultimately the project once converted. Similarly, the project name will be set to "My Custom Project".

You may override / set anything else you'd like such as contacts, custom fields, sales data, etc in the contractors_cloud_data json object.

Leads

Overview

Setup

Step 1. Create your lead connection

❗️
Heads Up

Step 2. Map your fields (Optional)

📘
Automatic Field Mapping

Step 3: Configure your lead connection settings (Optional)

Usage

Endpoint

Headers

Body

Json Leads

Excel Leads

Text Leads

Response

Lead to Project Conversion

Lead Lifecycle

Data Overrides

Overview

Setup

Step 1. Create your lead connection

❗️Heads Up

Step 2. Map your fields (Optional)

📘Automatic Field Mapping

Step 3: Configure your lead connection settings (Optional)

Usage

Endpoint

Headers

Body

Json Leads

Excel Leads

Text Leads

Response

Lead to Project Conversion

Lead Lifecycle

Data Overrides

❗️
Heads Up

📘
Automatic Field Mapping