List projects

List projects

curl --request GET \
  --url https://api.contractorscloud.com/api/v1/projects \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.contractorscloud.com/api/v1/projects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.contractorscloud.com/api/v1/projects",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.contractorscloud.com/api/v1/projects"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.contractorscloud.com/api/v1/projects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "current_page": 1,
  "data": [
    {
      "id": 9103,
      "tenant_id": 12,
      "company_id": 6,
      "account_id": 5190,
      "status_id": 3,
      "event_id": 214,
      "lead_id": 372,
      "storm_id": null,
      "group_id": null,
      "workflow_id": 58,
      "site_type_id": 4,
      "cancellation_id": null,
      "rep_primary_id": 1159,
      "mortgage_company_id": null,
      "original_milestone_id": 1040,
      "current_project_milestone_id": 1042,
      "referred_by": 5107,
      "companycam_id": null,
      "hash": "f3a1c9e7b2d84f6a9c1e3b7d5a2f9c4e",
      "number": "2025-0184",
      "name": "Smith Residence - Roof Replacement",
      "account_name": "Jane Smith",
      "address_street": "482 Birchwood Ave",
      "address_city": "Madison",
      "address_state": "WI",
      "address_zip": "53703",
      "address_description": null,
      "address_latitude": "43.073100",
      "address_longitude": "-89.401200",
      "needs_appointment": true,
      "is_in_collections": false,
      "rep_primary_name": "Jane Doe",
      "percent_completed": "45.00",
      "percent_sale_close": "75.00",
      "amount_estimated": "18500.00",
      "mortgage_loan_number": null,
      "estimated_total_amount": "18500.00",
      "payouts_amount": "0.00",
      "overhead_amount": "0.00",
      "expenses_pending_amount": "0.00",
      "expenses_approved_amount": "0.00",
      "expenses_paid_amount": "0.00",
      "expenses_denied_amount": "0.00",
      "expenses_total_amount": "0.00",
      "financials_pending_amount": "0.00",
      "financials_approved_amount": "9250.00",
      "financials_billable_amount": "9250.00",
      "financials_sold_amount": "18500.00",
      "financials_total_amount": "18500.00",
      "financials_down_payment_amount": "5000.00",
      "financials_progress_payment_amount": "4250.00",
      "financials_final_paid_amount": "0.00",
      "financials_deductible_paid_amount": "0.00",
      "financials_all_paid_amount": "9250.00",
      "financials_total_paid_amount": "9250.00",
      "financials_credit_memo_amount": "0.00",
      "financials_refund_amount": "0.00",
      "financials_revenue_amount": "9250.00",
      "financials_revenue_approved_amount": "9250.00",
      "financials_received_amount": "9250.00",
      "financials_balance_amount": "9250.00",
      "last_note_created_at": "2025-02-14 10:05:00",
      "is_in_collections_at": null,
      "first_contract_at": "2025-02-11 09:30:00",
      "first_contract_approved_at": "2025-02-12 16:00:00",
      "first_appointment_at": "2025-02-10 13:00:00",
      "appointment_recommended_at": null,
      "sale_closed_at": "2025-02-12 16:00:00",
      "referred_at": null,
      "callback_at": "2025-02-10 09:15:00",
      "completed_at": null,
      "created_at": "2025-02-10 09:15:00",
      "updated_at": "2025-02-14 10:05:00",
      "deleted_at": null
    }
  ],
  "first_page_url": "https://api.contractorscloud.com/api/v1/projects?page[number]=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://api.contractorscloud.com/api/v1/projects?page[number]=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://api.contractorscloud.com/api/v1/projects?page[number]=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://api.contractorscloud.com/api/v1/projects",
  "per_page": 30,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

{
  "message": "Unauthenticated."
}

GET

projects

List projects

curl --request GET \
  --url https://api.contractorscloud.com/api/v1/projects \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.contractorscloud.com/api/v1/projects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.contractorscloud.com/api/v1/projects",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.contractorscloud.com/api/v1/projects"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.contractorscloud.com/api/v1/projects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "current_page": 1,
  "data": [
    {
      "id": 9103,
      "tenant_id": 12,
      "company_id": 6,
      "account_id": 5190,
      "status_id": 3,
      "event_id": 214,
      "lead_id": 372,
      "storm_id": null,
      "group_id": null,
      "workflow_id": 58,
      "site_type_id": 4,
      "cancellation_id": null,
      "rep_primary_id": 1159,
      "mortgage_company_id": null,
      "original_milestone_id": 1040,
      "current_project_milestone_id": 1042,
      "referred_by": 5107,
      "companycam_id": null,
      "hash": "f3a1c9e7b2d84f6a9c1e3b7d5a2f9c4e",
      "number": "2025-0184",
      "name": "Smith Residence - Roof Replacement",
      "account_name": "Jane Smith",
      "address_street": "482 Birchwood Ave",
      "address_city": "Madison",
      "address_state": "WI",
      "address_zip": "53703",
      "address_description": null,
      "address_latitude": "43.073100",
      "address_longitude": "-89.401200",
      "needs_appointment": true,
      "is_in_collections": false,
      "rep_primary_name": "Jane Doe",
      "percent_completed": "45.00",
      "percent_sale_close": "75.00",
      "amount_estimated": "18500.00",
      "mortgage_loan_number": null,
      "estimated_total_amount": "18500.00",
      "payouts_amount": "0.00",
      "overhead_amount": "0.00",
      "expenses_pending_amount": "0.00",
      "expenses_approved_amount": "0.00",
      "expenses_paid_amount": "0.00",
      "expenses_denied_amount": "0.00",
      "expenses_total_amount": "0.00",
      "financials_pending_amount": "0.00",
      "financials_approved_amount": "9250.00",
      "financials_billable_amount": "9250.00",
      "financials_sold_amount": "18500.00",
      "financials_total_amount": "18500.00",
      "financials_down_payment_amount": "5000.00",
      "financials_progress_payment_amount": "4250.00",
      "financials_final_paid_amount": "0.00",
      "financials_deductible_paid_amount": "0.00",
      "financials_all_paid_amount": "9250.00",
      "financials_total_paid_amount": "9250.00",
      "financials_credit_memo_amount": "0.00",
      "financials_refund_amount": "0.00",
      "financials_revenue_amount": "9250.00",
      "financials_revenue_approved_amount": "9250.00",
      "financials_received_amount": "9250.00",
      "financials_balance_amount": "9250.00",
      "last_note_created_at": "2025-02-14 10:05:00",
      "is_in_collections_at": null,
      "first_contract_at": "2025-02-11 09:30:00",
      "first_contract_approved_at": "2025-02-12 16:00:00",
      "first_appointment_at": "2025-02-10 13:00:00",
      "appointment_recommended_at": null,
      "sale_closed_at": "2025-02-12 16:00:00",
      "referred_at": null,
      "callback_at": "2025-02-10 09:15:00",
      "completed_at": null,
      "created_at": "2025-02-10 09:15:00",
      "updated_at": "2025-02-14 10:05:00",
      "deleted_at": null
    }
  ],
  "first_page_url": "https://api.contractorscloud.com/api/v1/projects?page[number]=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://api.contractorscloud.com/api/v1/projects?page[number]=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://api.contractorscloud.com/api/v1/projects?page[number]=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://api.contractorscloud.com/api/v1/projects",
  "per_page": 30,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

{
  "message": "Unauthenticated."
}

Authorizations

Authorization

string

header

required

Authenticate with an API access token in the Authorization header: Authorization: Bearer <token>. Create a token from the API Access Tokens page in Contractors Cloud, under Integrations.

Query Parameters

page[number]

integer

default:1

The 1-indexed page number to retrieve.

Required range: x >= 1

page[size]

integer

default:30

The number of results per page (max 100).

Required range: 1 <= x <= 100

filter[id]

integer

Exact match on the project's id.

filter[company_id]

integer

Exact match on the id of the company the project belongs to.

filter[account_id]

integer

Exact match on the id of the account the project belongs to.

filter[status_id]

integer

Exact match on the id of the project's current status.

filter[site_type_id]

integer

Exact match on the id of the project's site type.

filter[workflow_id]

integer

Exact match on the id of the workflow the project follows.

filter[event_id]

integer

Exact match on the id of the event the project originated from.

filter[lead_id]

integer

Exact match on the id of the lead source the project originated from.

filter[storm_id]

integer

Exact match on the id of the storm the project is associated with.

filter[group_id]

integer

Exact match on the id of the group the project belongs to.

filter[mortgage_company_id]

integer

Exact match on the id of the mortgage company financing the project.

filter[name]

string

Partial match on the project's name.

filter[search]

string

Fuzzy search across the project's name and address, its linked account's name, address, and phone numbers, and the first and last names of any contacts linked to the project or its account.

filter[has_work_orders]

boolean

Limit to projects that do (1) or don't (0) have any work orders.

filter[has_unscheduled_work_orders]

boolean

Limit to projects that do (1) or don't (0) have any unscheduled work orders.

filter[extended_property]

object

Filters by an extended property's key and value, using the syntax filter[extended_property][<key>]=<value>. Matches projects with an extended property whose key equals <key> and whose value exactly equals <value> (comma-separate multiple values to match any of them).

Hide child attributes

filter[extended_property].{key}]

string

filter[deleted]

boolean

Records deleted from the Contractors Cloud web app are hidden by default. Pass filter[deleted]=true to include them. Deleting a project through Delete project removes it permanently rather than marking it deleted.

include

string

Comma-separated related resources to embed. Allowed: lead (the project's lead source), event, storm, group, status, company, account, workflow, cancellation, referrer, site_type, rep_primary, mortgage_company, cover_photo, extended_properties.

sort

string

Field to sort by. Prefix with - for descending. Allowed: id, status_id, number, name, address_street, address_city, address_state, percent_completed, updated_at, created_at, last_note_created_at, callback_at, first_appointment_at, completed_at, first_contract_approved_at.

Response

A paginated list of projects.

data

object[]

Hide child attributes

data.id

integer

The project's unique identifier.

Example:

9103

data.tenant_id

integer | null

The id of your organization's account.

Example:

12

data.company_id

integer

The id of the company this project belongs to.

Example:

6

data.account_id

integer

The id of the account this project belongs to.

Example:

5190

data.status_id

integer

The id of the project's current status.

Example:

3

data.event_id

integer | null

The id of the event this project originated from. Null if not set.

Example:

214

data.lead_id

integer | null

The id of the lead source this project originated from. Null if not set. Only active lead sources can be selected.

Example:

372

data.storm_id

integer | null

The id of the storm this project is associated with. Null if not associated with a storm.

data.group_id

integer | null

The id of the group this project belongs to. Null if not grouped.

data.workflow_id

integer | null

The id of the workflow this project follows. Null if no workflow is assigned.

Example:

58

data.site_type_id

integer | null

The id of the project's site type, from the site-type reference data (see List available options). Null if not set.

Example:

4

data.cancellation_id

integer | null

The id of the cancellation reason recorded for this project. Null unless the project was canceled.

data.rep_primary_id

integer | null

The id of the user assigned as this project's primary rep. Null if unassigned.

Example:

1159

data.mortgage_company_id

integer | null

The id of the mortgage company financing this project. Null if not financed.

data.original_milestone_id

integer | null

The id of the milestone this project was on when it was created. Null if not tracked.

data.current_project_milestone_id

integer | null

The id of the project's current milestone. Null if not on one.

data.referred_by

integer | null

The id of the contact who referred this project. Null if not referred.

data.companycam_id

integer | null

An identifier linking this project to a record in a connected third-party service. Null if not connected. Only settable through Update project.

data.hash

string | null

An opaque value that uniquely identifies this project. Null if not yet generated.

Example:

"f3a1c9e7b2d84f6a9c1e3b7d5a2f9c4e"

data.number

string

The project's user-facing number (up to 15 characters). A newly created project holds the placeholder value Lead until it's set to a real value — number cannot be set on create, and Update project is the only place it can be set.

Example:

"2025-0184"

data.name

string | null

The project's name. Null if not set. Required (and cannot be blank) for companies that require project names.

Example:

"Smith Residence - Roof Replacement"

data.account_name

string | null

The linked account's display name, kept in sync with the account's primary contact or business name. Null if not set.

Example:

"Jane Smith"

data.address_street

string | null

The street portion of the project's address. Null if not provided.

Example:

"482 Birchwood Ave"

data.address_city

string | null

The city portion of the project's address. Null if not provided.

Example:

"Madison"

data.address_state

string | null

The two-letter state or province code for the project's address. Null if not provided.

Example:

"WI"

data.address_zip

string | null

The postal code for the project's address. Null if not provided.

Example:

"53703"

data.address_description

string | null

A free-form description of the project's site or address, such as access instructions. Null if not provided.

data.address_latitude

string | null

The latitude of the project's address, as a decimal string. Null if the address hasn't been geocoded.

Example:

"43.073100"

data.address_longitude

string | null

The longitude of the project's address, as a decimal string. Null if the address hasn't been geocoded.

Example:

"-89.401200"

data.needs_appointment

boolean

Whether this project needs an appointment scheduled.

Example:

true

data.is_in_collections

boolean

Whether this project is currently marked as in collections.

Example:

false

data.rep_primary_name

string

The primary rep's full name. Reads TBD when no rep is assigned.

Example:

"Jane Doe"

data.percent_completed

string

The percentage of the project considered complete, formatted as a decimal string.

Example:

"45.00"

data.percent_sale_close

string

The estimated probability of this project's sale closing, expressed as a percentage and formatted as a decimal string.

Example:

"75.00"

data.amount_estimated

string

The estimated dollar amount for this project, formatted as a decimal string. Defaults to "0.00" when not provided.

Example:

"18500.00"

data.mortgage_loan_number

string | null

The loan number associated with the project's financing. Null if not financed or not provided.

data.estimated_total_amount

string

The project's total estimated amount across all of its estimates, formatted as a decimal string. Always present, regardless of financial data permissions.

Example:

"18500.00"

data.payouts_amount

string

The total amount paid out on this project (for example, to reps).

Example:

"0.00"

data.overhead_amount

string

The total overhead amount allocated to this project.

Example:

"0.00"

data.expenses_pending_amount

string

The total amount of pending (unapproved) expenses on this project.

Example:

"0.00"

data.expenses_approved_amount

string

The total amount of approved expenses on this project.

Example:

"0.00"

data.expenses_paid_amount

string

The total amount of expenses paid on this project.

Example:

"0.00"

data.expenses_denied_amount

string

The total amount of expenses denied on this project.

Example:

"0.00"

data.expenses_total_amount

string

The total amount of all expenses recorded on this project.

Example:

"0.00"

data.financials_pending_amount

string

The total pending financial amount on this project.

Example:

"0.00"

data.financials_approved_amount

string

The total approved financial amount on this project.

Example:

"9250.00"

data.financials_billable_amount

string

The total billable amount on this project.

Example:

"9250.00"

data.financials_sold_amount

string

The total sold amount on this project.

Example:

"18500.00"

data.financials_total_amount

string

The total financial amount recorded on this project.

Example:

"18500.00"

data.financials_down_payment_amount

string

The total down payment amount recorded on this project.

Example:

"5000.00"

data.financials_progress_payment_amount

string

The total progress payment amount recorded on this project.

Example:

"4250.00"

data.financials_final_paid_amount

string

The total final payment amount recorded on this project.

Example:

"0.00"

data.financials_deductible_paid_amount

string

The total deductible payment amount recorded on this project.

Example:

"0.00"

data.financials_all_paid_amount

string

The total amount paid across all payment types on this project.

Example:

"9250.00"

data.financials_total_paid_amount

string

The total amount paid on this project.

Example:

"9250.00"

data.financials_credit_memo_amount

string

The total credit memo amount applied to this project.

Example:

"0.00"

data.financials_refund_amount

string

The total amount refunded on this project.

Example:

"0.00"

data.financials_revenue_amount

string

The total revenue recognized on this project.

Example:

"9250.00"

data.financials_revenue_approved_amount

string

The total approved revenue recognized on this project.

Example:

"9250.00"

data.financials_received_amount

string

The total amount received on this project.

Example:

"9250.00"

data.financials_balance_amount

string

The outstanding balance remaining on this project.

Example:

"9250.00"

data.last_note_created_at

string | null

Timestamp of the most recent note added to this project, formatted as YYYY-MM-DD HH:MM:SS. Set immediately at creation by the automatic "Project was created." note.

Example:

"2025-02-14 10:05:00"

data.is_in_collections_at

string | null

Timestamp when this project was marked as in collections. Null if not in collections.

data.first_contract_at

string | null

Timestamp when the first contract was created for this project. Null if no contract exists yet.

Example:

"2025-02-11 09:30:00"

data.first_contract_approved_at

string | null

Timestamp when the first contract for this project was approved. Null if not yet approved.

Example:

"2025-02-12 16:00:00"

data.first_appointment_at

string | null

Timestamp of this project's first scheduled appointment. Null if none has been scheduled.

Example:

"2025-02-10 13:00:00"

data.appointment_recommended_at

string | null

Timestamp when an appointment was recommended for this project. Null if not applicable.

data.sale_closed_at

string | null

Timestamp when the sale was closed for this project. Null if not yet closed.

Example:

"2025-02-12 16:00:00"

data.referred_at

string | null

Timestamp when this project was referred. Null if not referred.

data.callback_at

string | null

Timestamp for this project's next callback. Defaults to the project's creation time when no value is provided.

Example:

"2025-02-10 09:15:00"

data.completed_at

string | null

Timestamp when this project was completed. Null if not yet completed.

data.created_at

string | null

Timestamp when the project was created, formatted as YYYY-MM-DD HH:MM:SS.

Example:

"2025-02-10 09:15:00"

data.updated_at

string | null

Timestamp when the project was last updated, formatted as YYYY-MM-DD HH:MM:SS.

Example:

"2025-02-14 10:05:00"

data.deleted_at

string | null

Timestamp when the project was deleted from the Contractors Cloud web app. Null unless it was deleted there — see the deleted filter on List projects. Deleting a project through this API removes it permanently instead of setting this field.

current_page

integer

The 1-indexed page number of the current response.

Example:

1

first_page_url

string

The URL of the first page of results.

from

integer | null

The 1-indexed position of the first record in data for this page. Null when the page is empty.

Example:

1

last_page

integer

The number of the final page in the result set.

Example:

4

last_page_url

string

The URL of the last page of results.

links

object[]

Rendered pagination links (previous, numbered pages, next).

Hide child attributes

links.url

string | null

The target URL for this link, or null if the link isn't clickable (for example, the current page).

links.label

string

Display label for the link, such as a page number or Next ».

links.active

boolean

Whether this link represents the current page.

next_page_url

string | null

The URL of the next page, or null if this is the last page.

path

string

The endpoint URL without query parameters.

per_page

integer

The number of records requested per page.

Example:

30

prev_page_url

string | null

The URL of the previous page, or null if this is the first page.

integer | null

The 1-indexed position of the last record in data for this page. Null when the page is empty.

Example:

30

total

integer

The total number of records across all pages.

Example:

97

Getting Started

Reference

Authorizations

Query Parameters

Response