Introduction

The Contractors Cloud API is based on REST principles. All access to the API occurs over SSL-encrypted secure channel, so your API client must support SSL. Every Contractors Cloud account receives a unique API key that is used to custom develop and connect Contractors Cloud to their applications.

Currently, the Contractors Cloud API is only geared to importing leads/projects into Contractors Cloud. Exporting data out of Contractors Cloud is not yet available.

Contractors Cloud requires more than just name, address, and phone number to create a lead/project. We require things like a company, lead source, event and other data. Therefore, you can custom create API Keys including defaults for the required data. This means that these default values will always be applied to the incoming records.

If Contractors Cloud has everything it needs, it will automatically create the lead/project and once it is instantly created, workflows and custom alerts can automatically be applied.

If Contractors Cloud senses missing information, then the incoming record will be placed in our API Import Queue where it will sit until a user fills in the missing information.

The API Key generation tool and the API Import Queue are only available in our Contractors Cloud RainMaker version. However, any incoming data will be available in both Classic and RainMaker versions.

Generating API Keys

Before sending data to Contractors Cloud, you need to generate an API Key.

The API Key defines who you are, who we are and also embeds defaults needed to create a project in Contractors Cloud.

You can use a single API Key in multiple integrations of your choice.

You can generate an API Key as follows:

  1. Log into Contractors Cloud RainMaker - https://dev.contractorscloud.com/login.php
  2. Main Menu -> Tools -> API Keys
  3. Once in the API Key Interface click Add
  4. Complete the form by designating defaults and click Save API Key
    NOTE: Once an API Key is created, you will NOT be able to edit it. Therefore, if you want a new set of defaults for a particular integration, you will need to delete the existing API Key and generate a new one
  5. Once an API Key is generated, provide the key to the integration partner. Depending on the integration partner, you may need to cut and paste or email the key depending on their integration interface.

Base URL

All URLs referenced in the documentation have the following base:
https://app.contractorscloud.com

Authentication

Once your data is ready to send, you can authenticate and make your HTTP POST to https://app.contractorscloud.com/api/v2/import/record

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, base64_encode('api:YOUR_API_KEY'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL,'https://app.contractorscloud.com/api/v2/import/record');
curl_setopt($ch, CURLOPT_POSTFIELDS, $arPostFields);
$result = curl_exec($ch);
curl_close($ch);

// **** output returned value ****
print_r(json_decode($result));

NOTE: CURLOPT_USERPWD requires base64 encoding

The API will return a JSON-encoded string with the result of your import. We're promiscuous so just about anything is accepted. Records will automatically get entered into our system. API key settings and validation will determine if the data is automatically converted into a job or moved to a queue for human-intervention.

Requests

Contractors Cloud accepts HTTP POST commands and also accepts POSTs of JSON-formatted strings.

To send data to Contractors Cloud, generate an HTTP POST of a key/value pair or HTTP POST a JSON string with the following values:

$arPostFields = array(
	'req_firstname' => 'John',
	'req_lastname' => 'Doe',
	'req_accountname' => 'Doe Account',
	'req_street' => '123 Main St.',
	'req_city' => 'Anytown',
	'req_state' => 'MN',
	'req_zip' => '55123',
		'req_oppdate' => '2020-01-02 12:34:56',
	'req_oppnum' => 'Your_Job_Number',
	'opt_emailPrimary' => 'email',
	'opt_phonePrimary' => '(123) 123-1234',
	'opt_phoneAlternate' => '(321) 321-4321',
	'opt_oppname' => 'Name_Of_Project',
	'opt_lat' => 'Project_Latitude',
	'opt_long' => 'Project_Longitude',
	'source' => 'source',
	'opt_note1' => 'service',
	'opt_note2' => 'comments',
	'opt_note3' => 'spectrumId'
	'opt_note4' => 'Your_additional_project_note'
);

Responses

Contractors Cloud returns resource representations as JSON. The API response is wrapped in a standard structure which holds the results for the API call.

HTTP/1.1 401 Unauthorized

  • Authentication failure
  • Too many requests (>100 per minute)
  • Disabled account

HTTP/1.1 200 OK

  • JSON-encoded string of the newly-created record. This record is added to a queue and processed asynchronously.

Schema

Below describes the fields available within the integration.

	'req_firstname'
	REQUIRED
	String
	First name of the person contact
	Example: ‘John’

	'Req_lastname'
	REQUIRED
	String
	Last name of the person contact
	Example: ‘Smith’

	'req_accountname'
	REQUIRED
	String
	Name of the account
	Example: Smith, John or Business Name, LLC

	'req_street'
	REQUIRED
	String
	Line 1 Street Address
	Example: 123 Contractor St

	'req_city'
	REQUIRED
	String
	City
	Example: Oklahoma City

	'req_state'
	REQUIRED
	String
	2-letter abbreviation
	Example: MN, CO, TX, OK, etc

	'req_zip'
	REQUIRED
	String
	At least a 5-digit zip code
	Example: 73120

	'req_oppdate'
	REQUIRED
	Mysql date format: 'YYYY-MM-DD HH:MM:SS'
	A date for the record. Typically the creation date of the lead/project
	Example: 2009-05-16 13:45:12

	'req_oppnum'
	OPTIONAL
	String
	Any number/letter combination job number representation
	Example: AP1234, 20-1025

	'opt_emailPrimary'
	OPTIONAL
	String
	Email in valid format for person contact
	Example: jsmith@samplecontracting.com


	'opt_phonePrimary'
	OPTIONAL
	String
	Primary phone in valid format for person contact
	Example: 555-555-5555

	'opt_phoneAlternate'
	OPTIONAL
	String
	Alternate phone in valid format for person contact
	Example: 555-555-5555

	'opt_oppname'
	OPTIONAL
	String
	Optional lead/project name
	Example: John Smith House

	'opt_lat'
	OPTIONAL
	String
	Latitude of project address
	Example: 35.468063
	Note: We geocode missing latitudes

	'opt_lat'
	OPTIONAL
	String
	Longitude of project address
	Example: -97.522477
	Note: We geocode missing longitudes

	'givenleadsource'
	OPTIONAL
	String - Varchar (155)
	Your lead source name
	Example: Website Form, Angies List, BBB, SalesRabbit, etc
	Note:
	If this lead source name matches a lead source name within Contractors Cloud, we’ll automatically match values.

	However, if there is no match, the user can create it on the fly within the API Import Queue.

	'givenrepname'
	OPTIONAL
	String - Varchar (155)
	Name of the Contractors Cloud user/Rep that will be assigned to the Contractors Cloud lead/project
	Example: John Smith, Peter Parker, etc

	Note:
	If this rep name matches a rep name within Contractors Cloud, we’ll automatically match values.

	However, if there is no match, the user will have to be manually created in Contractors Cloud and manually assigned.

	This is NOT required

	'givenstausname'
	OPTIONAL
	String - Varchar (155)
	Name of your lead/project status that will be assigned to the Contractors Cloud lead/project
	Example: Closed, Completed, Lead
	Note:
	If this status name matches a status name within Contractors Cloud, we’ll automatically match values.

	However, if there is no match, the user will have to assign the Contractors Cloud project status within the API Import Queue. There is no custom statuses within Contractors Cloud.

	This is NOT required

	'source'
	OPTIONAL
	String - Varchar (155)
	Longitude of project address
	Example: -97.522477
	Note: We geocode missing longitudes

	'source_oppid'
	OPTIONAL
	String - Varchar (155)
	This is your ID of your record. This will be used in the future to match and update records when the 2-way sync is available

	'opt_note1'
	OPTIONAL
	String/Text
	Note: Any additional data passed here will become a project note upon import.

	'opt_note2'
	OPTIONAL
	String/Text
	Note: Any additional data passed here will become a project note upon import.

	'opt_note3'
	OPTIONAL
	String/Text
	Note: Any additional data passed here will become a project note upon import.

	'opt_note4'
	OPTIONAL
	String/Text
	Note: Any additional data passed here will become a project note upon import.

	

Change Log

March 27th, 2020 - No changes at this time

Contact

if you have any questions contact: developer@contractorscloud.com