Creating a project

Creating a project means resolving a handful of ids from other endpoints first — a company, an account, at least one contact, a site type, a lead source, and an event — then sending them together in a single POST request. This recipe walks through gathering those ids and making that request.

Gather the required ids

Every id below must belong to your organization (and, where noted, to the specific company you’re creating the project under):

Field	Discover with
`company_id`	List companies — only companies you belong to are returned.
`account_id`	List accounts.
`contact_ids`	List contacts — at least one, distinct, existing contact id.
`event_id`	List events for the company, filtered to `filter[is_active]=1`.
`lead_id`	List lead sources for the company, filtered to `filter[is_active]=1`.
`site_type_id`	There’s currently no endpoint to list site types. Read one off an existing project with `include=site_type`, or ask your administrator.

Create the project

With those ids in hand, create the project along with its street address:

curl -X POST "https://api.contractorscloud.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "company_id": 101,
        "account_id": 5001,
        "contact_ids": [7001],
        "site_type_id": 3,
        "lead_id": 42,
        "event_id": 9,
        "address_street": "123 Main St",
        "address_city": "Minneapolis",
        "address_state": "MN",
        "address_zip": "55401"
      }'

The response is 201 Created with the full project:

{
  "id": 9301,
  "company_id": 101,
  "account_id": 5001,
  "status_id": 1,
  "site_type_id": 3,
  "lead_id": 42,
  "event_id": 9,
  "number": "Lead",
  "name": null,
  "address_street": "123 Main St",
  "address_city": "Minneapolis",
  "address_state": "MN",
  "address_zip": "55401",
  "rep_primary_name": "TBD",
  "created_at": "2025-03-03 14:22:10"
}

Conditional requirements

Two fields are required only in certain configurations, and one field is company-specific to look up:

workflow_id is required when the company you’re creating the project under has workflows enabled as mandatory. The company resource doesn’t expose this setting, so the practical check is attempting the create without it — a 422 naming workflow_id means it’s required. When required, it must be an active workflow belonging to that company (see List workflows).
name is required when the company requires project names. Otherwise it’s optional and can be left out or set to null.
company_custom_fields is required only when the company defines active required custom fields. Discover the field definitions with List company custom fields; every active, required field’s id must be present, and each value’s type must match its field’s type (a YYYY-MM-DD date for date fields, one of the field’s options for select fields, a number for number fields, true/false for checkbox fields, or a string for input/textarea fields).

After creation

A brand-new project’s number is a placeholder, literally the string "Lead" — set a real value with Update project, the only endpoint that can change it:

curl -X PUT "https://api.contractorscloud.com/api/v1/projects/9301" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"number": "2025-0201"}'

To react to new projects without polling, subscribe a webhook to projects.created — see Webhooks. And if most of your projects originate from an external source (a web form, a lead vendor, a spreadsheet), consider Leads instead of calling this endpoint directly — a lead connection validates and converts inbound submissions into projects automatically.

See the Projects reference for every field, filter, include, and sort this resource supports.

Concepts

Domains

Examples

Gather the required ids

Create the project

Conditional requirements

After creation

​Gather the required ids

​Create the project

​Conditional requirements

​After creation

Gather the required ids

Create the project

Conditional requirements

After creation