Upsert a deliverable

PUT

deliverable

{id}

curl --request PUT \
  --url https://{instance}/api/v2/deliverable/{id} \
  --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",
  "quantity": 1,
  "parentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rootParentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "originTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cycleTimeSec": 0,
  "durationSec": 0,
  "peopleNum": 1,
  "data": {
    "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "costCode": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}
'

const options = {
  method: 'PUT',
  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',
    quantity: 1,
    parentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    rootParentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    originTemplateId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    cycleTimeSec: 0,
    durationSec: 0,
    peopleNum: 1,
    data: {stageId: '3fa85f64-5717-4562-b3fc-2c963f66afa6'},
    costCode: '<string>',
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z'
  })
};

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

import requests

url = "https://{instance}/api/v2/deliverable/{id}"

payload = {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "identifier": "<string>",
    "isArchived": False,
    "archivedAt": "2023-11-07T05:31:56Z",
    "quantity": 1,
    "parentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rootParentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "originTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "cycleTimeSec": 0,
    "durationSec": 0,
    "peopleNum": 1,
    "data": { "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
    "costCode": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(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",
    "archivedById": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "order",
    "quantity": 1,
    "parentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rootParentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "originTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "cycleTimeSec": 0,
    "durationSec": 0,
    "peopleNum": 1,
    "data": {
      "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "costCode": "<string>",
    "schedule": {
      "startDate": "2023-11-07T05:31:56Z",
      "endDate": "2023-11-07T05:31:56Z"
    },
    "progress": {
      "status": "waiting",
      "completed": 0,
      "wip": 0,
      "percentage": 0,
      "startedAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "hasBeenReworked": false,
      "updatedById": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "computed": {
      "rootType": "order",
      "fullName": [
        "<string>"
      ],
      "fullPath": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "phasesPath": [
        "<string>"
      ],
      "phase": "<string>",
      "currentChildren": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "stageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "order"
        }
      ],
      "containedStageIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "containedPhaseNames": [
        "<string>"
      ],
      "containedCurrentStageIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "containedCurrentPhaseNames": [
        "<string>"
      ],
      "currentStageIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "currentPhaseNames": [
        "<string>"
      ],
      "combinedWorkerIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "combinedTagIds": [
        "<string>"
      ],
      "workerIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "tags": [
        "<string>"
      ],
      "isLeaf": true,
      "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "date": "<string>",
      "isAtRisk": false,
      "isLate": false,
      "effectiveDueDate": "<string>",
      "effectiveDueDateIsInherited": false,
      "effectiveDueDateIsLate": false,
      "hasReworkedStages": false,
      "groupIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "alertType": "on-hold",
    "alertTypeOrdinal": 123,
    "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": {}
}

{
  "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.

Path Parameters

string<uuid>

required

Record id.

Query Parameters

update

string[]

required

Columns to overwrite when the row already exists. Repeat the parameter for each column: a single comma-separated value is read as one column name and fails at the database. Without the parameter the request is rejected with 400.

Body

application/json

These raw endpoints do not enforce the nesting rules. A step under an order, or a stage node with no station, is accepted here and leaves the tree in a state the app cannot show. Use the domain concepts endpoints for validated writes.

name

string

required

Display name.

type

enum<string>

required

Which concept this node represents.

Available options:

order,

route,

overhead,

template-phase,

phase,

component,

stage,

step,

qcstep,

group

string<uuid>

Unique id. Generated on create unless you supply one.

identifier

string

Human-readable id, unique within your organization. Generated for you 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.

quantity

integer

default:1

How many of this node the work covers.

parentId

string<uuid> | null

Node directly above this one.

rootParentId

string<uuid> | null

Root of this node's tree. A root node points at itself.

originTemplateId

string<uuid> | null

Route or template this node was built from.

cycleTimeSec

integer

default:0

Cycle time per unit, in seconds.

durationSec

integer

default:0

Total duration, in seconds.

peopleNum

integer

default:1

How many people the node is planned for.

data

object

Per-concept fields. Which keys apply depends on type: a stage node needs stageId, an order needs projectId, and so on. See the domain concepts guide for the full table.

Show child attributes

Example:

{
  "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

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.

Response

The upserted deliverable.

value

object

required

One generic work-tree node. Its type decides which domain concept it represents, from an order down to a single step.

Show child attributes

Upsert a deliverable

curl --request PUT \
  --url https://{instance}/api/v2/deliverable/{id} \
  --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",
  "quantity": 1,
  "parentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rootParentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "originTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cycleTimeSec": 0,
  "durationSec": 0,
  "peopleNum": 1,
  "data": {
    "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "costCode": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}
'

const options = {
  method: 'PUT',
  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',
    quantity: 1,
    parentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    rootParentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    originTemplateId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    cycleTimeSec: 0,
    durationSec: 0,
    peopleNum: 1,
    data: {stageId: '3fa85f64-5717-4562-b3fc-2c963f66afa6'},
    costCode: '<string>',
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z'
  })
};

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

import requests

url = "https://{instance}/api/v2/deliverable/{id}"

payload = {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "identifier": "<string>",
    "isArchived": False,
    "archivedAt": "2023-11-07T05:31:56Z",
    "quantity": 1,
    "parentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rootParentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "originTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "cycleTimeSec": 0,
    "durationSec": 0,
    "peopleNum": 1,
    "data": { "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
    "costCode": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(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",
    "archivedById": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "order",
    "quantity": 1,
    "parentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rootParentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "originTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "cycleTimeSec": 0,
    "durationSec": 0,
    "peopleNum": 1,
    "data": {
      "stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "costCode": "<string>",
    "schedule": {
      "startDate": "2023-11-07T05:31:56Z",
      "endDate": "2023-11-07T05:31:56Z"
    },
    "progress": {
      "status": "waiting",
      "completed": 0,
      "wip": 0,
      "percentage": 0,
      "startedAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "hasBeenReworked": false,
      "updatedById": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "computed": {
      "rootType": "order",
      "fullName": [
        "<string>"
      ],
      "fullPath": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "phasesPath": [
        "<string>"
      ],
      "phase": "<string>",
      "currentChildren": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "stageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "order"
        }
      ],
      "containedStageIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "containedPhaseNames": [
        "<string>"
      ],
      "containedCurrentStageIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "containedCurrentPhaseNames": [
        "<string>"
      ],
      "currentStageIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "currentPhaseNames": [
        "<string>"
      ],
      "combinedWorkerIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "combinedTagIds": [
        "<string>"
      ],
      "workerIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "tags": [
        "<string>"
      ],
      "isLeaf": true,
      "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "date": "<string>",
      "isAtRisk": false,
      "isLate": false,
      "effectiveDueDate": "<string>",
      "effectiveDueDateIsInherited": false,
      "effectiveDueDateIsLate": false,
      "hasReworkedStages": false,
      "groupIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "alertType": "on-hold",
    "alertTypeOrdinal": 123,
    "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": {}
}

{
  "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

Path Parameters

Query Parameters

Body

Response