Deliverables
Update a deliverable
Change one deliverable. Only the fields you send are touched.
This is also how you archive and restore: send { "isArchived": true } or { "isArchived": false }.
PATCH
/
deliverable
/
{id}
Update a deliverable
curl --request PATCH \
--url https://{instance}/api/v2/deliverable/{id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"identifier": "<string>",
"name": "<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>"
}
'const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
identifier: '<string>',
name: '<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>'
})
};
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 = {
"identifier": "<string>",
"name": "<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>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(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
Organization-scoped API key. Create one in the BuildingSwell app under Organization settings, API keys.
Path Parameters
Record id.
Body
application/json
Every field is optional. Only the fields you send are changed.
Human-readable id, unique within your organization. Generated for you when you leave it out.
Display name.
Archived records are hidden from list results unless you ask for them. Set this to archive or restore the record.
When the record was archived. Set automatically when isArchived flips to true, and cleared on restore.
Which concept this node represents.
Available options:
order, route, overhead, template-phase, phase, component, stage, step, qcstep, group How many of this node the work covers.
Node directly above this one.
Root of this node's tree. A root node points at itself.
Route or template this node was built from.
Cycle time per unit, in seconds.
Total duration, in seconds.
How many people the node is planned for.
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
Show child attributes
Example:
{
"stageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
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.
Response
The updated deliverable.
One generic work-tree node. Its type decides which domain concept it represents, from an order down to a single step.
Show child attributes
Show child attributes
⌘I
Update a deliverable
curl --request PATCH \
--url https://{instance}/api/v2/deliverable/{id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"identifier": "<string>",
"name": "<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>"
}
'const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
identifier: '<string>',
name: '<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>'
})
};
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 = {
"identifier": "<string>",
"name": "<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>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(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": {}
}