Common examples

Here are some examples for some of the most common integrations.

We realize the size of this API with all of it's features, endpoints and types may seem overwhelming. Most integrations we see really only need to perform one or two actions such as creating a contact or creating a new lead / Project. To save you time, we have documented the most common integration examples for you to quickly get started.

Creating a project

Creating a new Project is probably the most common use case. A Project relies on a handful of other resources so unless you have all the required data already available, you will need to make several API calls prior to creating a Project to collect all the necessary data.

Looking at the Create project endpoint, the following fields are required in your json payload for the POST call. Each item described here also has a link to the corresponding endpoint where you can retrieve the ids / data you will need:

Once you have collected all the required data, your json payload for creating a Project should resemble something like this but will differ depending on how your Contractors Cloud account is setup:

{
	"company_id": 6,
	"account_id": 2206779,
	"contact_ids": [13,1469],
	"site_type_id": 11,
	"lead_id": 7870,
	"referred_by": 1470,
	"event_id": 8,
	"workflow_id": null,
	"rep_primary_id": 10007,
	"company_custom_fields": [
		{
			"id": 2,
			"value": "Yes"
		},
		{
			"id": 1453,
			"value": "2023-07-24"
		},
		{
			"id": 1391,
			"value": null
		},
		{
			"id": 1,
			"value": "20-30"
		}
	],
	"name": "Roofing job in Falvortown",
	"address_street": "123 Example Street",
	"address_city": "Delano",
	"address_state": "MN",
	"address_zip": "55328",
	"address_description": null,
	"needs_appointment": false
}

❗ Required Fields: Depending on the Company a project is being created for, there may be additional CustomFields which will be required for Project creation. Additionally, fields such as workflow_id and name may also be required and their requirement is dictated by the corresponding Company settings.

Searching contacts

When getting a listing of Contacts from the Read contacts endpoint, you'll probably want to find, search and sort for specific Contacts. This can be achieved via query params as documented in the Making requests section. The Contact resource has a handful of filters and sorts that can be applied when performing your request.

For example, say you want to get a listing of Contacts that match the search term "steve", have values for an email and cell phone and sort the list of Contacts by their last name in descending order. Your request query would look something like this:

GET: /api/v1/contacts?filter[search]=steve&sort=-last_name&filter[has_attributes]=email,phone_cell