Update project

Update project

curl --request PUT \
  --url https://api.contractorscloud.com/api/v1/projects/{projectId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "2025-0201",
  "status_id": 2
}
'

import requests

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

payload = {
    "number": "2025-0201",
    "status_id": 2
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({number: '2025-0201', status_id: 2})
};

fetch('https://api.contractorscloud.com/api/v1/projects/{projectId}', 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/{projectId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'number' => '2025-0201',
    'status_id' => 2
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"number\": \"2025-0201\",\n  \"status_id\": 2\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.contractorscloud.com/api/v1/projects/{projectId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"number\": \"2025-0201\",\n  \"status_id\": 2\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"number\": \"2025-0201\",\n  \"status_id\": 2\n}"

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

{
  "id": 9301,
  "tenant_id": 12,
  "company_id": 101,
  "account_id": 5001,
  "status_id": 2,
  "event_id": 9,
  "lead_id": 42,
  "storm_id": null,
  "group_id": null,
  "workflow_id": null,
  "site_type_id": 3,
  "cancellation_id": null,
  "rep_primary_id": null,
  "mortgage_company_id": null,
  "original_milestone_id": null,
  "current_project_milestone_id": null,
  "referred_by": null,
  "companycam_id": null,
  "hash": "9d2b6f4a1c8e3d7b5a9c2f6e4d1b8a3c",
  "number": "2025-0201",
  "name": null,
  "account_name": "Robert Chen",
  "address_street": "123 Main St",
  "address_city": "Minneapolis",
  "address_state": "MN",
  "address_zip": "55401",
  "address_description": null,
  "address_latitude": "44.977800",
  "address_longitude": "-93.265000",
  "needs_appointment": false,
  "is_in_collections": false,
  "rep_primary_name": "TBD",
  "percent_completed": "0.00",
  "percent_sale_close": "0.00",
  "amount_estimated": "0.00",
  "mortgage_loan_number": null,
  "estimated_total_amount": "0.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": "0.00",
  "financials_billable_amount": "0.00",
  "financials_sold_amount": "0.00",
  "financials_total_amount": "0.00",
  "financials_down_payment_amount": "0.00",
  "financials_progress_payment_amount": "0.00",
  "financials_final_paid_amount": "0.00",
  "financials_deductible_paid_amount": "0.00",
  "financials_all_paid_amount": "0.00",
  "financials_total_paid_amount": "0.00",
  "financials_credit_memo_amount": "0.00",
  "financials_refund_amount": "0.00",
  "financials_revenue_amount": "0.00",
  "financials_revenue_approved_amount": "0.00",
  "financials_received_amount": "0.00",
  "financials_balance_amount": "0.00",
  "last_note_created_at": "2025-03-03 14:22:10",
  "is_in_collections_at": null,
  "first_contract_at": null,
  "first_contract_approved_at": null,
  "first_appointment_at": null,
  "appointment_recommended_at": null,
  "sale_closed_at": null,
  "referred_at": null,
  "callback_at": "2025-03-03 14:22:10",
  "completed_at": null,
  "created_at": "2025-03-03 14:22:10",
  "updated_at": "2025-03-04 08:10:45",
  "deleted_at": null
}

{
  "message": "Unauthenticated."
}

{
  "message": "The requested resource could not be found."
}

{
  "message": "The first name field is required.",
  "errors": {
    "first_name": [
      "The first name field is required."
    ]
  }
}

PUT

projects

{projectId}

Update project

curl --request PUT \
  --url https://api.contractorscloud.com/api/v1/projects/{projectId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "2025-0201",
  "status_id": 2
}
'

import requests

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

payload = {
    "number": "2025-0201",
    "status_id": 2
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({number: '2025-0201', status_id: 2})
};

fetch('https://api.contractorscloud.com/api/v1/projects/{projectId}', 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/{projectId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'number' => '2025-0201',
    'status_id' => 2
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"number\": \"2025-0201\",\n  \"status_id\": 2\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.contractorscloud.com/api/v1/projects/{projectId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"number\": \"2025-0201\",\n  \"status_id\": 2\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"number\": \"2025-0201\",\n  \"status_id\": 2\n}"

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

{
  "id": 9301,
  "tenant_id": 12,
  "company_id": 101,
  "account_id": 5001,
  "status_id": 2,
  "event_id": 9,
  "lead_id": 42,
  "storm_id": null,
  "group_id": null,
  "workflow_id": null,
  "site_type_id": 3,
  "cancellation_id": null,
  "rep_primary_id": null,
  "mortgage_company_id": null,
  "original_milestone_id": null,
  "current_project_milestone_id": null,
  "referred_by": null,
  "companycam_id": null,
  "hash": "9d2b6f4a1c8e3d7b5a9c2f6e4d1b8a3c",
  "number": "2025-0201",
  "name": null,
  "account_name": "Robert Chen",
  "address_street": "123 Main St",
  "address_city": "Minneapolis",
  "address_state": "MN",
  "address_zip": "55401",
  "address_description": null,
  "address_latitude": "44.977800",
  "address_longitude": "-93.265000",
  "needs_appointment": false,
  "is_in_collections": false,
  "rep_primary_name": "TBD",
  "percent_completed": "0.00",
  "percent_sale_close": "0.00",
  "amount_estimated": "0.00",
  "mortgage_loan_number": null,
  "estimated_total_amount": "0.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": "0.00",
  "financials_billable_amount": "0.00",
  "financials_sold_amount": "0.00",
  "financials_total_amount": "0.00",
  "financials_down_payment_amount": "0.00",
  "financials_progress_payment_amount": "0.00",
  "financials_final_paid_amount": "0.00",
  "financials_deductible_paid_amount": "0.00",
  "financials_all_paid_amount": "0.00",
  "financials_total_paid_amount": "0.00",
  "financials_credit_memo_amount": "0.00",
  "financials_refund_amount": "0.00",
  "financials_revenue_amount": "0.00",
  "financials_revenue_approved_amount": "0.00",
  "financials_received_amount": "0.00",
  "financials_balance_amount": "0.00",
  "last_note_created_at": "2025-03-03 14:22:10",
  "is_in_collections_at": null,
  "first_contract_at": null,
  "first_contract_approved_at": null,
  "first_appointment_at": null,
  "appointment_recommended_at": null,
  "sale_closed_at": null,
  "referred_at": null,
  "callback_at": "2025-03-03 14:22:10",
  "completed_at": null,
  "created_at": "2025-03-03 14:22:10",
  "updated_at": "2025-03-04 08:10:45",
  "deleted_at": null
}

{
  "message": "Unauthenticated."
}

{
  "message": "The requested resource could not be found."
}

{
  "message": "The first name field is required.",
  "errors": {
    "first_name": [
      "The first name field is required."
    ]
  }
}

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.

Path Parameters

projectId

integer

required

The id of the project.

Body

application/json

account_id

integer

The id of the account this project belongs to. Optional; cannot be set to null when provided.

Example:

5190

status_id

integer

The id of the project's status, from the project-status reference data (see List available options). Optional; cannot be set to null when provided.

site_type_id

integer

The id of the project's site type. Optional; cannot be set to null when provided.

Example:

4

lead_id

integer

The id of the lead source this project originated from. Optional; cannot be set to null when provided. Must be an active lead source belonging to the project's own company.

Example:

372

referred_by

integer | null

The id of the contact who referred this project. Optional.

event_id

integer

The id of the event this project originated from. Optional; cannot be set to null when provided. Must be an active event belonging to the project's own company.

Example:

214

workflow_id

integer | null

The id of the workflow this project follows. Must be an active workflow belonging to the project's own company. Required (and cannot be null) only when that company requires a workflow on its projects; optional and nullable otherwise.

Example:

58

rep_primary_id

integer | null

The id of the user assigned as this project's primary rep. Must be a user belonging to the project's own company. Optional.

name

string | null

The project's name. Required (and cannot be blank) only for companies that require project names.

Maximum string length: 150

number

string

The project's user-facing number. This is the only place number can be set — use it to replace the Lead placeholder assigned when the project was created. Cannot be set to an empty value.

Maximum string length: 15

Example:

"2025-0201"

address_street

string

The street portion of the project's address. Optional; cannot be blank when provided.

Maximum string length: 50

address_city

string

The city portion of the project's address. Optional; cannot be blank when provided.

Maximum string length: 50

address_state

string

The two-letter state or province code for the project's address. Optional; cannot be blank when provided.

Required string length: 2

address_zip

string

The postal code for the project's address. Optional; cannot be blank when provided.

Maximum string length: 50

address_description

string | null

A free-form description of the project's site or address, such as access instructions. Optional.

address_latitude

string | null

The latitude of the project's address. Optional.

address_longitude

string | null

The longitude of the project's address. Optional.

needs_appointment

boolean

Whether this project needs an appointment scheduled. Optional.

referred_at

string<date> | null

The date this project was referred, formatted as YYYY-MM-DD. Optional.

amount_estimated

number | null

The estimated dollar amount for this project. Optional; resets to 0 when explicitly set to null.

sale_closed_at

string<date> | null

The date the sale was closed, formatted as YYYY-MM-DD. Optional.

percent_sale_close

number | null

The estimated probability of this project's sale closing, as a percentage. Optional; resets to 0 when explicitly set to null.

companycam_id

number | null

An identifier linking this project to a record in a connected third-party service. Optional.

Response

The updated project.

A project — the central job record in Contractors Cloud. The financial fields from payouts_amount through financials_balance_amount below are omitted from the response entirely when the calling user's account has the "Hide all project financial data" or the contract-access restriction permission enabled. amount_estimated, estimated_total_amount, percent_completed, and percent_sale_close are always present regardless of that permission.

integer

The project's unique identifier.

Example:

9103

tenant_id

integer | null

The id of your organization's account.

Example:

12

company_id

integer

The id of the company this project belongs to.

Example:

6

account_id

integer

The id of the account this project belongs to.

Example:

5190

status_id

integer

The id of the project's current status.

Example:

3

event_id

integer | null

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

Example:

214

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

storm_id

integer | null

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

group_id

integer | null

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

workflow_id

integer | null

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

Example:

58

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

cancellation_id

integer | null

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

rep_primary_id

integer | null

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

Example:

1159

mortgage_company_id

integer | null

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

original_milestone_id

integer | null

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

current_project_milestone_id

integer | null

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

referred_by

integer | null

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

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.

hash

string | null

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

Example:

"f3a1c9e7b2d84f6a9c1e3b7d5a2f9c4e"

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"

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"

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"

address_street

string | null

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

Example:

"482 Birchwood Ave"

address_city

string | null

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

Example:

"Madison"

address_state

string | null

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

Example:

"WI"

address_zip

string | null

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

Example:

"53703"

address_description

string | null

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

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"

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"

needs_appointment

boolean

Whether this project needs an appointment scheduled.

Example:

true

is_in_collections

boolean

Whether this project is currently marked as in collections.

Example:

false

rep_primary_name

string

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

Example:

"Jane Doe"

percent_completed

string

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

Example:

"45.00"

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"

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"

mortgage_loan_number

string | null

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

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"

payouts_amount

string

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

Example:

"0.00"

overhead_amount

string

The total overhead amount allocated to this project.

Example:

"0.00"

expenses_pending_amount

string

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

Example:

"0.00"

expenses_approved_amount

string

The total amount of approved expenses on this project.

Example:

"0.00"

expenses_paid_amount

string

The total amount of expenses paid on this project.

Example:

"0.00"

expenses_denied_amount

string

The total amount of expenses denied on this project.

Example:

"0.00"

expenses_total_amount

string

The total amount of all expenses recorded on this project.

Example:

"0.00"

financials_pending_amount

string

The total pending financial amount on this project.

Example:

"0.00"

financials_approved_amount

string

The total approved financial amount on this project.

Example:

"9250.00"

financials_billable_amount

string

The total billable amount on this project.

Example:

"9250.00"

financials_sold_amount

string

The total sold amount on this project.

Example:

"18500.00"

financials_total_amount

string

The total financial amount recorded on this project.

Example:

"18500.00"

financials_down_payment_amount

string

The total down payment amount recorded on this project.

Example:

"5000.00"

financials_progress_payment_amount

string

The total progress payment amount recorded on this project.

Example:

"4250.00"

financials_final_paid_amount

string

The total final payment amount recorded on this project.

Example:

"0.00"

financials_deductible_paid_amount

string

The total deductible payment amount recorded on this project.

Example:

"0.00"

financials_all_paid_amount

string

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

Example:

"9250.00"

financials_total_paid_amount

string

The total amount paid on this project.

Example:

"9250.00"

financials_credit_memo_amount

string

The total credit memo amount applied to this project.

Example:

"0.00"

financials_refund_amount

string

The total amount refunded on this project.

Example:

"0.00"

financials_revenue_amount

string

The total revenue recognized on this project.

Example:

"9250.00"

financials_revenue_approved_amount

string

The total approved revenue recognized on this project.

Example:

"9250.00"

financials_received_amount

string

The total amount received on this project.

Example:

"9250.00"

financials_balance_amount

string

The outstanding balance remaining on this project.

Example:

"9250.00"

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"

is_in_collections_at

string | null

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

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"

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"

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"

appointment_recommended_at

string | null

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

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"

referred_at

string | null

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

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"

completed_at

string | null

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

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"

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"

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.

Getting Started

Reference

Authorizations

Path Parameters

Body

Response