Introduction
Even though active, this API is no longer supported. Click here for the latest API documentation.
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:
- Log into Contractors Cloud
- Main Menu -> Projects -> API Keys
- Once in the API Key Interface click Add
-
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
- 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'
);
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'
);
$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.