Create a project

POST

project

Create a project

curl --request POST \
  --url https://{instance}/api/v2/project \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "identifier": "<string>",
  "isArchived": false,
  "archivedAt": "2023-11-07T05:31:56Z",
  "scheduledStartDate": "2023-12-25",
  "scheduledEndDate": "2023-12-25",
  "actualEndDate": "2023-12-25",
  "costCode": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "jobsiteAddress": {
    "addressLine1": "<string>",
    "addressLine2": "<string>",
    "city": "<string>",
    "stateOrProvince": "<string>",
    "postalCode": "<string>"
  }
}
'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    identifier: '<string>',
    isArchived: false,
    archivedAt: '2023-11-07T05:31:56Z',
    scheduledStartDate: '2023-12-25',
    scheduledEndDate: '2023-12-25',
    actualEndDate: '2023-12-25',
    costCode: '<string>',
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z',
    jobsiteAddress: {
      addressLine1: '<string>',
      addressLine2: '<string>',
      city: '<string>',
      stateOrProvince: '<string>',
      postalCode: '<string>'
    }
  })
};

fetch('https://{instance}/api/v2/project', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{instance}/api/v2/project"

payload = {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "identifier": "<string>",
    "isArchived": False,
    "archivedAt": "2023-11-07T05:31:56Z",
    "scheduledStartDate": "2023-12-25",
    "scheduledEndDate": "2023-12-25",
    "actualEndDate": "2023-12-25",
    "costCode": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "jobsiteAddress": {
        "addressLine1": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "stateOrProvince": "<string>",
        "postalCode": "<string>"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "value": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "identifier": "<string>",
    "name": "<string>",
    "isArchived": false,
    "archivedAt": "2023-11-07T05:31:56Z",
    "scheduledStartDate": "2023-12-25",
    "scheduledEndDate": "2023-12-25",
    "actualEndDate": "2023-12-25",
    "costCode": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

Authorizations

X-API-Key

string

header

required

Organization-scoped API key. Create one in the BuildingSwell app under Organization settings, API keys.

Body

application/json

object
object[]

Only name is required. Creating a project also creates one project-owned Jobsite location in the same transaction, so a project always has somewhere to ship to.

name

string

required

Display name.

string<uuid>

Unique id. Generated on create unless you supply one.

identifier

string

Human-readable id, unique within your organization. Generated in the form PROJ-a1b2c when you leave it out.

isArchived

boolean

default:false

Archived records are hidden from list results unless you ask for them. Set this to archive or restore the record.

archivedAt

string<date-time> | null

When the record was archived. Set automatically when isArchived flips to true, and cleared on restore.

scheduledStartDate

string<date> | null

Planned start of the project.

scheduledEndDate

string<date> | null

Planned finish of the project.

actualEndDate

string<date> | null

Date the project actually finished.

costCode

string | null

Cost code. Trimmed on write, and an empty string is rejected: send a non-empty string or null.

Stored as a plain string. It is not validated against the cost code list, and renaming an entry in that list does not change this value.

createdAt

string<date-time>

When the record was created.

updatedAt

string<date-time>

When the record last changed.

jobsiteAddress

object

Address for the Jobsite that BuildingSwell creates alongside the project. Every field is optional, so a partial address is fine. Send the object with all fields blank, or leave it out, and the Jobsite is created without an address.

Accepted on POST /project only. PATCH, PUT, and the bulk routes ignore it, and it is never returned in a project response: read it back from the project's Jobsite.

Show child attributes

Response

The created project. An array request returns values instead of value.

Option 1
Option 2

value

object

required

Projects group the orders and other work you deliver for one customer job.

Show child attributes

Create a project

curl --request POST \
  --url https://{instance}/api/v2/project \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "identifier": "<string>",
  "isArchived": false,
  "archivedAt": "2023-11-07T05:31:56Z",
  "scheduledStartDate": "2023-12-25",
  "scheduledEndDate": "2023-12-25",
  "actualEndDate": "2023-12-25",
  "costCode": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "jobsiteAddress": {
    "addressLine1": "<string>",
    "addressLine2": "<string>",
    "city": "<string>",
    "stateOrProvince": "<string>",
    "postalCode": "<string>"
  }
}
'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    identifier: '<string>',
    isArchived: false,
    archivedAt: '2023-11-07T05:31:56Z',
    scheduledStartDate: '2023-12-25',
    scheduledEndDate: '2023-12-25',
    actualEndDate: '2023-12-25',
    costCode: '<string>',
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z',
    jobsiteAddress: {
      addressLine1: '<string>',
      addressLine2: '<string>',
      city: '<string>',
      stateOrProvince: '<string>',
      postalCode: '<string>'
    }
  })
};

fetch('https://{instance}/api/v2/project', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{instance}/api/v2/project"

payload = {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "identifier": "<string>",
    "isArchived": False,
    "archivedAt": "2023-11-07T05:31:56Z",
    "scheduledStartDate": "2023-12-25",
    "scheduledEndDate": "2023-12-25",
    "actualEndDate": "2023-12-25",
    "costCode": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "jobsiteAddress": {
        "addressLine1": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "stateOrProvince": "<string>",
        "postalCode": "<string>"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "value": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "identifier": "<string>",
    "name": "<string>",
    "isArchived": false,
    "archivedAt": "2023-11-07T05:31:56Z",
    "scheduledStartDate": "2023-12-25",
    "scheduledEndDate": "2023-12-25",
    "actualEndDate": "2023-12-25",
    "costCode": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

{
  "error": {
    "message": "<string>",
    "code": "BAD_REQUEST",
    "requestId": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ],
    "missingPermissions": [
      "<string>"
    ]
  },
  "context": {}
}

Overview

Projects

Stages

Deliverables

Work sessions

Dependencies

Documents

Custom properties

QC

People (Workers)

Timesheets

Codes

Roles

Users

Domain concepts

Items

Item vendors

Inventory stock

Inventory transactions

Inventory allocations

BOM lines

Production outputs

Units of measure

Vendors

Locations

Deliveries

Delivery lines

Trucks

Contacts

Project contacts

Teams

Shifts

Departments (shops)

Authorizations

Body

Response