Discover more about the lead object and its related properties
Table of Contents
Introduction
In ConstructionOnline, a lead is an incoming contact that has expressed some interest in your company's services or products. Leads can be obtained from a number of different ways, from networking, to your company's website, or even social media. Leads require further discussion or review to qualify as a prospective client, which usually involves sales calls, callbacks, meetings, and follow-ups. Leads in ConstructionOnline can be tracked their entire lifecycle, from initial capture to closure.
⭐ Leads vs. Contacts
A lead is a type of contact in ConstructionOnline. Like other contacts, leads can contain important personal data such as name, address, city, contact quality, and more. However, leads also contain additional information that can only be accessed from the Lead Tracking section of ConstructionOnline. These additional fields include details such as lead status, stage, source, quality, value, and more.
Several Contacts endpoints will return leads when called. However, these leads will return as contact objects—meaning, they will only return properties reserved for contact objects. Lead-specific information, such as lead type or stage, will not be included within the returned leads.
To return lead-specific information alongside basic contact information, you will need to call one of the Leads endpoints.
Lead Object
The lead object is an extension of the contact object and represents an individual lead in ConstructionOnline. Each lead object returns the same properties for contact objects, but with the addition of extra lead-specific properties.
Each lead is referenced by its unique numerical ID, which is stored in the property 'ID'. A lead's ID is automatically assigned during creation and cannot be modified. Each lead object will contain at least a 'FIRSTNAME', 'LASTNAME', 'EMAIL', and 'DISPLAY_NAME', as these properties are required for creation. The remaining properties are optional. Many of the returned properties and their associated values are carried over from the lead's contact details.
| Name | Type | Description |
| ID | integer | Unique identifier for the lead. |
| FIRSTNAME | string | Lead's first name. |
| LASTNAME | string | Lead's last name. |
| string | Lead's email address. | |
| DISPLAY_NAME | string | Lead's display name. |
| ACCOUNT | string | Reserved for future use. |
| LACCESS | date | Date and time the lead last accessed ConstructionOnline. |
| LMOD | date | Date and time the lead was last modified. |
| COMPANY | string | Company associated with the lead. |
| ADDRESS | string | Lead's street address. |
| CITY | string | Lead's city. |
| STATE | string | Lead's state. |
| ZIP | string | Lead's zip code. |
| PHONE | string | Lead's phone number. |
| MOBILE_PHONE | string | Lead's mobile phone number. |
| MOBILE_PROVIDER | string | Lead's mobile provider. |
| FAX | string | Lead's fax number. |
| LMOD_CON_ID | integer | Unique identifier for the user who last modified the lead. |
| LMOD_NAME | string | Name of the user who last modified the lead. |
| MIDDLENAME | string | Lead's middle name. |
| WEBSITE | string | Lead's website. |
| CREATOR_ID | integer | Unique identifier for the user that created the lead. |
| CREATOR_NAME | string | Name of the user who created the lead. |
| TIMEZONE_OFFSET | double | Reserved for future use. |
| AUTO_TIMEZONE | boolean | Reserved for future use. |
| COMPANY_ID | integer | Unique identifier for the company associated with the lead. |
| COMPANY_NAME | string | Name of the company associated with the lead. |
| COUNTRY_SETTING | integer | Reserved for future use. |
| LANGUAGE_SETTING | integer | Reserved for future use. |
| COMPANY_PERMISSIONS | integer | Reserved for future use. |
| IS_COMPANY_ADMIN | boolean | Reserved for future use. |
| OFFLINE_FILES | string | Any files saved with the lead. |
| FAVORITE_PROJECTS | integer | Reserved for future use. |
| DATE_FORMAT | byte | Reserved for future use. |
| TIME_FORMAT | byte | Reserved for future use. |
| TIMEZONE_ID | string | Reserved for future use. |
| CONTACT_QUALITY | integer |
Contact quality associated with the lead. Returns the star rating as a integer between 1 and 5. Returns null if no rating has been assigned. Please note: contact quality and lead quality are two separate properties. |
| MESSAGE_SIGNATURE | string | Reserved for future use. |
| GENERAL_CALENDAR_COLOR | string | Reserved for future use. |
| LEAD_STATUS | integer | Status of the lead. Returns an integer that corresponds with the selected status in ConstructionOnline. |
| LEAD_QUALITY | integer |
Lead quality associated with the lead. Returns the star rating as an integer between 1 and 5. Returns null if no rating has been assigned. Please note: contact quality and lead quality are two separate properties. |
| LEAD_VALUE | integer | Value assigned to the lead. |
| LEAD_ASSIGNED_TO | integer | ID of the user assigned to the lead. |
| LEAD_PROBABILITY | integer | Probability of conversion for the lead. |
| LEAD_LAST_CONTACT | date | Date of the last point of contact (email, call, message, etc.) sent to the lead. |
| LEAD_DATE_CREATED | date | Date the lead was created. |
| LEAD_OPENED | date | Date the lead was opened. |
| LEAD_CLOSED | date | Date the lead was closed. |
| LEAD_LMOD_DATE | date | Date the lead was last modified. |
| LEAD_LMOD_ID | integer | ID of the user that last modified the lead. |
| IS_LEAD | integer | Always returns 1 for leads. |
| IS_SUB | integer | Reserved for future use. |
| IS_CLIENT | integer | Reserved for future use. |
Properties marked as "Reserved for future use" will be used in the future if the lead is converted to a different type of contact, such as a client. If a value is returned for one of these properties, it is the default value automatically set by ConstructionOnline.
In addition to the properties above, lead objects also return properties that reference custom values for the user's company account. Custom values are fields that can be customized for each company to best fit their specific needs, and are denoted by a gear icon ⚙️ beside the field heading.
Each custom value property will return the numerical ID that represents the specific custom value entry assigned to the opportunity. To ensure you know the meaning of the returned value, we highly recommend storing your company's custom value entries in a data table or collection for reference. This endpoint can be used to return all custom values for your company's account.
| Name | Type | Description |
| CONTACT_REGION | integer | Corresponds to the 'Region' custom value. Returns the numerical ID for the specific region associated with the lead. |
| CONTACT_DIVISION | integer | Corresponds to the 'Division' custom value. Returns the numerical ID for the specific division associated with the lead. |
| CONTACT_OFFICE | integer | Corresponds to the 'Office' custom value. Returns the numerical ID for the specific office associated with the lead. |
| CONTACT_CATEGORY | integer | Corresponds to the 'Contact Category' custom value. Returns the numerical ID for the specific category associated with the lead. |
| CONTACT_TRADE | integer | Corresponds to the 'Trade' custom value. Returns the numerical ID for the specific trade associated with the lead. |
| FIELD_ID | integer | Corresponds to the 'Contact Group' custom value. Returns the numerical ID for the specific contact group associated with the lead. |
| LEAD_STAGE | integer | Corresponds with the 'Lead Stage' custom value. Returns the numerical ID for the specific stage associated with the lead. |
| LEAD_SOURCE | integer | Corresponds with the 'Lead Source' custom value. Returns the numerical ID for the specific source tied with the lead. |
| LEAD_TYPE | integer | Corresponds with the 'Types' custom value. Returns the numerical ID for the specific type assigned to the lead. |
| LEAD_LOST_REASON | integer | Corresponds with the 'Closed Lost Reason' custom value. This custom value only appears as an option if the lead has been marked as closed. Returns the numerical ID for the reason. |
| LEAD_WON_REASON | integer | Corresponds with the 'Closed Won Reason' custom value. This custom value only appears as an option if the lead has been marked as won. Returns the numerical ID for the reason. |