Getting Started
      Back to home
      1. ConstructionOnline API Documentation
      2. Getting Started

      Making API requests

      Learn how to make simple requests against the ConstructionOnline API

      In this article, you will learn how to perform basic create, update, and read requests with the ConstructionOnline API. These types of requests are the foundation for any integrations, automations, or custom builds with data from your ConstructionOnline company account, as they together work to "sync" your data from one application to another. This article will explore some of the capabilities of the ConstructionOnline API without fully building out any integrations or applications.

      By the end of this article, you will know how to extract and manage your data with the API. Extracted data can be immediately pulled into a custom report or spreadsheet if desired. We will cover examples with Contacts, which are an essential component of ConstructionOnline. Specifically, you will learn how to create a new contact, update a contact, and get your entire contact list using the API.

      Prerequisites

      You will need the following to start making requests against the ConstructionOnline API:

      • The email address and password for your ConstructionOnline account
      • An API key
      • A development environment for calling the API, whether it is an IDE, a code editor, or an API explorer tool like Postman

      Create a Contact

      In this example, we will walk through how to create a new contact using the ConstructionOnline API.

      Request

      The API endpoint for creating a new contact is:

      https://api.constructiononline.com/api/Contacts?contactInfo={contactInfo}

      To create a new contact, we will make a POST request to the URL above. The POST method allows you to send data to a server to create or update a resource. In this case, we are creating a new resource—the contact.

      Notice that there is a parameter in the URL called contactInfo. This is a request parameter that will send data to create the contact, such as the contact's name and email address. You can include data for contact object properties in the parameter, which should be entered in JSON key-value format, like so: {"EMAIL" : "alice@conwayconstruction.com"}. Please note that the properties FIRSTNAME, LASTNAME, EMAIL, and DISPLAY_NAME are required for contact creation and must be included in the parameter. All Contact object properties and their definitions can be found in the Contacts Overview article. 

      To avoid a lengthy request URL, we recommend that any properties beyond those required are added during a future update. We recommend that only the four required properties are included during creation.

      Code snippets for this endpoint in cURL, C#, Python, and JavaScript can be found here. Using one of the provided code snippets (or Postman), fill out the placeholder variables with your ConstructionOnline email address & password and API key. Replace the {contactInfo} placeholder with the properties for the contact. Once you've finished, you can run the code to make the call.

      Here's an example of making a request to the above API endpoint using the Python code snippet:

      import base64, requests, json
      #Global Variables
        apikey = "1234567890"
        username = "testuser@uda99.com"
        password = "Testuser1234"

      #Functions
        def makeRequest(endpoint, payload):
             url = "https://api.constructiononline.com/" + endpoint
             userPass = username + ":" + password    
             headers = {
                          "APIKey": apikey,
                          "Accept-Encoding": "gzip, deflate, br",
                          "Authorization": "Basic " + base64.b64encode(userPass.encode()).decode(),
                      }
             response = requests.request("POST", url, headers=headers, data=payload)
             return json.dumps(json.loads(response.text), indent=2)   
      #Main Program 
      print(makeRequest("api/contacts?contactInfo="EMAIL":"alice@conwayconstruction.com","FIRSTNAME":"Alice","LASTNAME":"Conway","DISPLAY_NAME":"Alice Conway"))

      Note that this example contains placeholder data. For this request to work correctly, you must replace the placeholders with your own credentials and API key. 

      Response

      After making your request to the API, you will receive a response in JSON format. The responses will contain a status code, which will indicate whether or not the request was successful. In this specific example, the API returned a 200 response. This indicates the request was successful and a resource (the contact) was created. In the sample response below, you can see the entire record of the returned contact.

      {
              "ID": 29,
              "FIRSTNAME": "Alice",
              "LASTNAME": "Conway",
              "EMAIL": "alice@conwayconstruction.com",
              "ACCOUNT": "",
              "LACCESS": "2023-09-21T19:23:10.97",
              "LMOD": "2023-04-21T13:51:13.673",
              "DISPLAY_NAME": "Alice Conway",
              "COMPANY": "",
              "ADDRESS": "",
              "CITY": "",
              "STATE": "",
              "ZIP": "",
              "PHONE": "",
              "MOBILE_PHONE": "",
              "MOBILE_PROVIDER": "",
              "FAX": "",
              "LMOD_CON_ID": 29,
              "LMOD_NAME": "",
              "ISCOMPANY": false,
              "MIDDLENAME": "",
              "WEBSITE": "",
              "CREATOR_ID": 29,
              "CREATOR_NAME": "",
              "TIMEZONE_OFFSET": -5.0,
              "AUTO_TIMEZONE": true,
              "COMPANY_ID": 0,
              "COMPANY_NAME": "",
              "COUNTRY_SETTING": 1,
              "LANGUAGE_SETTING": 1,
              "LAT": 32.538900,
              "LON": -85.492100,
              "COMPANY_PERMISSIONS": 0,
              "IS_COMPANY_ADMIN": true,
              "OFFLINE_FILES": null,
              "DATE_FORMAT": 0,
              "TIME_FORMAT": 0,
              "TIMEZONE_ID": "America/Chicago",
              "CONTACT_QUALITY": 0,
              "CONTACT_REGION": 0,
              "CONTACT_DIVISION": 0,
              "CONTACT_OFFICE": 0,
              "CONTACT_CATEGORY": 0,
              "CONTACT_TRADE": 0,
              "FIELD_ID": null,
              "MESSAGE_SIGNATURE": "",
              "GENERAL_CALENDAR_COLOR": "#FFA61B",
              "IS_LEAD": 0,
              "IS_SUB": 0,
              "IS_CLIENT": 0
          }

      Notice how the contact was automatically assigned a value for the property 'ID'. This property serves as a unique identifier for the contact, which you will need to know for any future references to the contact. The values for the properties we specified in our request (email, first name, last name, and display name) are also in the response. Any unspecified properties took on default values when the contact was created. A full list of all contact object properties and definitions can be found here. Now that you've created a contact, let's learn how to update it with additional properties.

      Update a Contact

      In this next example, we'll use the API to update the contact you just created with additional properties.

      Request

      The API endpoint for updating a single contact is:

      https://api.constructiononline.com/api/v2/Contacts?id={id}

      To update a contact, we will make a PUT request to the URL above. Notice that there is a parameter in the URL called id. This is a path parameter that will identify the specific contact you want to update. You will need to include the contact's ID value in the parameter. In our previous example, the contact was automatically assigned an ID of 29 during creation. This value will be used to identify the contact for update, as seen in the example URL below: 

      https://api.constructiononline.com/api/v2/Contacts?id=29

      For this example, let's update the contact's display name and add information for the properties COMPANY, PHONE, and ADDRESS. You should enter the properties to be updated in the payload of the request. For example:

      payload = "{\"DISPLAY_NAME\": \"Alice C\", \"COMPANY\": \"Conway Construction\", \"PHONE\": \"3345678900\", \"ADDRESS\": \"2234 Moores Mill Dr\"}"

      Code snippets for this endpoint in cURL, C#, Python, and JavaScript can be found here. Using one of the provided code snippets (or Postman), fill out the placeholder variables with your ConstructionOnline email address & password and API key. Replace the {id} placeholder with the contact's ID. Enter the data for updating the contact in the payload of the request. Once you've finished, you can run the code to make the call.

      Here's an example of making a request to the above API endpoint using the Python code snippet:

      import base64, requests, json

         #Global Variables
          apikey = {apikey}
          username = {username}
          password = {password}

          #Functions
           def makeRequest(endpoint, payload):
                 url = "https://api.constructiononline.com/" + endpoint
                  userPass = username + ":" + password    
                  headers = {
                          "APIKey": apikey,
                          "Accept-Encoding": "gzip, deflate, br",
                          "Authorization": "Basic " + base64.b64encode(userPass.encode()).decode(),
                      }
                      response = requests.request("PUT", url, headers=headers, data=payload)
                      return json.dumps(json.loads(response.text), indent=2)   
           #Main Program 
           payload = "{\"DISPLAY_NAME\": \"Alice C\", \"COMPANY\": \"Conway Construction\", \"PHONE\": \"3345678900\", \"ADDRESS\": \"2234 Moores Mill Dr\"}"
           print(makeRequest("api/Contacts?id={id}", payload)

      Response

      In this specific example, the API returned a 200 status with a record of the updated contact. In the response below, notice how the display name changed from "Alice Conway" to "Alice C" and values for the properties COMPANY, PHONE, and ADDRESS were added, while all other properties remained the same.

      {
              "ID": 29,
              "FIRSTNAME": "Alice",
              "LASTNAME": "Conway",
              "EMAIL": "alice@conwayconstruction.com",
              "ACCOUNT": "",
              "LACCESS": "2023-09-21T19:23:10.97",
              "LMOD": "2023-04-21T13:51:13.673",
              "DISPLAY_NAME": "Alice C",
              "COMPANY": "Conway Construction",
              "ADDRESS": "2234 Moores Mill Dr",
              "CITY": "",
              "STATE": "",
              "ZIP": "",
              "PHONE": "3345678900",
              "MOBILE_PHONE": "",
              "MOBILE_PROVIDER": "",
              "FAX": "",
              "LMOD_CON_ID": 29,
              "LMOD_NAME": "",
              "ISCOMPANY": false,
              "MIDDLENAME": "",
              "WEBSITE": "",
              "CREATOR_ID": 29,
              "CREATOR_NAME": "",
              "TIMEZONE_OFFSET": -5.0,
              "AUTO_TIMEZONE": true,
              "COMPANY_ID": 0,
              "COMPANY_NAME": "",
              "COUNTRY_SETTING": 1,
              "LANGUAGE_SETTING": 1,
              "LAT": 32.538900,
              "LON": -85.492100,
              "COMPANY_PERMISSIONS": 0,
              "IS_COMPANY_ADMIN": true,
              "OFFLINE_FILES": null,
              "DATE_FORMAT": 0,
              "TIME_FORMAT": 0,
              "TIMEZONE_ID": "America/Chicago",
              "CONTACT_QUALITY": 0,
              "CONTACT_REGION": 0,
              "CONTACT_DIVISION": 0,
              "CONTACT_OFFICE": 0,
              "CONTACT_CATEGORY": 0,
              "CONTACT_TRADE": 0,
              "FIELD_ID": null,
              "MESSAGE_SIGNATURE": "",
              "GENERAL_CALENDAR_COLOR": "#FFA61B",
              "IS_LEAD": 0,
              "IS_SUB": 0,
              "IS_CLIENT": 0
        }

      Finally, let's learn how to return how to use the API to return all contacts in a contact list—including the contact you just created.

      Get Contact List

      In this example, we'll use the API to return all contacts saved in your company's ConstructionOnline account.

      Request

      The API endpoint for getting a contact list is:

      https://api.constructiononline.com/api/v2/Contacts

      To return the entire contact list, we will make a GET request to the URL above. There are no parameters for this request. Code snippets for this endpoint in cURL, C#, Python, and JavaScript can be found here. Using one of the provided code snippets (or Postman), fill out the placeholder variables with your ConstructionOnline email address & password and API key. Once you've finished, you can run the code to make the call.

      Here's an example of making a request to the above API endpoint using the Python code snippet:

      import base64, requests, json
      apikey = "1234567890"
      username = "testuser@uda99.com"
      password = "Testuser1234"
      def makeRequest(endpoint):
          url = "https://api.constructiononline.com/" + endpoint
          userPass = username + ":" + password    
          headers = {
              "APIKey": apikey,
              "Accept-Encoding": "gzip, deflate, br",
              "Authorization": "Basic " + base64.b64encode(userPass.encode()).decode(),
          }
          response = requests.get(url, headers=headers)
          return json.dumps(json.loads(response.text), indent=2)   

      #Main Program 
      print(makeRequest("api/v2/Contacts"))

      Note that this example contains placeholder data. For this request to work correctly, you must replace the placeholders with your own credentials and API key. 

      Response

      In this specific example, the API returned a 200 status with a record of all contacts within the company account. For this specific example, the sample contact list contained two contacts, so only two contacts were returned. It is likely that your contact list is much larger than the sample and you will receive a lengthier response. 

      {
              "ID": 29,
              "FIRSTNAME": "Alice",
              "LASTNAME": "Conway",
              "EMAIL": "alice@conwayconstruction.com",
              "ACCOUNT": "",
              "LACCESS": "2023-09-21T19:23:10.97",
              "LMOD": "2023-04-21T13:51:13.673",
              "DISPLAY_NAME": "Alice C",
              "COMPANY": "Conway Construction",
              "ADDRESS": "2234 Moores Mill Dr",
              "CITY": "",
              "STATE": "",
              "ZIP": "",
              "PHONE": "",
              "MOBILE_PHONE": "",
              "MOBILE_PROVIDER": "",
              "FAX": "",
              "LMOD_CON_ID": 29,
              "LMOD_NAME": "",
              "ISCOMPANY": false,
              "MIDDLENAME": "",
              "WEBSITE": "",
              "CREATOR_ID": 29,
              "CREATOR_NAME": "",
              "TIMEZONE_OFFSET": -5.0,
              "AUTO_TIMEZONE": true,
              "COMPANY_ID": 0,
              "COMPANY_NAME": "",
              "COUNTRY_SETTING": 1,
              "LANGUAGE_SETTING": 1,
              "LAT": 32.538900,
              "LON": -85.492100,
              "COMPANY_PERMISSIONS": 0,
              "IS_COMPANY_ADMIN": true,
              "OFFLINE_FILES": null,
              "DATE_FORMAT": 0,
              "TIME_FORMAT": 0,
              "TIMEZONE_ID": "America/Chicago",
              "CONTACT_QUALITY": 0,
              "CONTACT_REGION": 0,
              "CONTACT_DIVISION": 0,
              "CONTACT_OFFICE": 0,
              "CONTACT_CATEGORY": 0,
              "CONTACT_TRADE": 0,
              "FIELD_ID": null,
              "MESSAGE_SIGNATURE": "",
              "GENERAL_CALENDAR_COLOR": "#FFA61B",
              "IS_LEAD": 0,
              "IS_SUB": 0,
              "IS_CLIENT": 0
        },

      {
              "ID": 30,
              "FIRSTNAME": "James",
              "LASTNAME": "Smith",
              "EMAIL": "james@conwayconstruction.com",
              "ACCOUNT": "",
              "LACCESS": "2023-10-21T19:23:10.97",
              "LMOD": "2023-08-21T13:51:13.673",
              "DISPLAY_NAME": "James Smith",
              "COMPANY": "Conway Construction",
              "ADDRESS": "2234 Moores Mill Dr",
              "CITY": "Atlanta",
              "STATE": "GA",
              "ZIP": "",
              "PHONE": "",
              "MOBILE_PHONE": "",
              "MOBILE_PROVIDER": "",
              "FAX": "",
              "LMOD_CON_ID": 29,
              "LMOD_NAME": "",
              "ISCOMPANY": false,
              "MIDDLENAME": "",
              "WEBSITE": "",
              "CREATOR_ID": 29,
              "CREATOR_NAME": "",
              "TIMEZONE_OFFSET": -5.0,
              "AUTO_TIMEZONE": true,
              "COMPANY_ID": 0,
              "COMPANY_NAME": "",
              "COUNTRY_SETTING": 1,
              "LANGUAGE_SETTING": 1,
              "LAT": 32.538900,
              "LON": -85.492100,
              "COMPANY_PERMISSIONS": 0,
              "IS_COMPANY_ADMIN": true,
              "OFFLINE_FILES": null,
              "DATE_FORMAT": 0,
              "TIME_FORMAT": 0,
              "TIMEZONE_ID": "America/Chicago",
              "CONTACT_QUALITY": 0,
              "CONTACT_REGION": 0,
              "CONTACT_DIVISION": 0,
              "CONTACT_OFFICE": 0,
              "CONTACT_CATEGORY": 0,
              "CONTACT_TRADE": 0,
              "FIELD_ID": null,
              "MESSAGE_SIGNATURE": "",
              "GENERAL_CALENDAR_COLOR": "#FFA61B",
              "IS_LEAD": 0,
              "IS_SUB": 0,
              "IS_CLIENT": 0
      }

      The simple create, update, and read operations that we just performed can also be applied to many other objects in the ConstructionOnline API, such as Projects and Leads. Visit the ConstructionOnline API documentation for a comprehensive collection of reference docs for objects and endpoints currently documented in the API.

      Have more questions? 

      • Frequently asked questions (FAQs) regarding getting started with the ConstructionOnline API can be found here.
      • If you need additional assistance, please contact the ConstructionOnline development team at api@uda1.com.