Opportunities
      Back to home
      1. ConstructionOnline API Documentation
      2. Projects + Opportunities
      3. Opportunities

      Opportunities Overview

      Discover more about the opportunity object and its related properties

      Table of Contents

      1. Introduction
      2. Opportunity Object
      3. Endpoints

      Introduction

      In ConstructionOnline, an opportunity is a potential deal, or project, that has been identified as having a high probability of converting successfully. Opportunities are created from leads, who are potential construction clients for the project. Opportunities are similar to projects in ConstructionOnline, with options to set a scope of work, create an estimate, send messages, and more. However, opportunities are limited and do not have all of the same features as projects in ConstructionOnline.

      Opportunity Object

      The opportunity object represents an individual opportunity in ConstructionOnline. Each opportunity object returns multiple properties that reveal specific details about the opportunity, such as its name, contract price, address, and scope of work. Each property corresponds to a specific detail from within the Opportunity itself, which can be found within Opportunity Details or from a specific feature like Files. 

      Each opportunity object is referenced by a unique numerical ID, which is stored in the property 'ID'. An opportunity's ID is automatically assigned during creation and cannot be modified. Please note that a opportunity's ID is not the same as its opportunity or project number in ConstructionOnline. To update or return a specific opportunity, you must know the opportunity's ID. Each opportunity object will contain at least a 'NAME', as this property is required for creation. The remaining opportunity object properties are optional. Some properties are automatically assigned a default value when an opportunity is created. Others will return null if a value has not been set for the specific property. 

      Note that some of the following properties are specific to Projects and will only contain values if the opportunity was created from a project template. These values will only appear in ConstructionOnline if the opportunity is later converted to a project.

      Name Type Description
      ID integer Unique identifier for the opportunity.
      NAME string Name of the opportunity.
      CREATED_BY integer Unique identifier for the user who created the opportunity. 
      CREATOR_NAME string Name of the user who created the opportunity.
      LMOD date Date and time the opportunity was last modified.
      ADDRESS string Opportunity's address.
      CITY string Opportunity's city.
      STATE string Opportunity's state.
      ZIP string Opportunity's zip code.
      PROJECT_NUMBER string Opportunity/project number assigned to the opportunity.
      LMOD_CON_ID integer Unique identifier for the user who last modified the opportunity.
      IS_ARCHIVED  boolean Reserved for future use.
      IS_TEMPLATE boolean Signifies if the opportunity was created from a template.
      CURRENCY integer Type of currency set for the opportunity. Each type of currency corresponds to a specific number, which will be returned in this property. 
      COUNTRY_SETTING integer Number representing the specific country associated with the opportunity.
      CUSTOM_COLOR string Opportunity's color as it appears in ConstructionOnline. Returns the specific hex code for the color.
      COMPANY_ID string Unique identifier for the company associated with the opportunity.
      IS_INACTIVE boolean Signifies if the opportunity has a status of 'Live' or 'Pending'. Returns true if the opportunity is Pending, false if the opportunity is Live.
      ADDR_LAT double Opportunity's entered latitude coordinates.
      LAT double Latitude coordinates of the nearest weather station to the opportunity.
      ADDR_LONG   Opportunity's entered longitude coordinates.
      LON double Longitude coordinates of the nearest weather station to the opportunity.
      SCOPE_OF_WORK string Scope of work entered for the opportunity. Returns as an encoded string.
      TOTAL_TIME integer Only returns a value if the opportunity was created from a project template, else will return 0. Returns the project template's initial duration. This value will only appear in ConstructionOnline when the opportunity is later converted to a project. 
      TOTAL_MONEY double Only returns a value if the opportunity was created from a project template, else will return 0.0. Returns the project template's initial contract price. This value will only appear in ConstructionOnline when the opportunity is later converted to a project. 
      PROJECT_NOTES string Reserved for future use.
      NUMBERFOLDERS integer Number of folders saved within the opportunity.
      NUMBERIMAGES integer Number of images saved within the opportunity.
      NUMBERALBUMS integer Number of albums saved within the opportunity.
      NUMBERFILES integer Number of files saved within the opportunity.
      DATE_CREATED date Date and time the opportunity was created.
      PROJECT_TYPE string Name of the project type assigned to the opportunity. The unique numerical ID for the specific project type is listed in the property 'PROJECT_TYPE_ID'.
      ATTACH_FOLDER_ID integer Attachment folder location for files, photos, etc. 
      ESTIMATE_UNQUALIFIED_COMMITS integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported POs from QuickBooks that do not match anything in the estimate. 
      ESTIMATE_UNQUALIFIED_ACTUALS integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported actuals from QuickBooks that do not match anything in the estimate. 
      ESTIMATE_UNQUALIFIED_EXPENSES integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported invoices from QuickBooks that do not match anything in the estimate. 
      SELECTION_UNQUALIFIED_COMMITS integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported POs from QuickBooks that do not match any selections. 
      SELECTION_UNQUALIFIED_ACTUALS integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported actuals from QuickBooks that do not match any selections. 
      SELECTION_UNQUALIFIED_EXPENSES integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported invoices from QuickBooks that do not match any selections.
      CHANGE_ORDER_UNQUALIFIED_COMMITS integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported POs from QuickBooks that do not match any change orders.
      CHANGE_ORDER_UNQUALIFIED_ACTUALS integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported actuals from QuickBooks that do not match any change orders.
      CHANGE_ORDER_UNQUALIFIED_EXPENSES integer Only returns a value if the opportunity was created from a project template, else will return null. Total value of any imported invoices from QuickBooks that do not match any change orders.
      PRIMARY_SCHEDULE integer Only returns a value if the opportunity was created from a project template, else will return null. Unique numerical ID representing the schedule tied to the project. This schedule will only appear if and when the opportunity is later converted to a project. 
      COST_CODE_SET integer Number associated with the cost code list assigned to the opportunity. Returns null if a cost code list has not been assigned.
      IS_OPPORTUNITY boolean
      		 Always returns true for opportunities.
      OPPORTUNITY_STATUS integer Closed/open status of the opportunity. Returns the integer that corresponds with the selected status.
      OPPORTUNITY_REFERRER  string Email address of the user who referred the opportunity.
      OPPORTUNITY_PROBABILITY  integer Probability entered for the opportunity. Returned value will 0, 25, 50, 75, or 100. 
      OPPORTUNITY_VALUE double Value entered for the opportunity.
      OPPORTUNITY_OPENED_DATE date Date the opportunity was opened. 
      OPPORTUNITY_CLOSED_DATE date Date the opportunity was closed.
      OPPORTUNITY_QUALITY integer Quality associated with the opportunity. Returns the star rating as a integer between 1 and 5. Returns null if no rating has been assigned. 
      OPPORTUNITY_NOTES string Notes entered for the opportunity.
      OPPORTUNITY_CONVERTED_DATE date Date the opportunity was converted to a project.
      OPPORTUNITY_LEAD integer Reserved for future use.

      In addition to the properties above, opportunity 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
      PROJECT_TYPE_CUSTOM integer Corresponds to the 'Project Type' custom value. Returns the numerical ID for the specific project type associated with the opportunity. The name of the specific type is listed in the property 'PROJECT_TYPE'.
      OPPORTUNITY_STAGE integer Corresponds to the 'Opportunity Stage' custom value. Returns the numerical ID for the specific stage associated with the opportunity.
      OPPORTUNITY_SOURCE integer Corresponds to the 'Opportunity Source' custom value. Returns the numerical ID for the specific source tied to the opportunity.
      OPPORTUNITY_TYPE integer Corresponds to the 'Opportunity Type' custom value. Returns the numerical ID for the specific type associated with the opportunity.
      OPPORTUNITY_WON_REASON integer Corresponds to the 'Opportunity Won Reason' custom value. Returns the numerical ID for the specific reason why the opportunity was won.
      OPPORTUNITY_CLOSED_REASON integer Corresponds to the 'Opportunity Closed Reason' custom value. Returns the numerical ID for the specific reason why the opportunity was closed.