Upsert a work session

PUT

deliverable

work-sessions

{id}

curl --request PUT \
  --url https://{instance}/api/v2/deliverable/work-sessions/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "deliverableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startDate": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "endDate": "2023-11-07T05:31:56Z",
  "isEdited": false,
  "lastUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shiftWorkHours": {
    "startTime": "08:00",
    "endTime": "17:00",
    "breaks": [
      {
        "startTime": "12:00",
        "durationInSec": 1800
      }
    ],
    "timezone": "America/New_York"
  },
  "externalSource": "<string>",
  "externalSync": "synced",
  "metadata": {
    "costCode": "WELD-100",
    "unionCode": "LOCAL-7"
  },
  "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({
    deliverableId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    workerId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    shopId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    startDate: '2023-11-07T05:31:56Z',
    id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    endDate: '2023-11-07T05:31:56Z',
    isEdited: false,
    lastUpdatedBy: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    shiftWorkHours: {
      startTime: '08:00',
      endTime: '17:00',
      breaks: [{startTime: '12:00', durationInSec: 1800}],
      timezone: 'America/New_York'
    },
    externalSource: '<string>',
    externalSync: 'synced',
    metadata: {costCode: 'WELD-100', unionCode: 'LOCAL-7'},
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z'
  })
};

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

import requests

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

payload = {
    "deliverableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-11-07T05:31:56Z",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "endDate": "2023-11-07T05:31:56Z",
    "isEdited": False,
    "lastUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shiftWorkHours": {
        "startTime": "08:00",
        "endTime": "17:00",
        "breaks": [
            {
                "startTime": "12:00",
                "durationInSec": 1800
            }
        ],
        "timezone": "America/New_York"
    },
    "externalSource": "<string>",
    "externalSync": "synced",
    "metadata": {
        "costCode": "WELD-100",
        "unionCode": "LOCAL-7"
    },
    "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",
    "deliverableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-11-07T05:31:56Z",
    "endDate": "2023-11-07T05:31:56Z",
    "isEdited": false,
    "lastUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shiftWorkHours": {
      "startTime": "08:00",
      "endTime": "17:00",
      "breaks": [
        {
          "startTime": "12:00",
          "durationInSec": 1800
        }
      ],
      "timezone": "America/New_York"
    },
    "breakTimeInSec": 123,
    "externalSource": "<string>",
    "externalSync": "synced",
    "metadata": {
      "costCode": "WELD-100",
      "unionCode": "LOCAL-7"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "rawStart": "2023-11-07T05:31:56Z",
    "rawEnd": "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

Leave shiftWorkHours out and BuildingSwell fills it from the person's shop shift for startDate, stamping the shop timezone onto it. Leave metadata.costCode out and it is resolved from the deliverable, then its station, then its ancestors, then the project, then the route; if none of those carry one, the key is left off entirely.

One person can hold only one open session per deliverable. A second attempt comes back as 409.

deliverableId

string<uuid>

required

Deliverable the time was logged against.

workerId

string<uuid>

required

Person who did the work.

shopId

string<uuid>

required

Department the session belongs to.

startDate

string<date-time>

required

When the session started, in UTC.

string<uuid>

Unique id. Generated on create unless you supply one.

endDate

string<date-time> | null

When the session ended, in UTC. null means it is still open.

isEdited

boolean

default:false

true when someone has edited the session by hand.

lastUpdatedBy

string<uuid> | null

Who last changed the session.

shiftWorkHours

object | null

The shift the record was worked against. Break times are local wall-clock, not UTC.

Show child attributes

externalSource

string | null

System the session came from, for example quickbase.

externalSync

string

default:not synced

Sync state for the external system.

Example:

"synced"

metadata

object

Free-form key-value store. No key is guaranteed to be present, and a missing key is not the same as a null one. See the resource guide for which paths populate costCode and unionCode.

Example:

{
  "costCode": "WELD-100",
  "unionCode": "LOCAL-7"
}

createdAt

string<date-time>

When the record was created.

updatedAt

string<date-time>

When the record last changed.

Response

The upserted work session.

value

object

required

Time one person logged against one deliverable. An open session has no endDate.

Show child attributes

Upsert a work session

curl --request PUT \
  --url https://{instance}/api/v2/deliverable/work-sessions/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "deliverableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startDate": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "endDate": "2023-11-07T05:31:56Z",
  "isEdited": false,
  "lastUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shiftWorkHours": {
    "startTime": "08:00",
    "endTime": "17:00",
    "breaks": [
      {
        "startTime": "12:00",
        "durationInSec": 1800
      }
    ],
    "timezone": "America/New_York"
  },
  "externalSource": "<string>",
  "externalSync": "synced",
  "metadata": {
    "costCode": "WELD-100",
    "unionCode": "LOCAL-7"
  },
  "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({
    deliverableId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    workerId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    shopId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    startDate: '2023-11-07T05:31:56Z',
    id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    endDate: '2023-11-07T05:31:56Z',
    isEdited: false,
    lastUpdatedBy: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    shiftWorkHours: {
      startTime: '08:00',
      endTime: '17:00',
      breaks: [{startTime: '12:00', durationInSec: 1800}],
      timezone: 'America/New_York'
    },
    externalSource: '<string>',
    externalSync: 'synced',
    metadata: {costCode: 'WELD-100', unionCode: 'LOCAL-7'},
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z'
  })
};

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

import requests

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

payload = {
    "deliverableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-11-07T05:31:56Z",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "endDate": "2023-11-07T05:31:56Z",
    "isEdited": False,
    "lastUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shiftWorkHours": {
        "startTime": "08:00",
        "endTime": "17:00",
        "breaks": [
            {
                "startTime": "12:00",
                "durationInSec": 1800
            }
        ],
        "timezone": "America/New_York"
    },
    "externalSource": "<string>",
    "externalSync": "synced",
    "metadata": {
        "costCode": "WELD-100",
        "unionCode": "LOCAL-7"
    },
    "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",
    "deliverableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shopId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-11-07T05:31:56Z",
    "endDate": "2023-11-07T05:31:56Z",
    "isEdited": false,
    "lastUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "shiftWorkHours": {
      "startTime": "08:00",
      "endTime": "17:00",
      "breaks": [
        {
          "startTime": "12:00",
          "durationInSec": 1800
        }
      ],
      "timezone": "America/New_York"
    },
    "breakTimeInSec": 123,
    "externalSource": "<string>",
    "externalSync": "synced",
    "metadata": {
      "costCode": "WELD-100",
      "unionCode": "LOCAL-7"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "rawStart": "2023-11-07T05:31:56Z",
    "rawEnd": "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