Upsert a person

PUT

worker

{id}

Upsert a person

curl --request PUT \
  --url https://{instance}/api/v2/worker/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customerIdentifier": "",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "active",
  "isArchived": false,
  "exemptFromAssignments": false,
  "unionCode": "<string>",
  "qbBadgeLink": "<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',
    customerIdentifier: '',
    teamId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    status: 'active',
    isArchived: false,
    exemptFromAssignments: false,
    unionCode: '<string>',
    qbBadgeLink: '<string>',
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z'
  })
};

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

import requests

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

payload = {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customerIdentifier": "",
    "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active",
    "isArchived": False,
    "exemptFromAssignments": False,
    "unionCode": "<string>",
    "qbBadgeLink": "<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",
    "name": "<string>",
    "customerIdentifier": "",
    "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active",
    "isArchived": false,
    "exemptFromAssignments": false,
    "unionCode": "<string>",
    "qbBadgeLink": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "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

Only name is required. Every other field falls back to its default.

name

string

required

Display name.

string<uuid>

Unique id. This is the value workerId refers to elsewhere.

customerIdentifier

string

default:""

Your own identifier for this person, for example an employee number. Defaults to an empty string.

teamId

string<uuid> | null

Team the person belongs to.

status

enum<string>

default:active

Employment status.

Available options:

active,

inactive,

terminated

isArchived

boolean

default:false

Archived people are hidden from list results unless you ask for them. They are never deleted, so historical ids still resolve. Set this to archive or restore the person.

exemptFromAssignments

boolean

default:false

true to leave the person out of assignment planning.

unionCode

string | null

Labor or union classification code.

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

qbBadgeLink

string | null

QuickBase badge link, used by that integration.

createdAt

string<date-time>

When the record was created.

updatedAt

string<date-time>

When the record last changed.

Response

The upserted person.

value

object

required

Your workforce roster. Use it to resolve the workerId values that appear on timesheets, assignments, and QC entries.

Show child attributes

Upsert a person

curl --request PUT \
  --url https://{instance}/api/v2/worker/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customerIdentifier": "",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "active",
  "isArchived": false,
  "exemptFromAssignments": false,
  "unionCode": "<string>",
  "qbBadgeLink": "<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',
    customerIdentifier: '',
    teamId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    status: 'active',
    isArchived: false,
    exemptFromAssignments: false,
    unionCode: '<string>',
    qbBadgeLink: '<string>',
    createdAt: '2023-11-07T05:31:56Z',
    updatedAt: '2023-11-07T05:31:56Z'
  })
};

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

import requests

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

payload = {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customerIdentifier": "",
    "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active",
    "isArchived": False,
    "exemptFromAssignments": False,
    "unionCode": "<string>",
    "qbBadgeLink": "<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",
    "name": "<string>",
    "customerIdentifier": "",
    "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active",
    "isArchived": false,
    "exemptFromAssignments": false,
    "unionCode": "<string>",
    "qbBadgeLink": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "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