People (Workers)

The BuildingSwell app calls this People. The API calls it worker. This page uses the API name so it matches the requests you write.

The roster of everyone who does work. Use it to resolve the workerId values that show up on timesheets, assignments, and QC entries, and to create, edit, archive, and restore people. Search columns: name, customerIdentifier Standard CRUD applies, with one exception: people are never hard-deleted. See standard endpoints.

Permissions. read on worker covers the GET endpoints, and create/update cover the writes. Admins have full access. In the role editor, the People composite grants create and update, while Build, Planning, Attendance, Timesheets, and Teams each grant read.

Fields

Every property the API returns for a person.

Field	Type	Notes
`id`	UUID	Unique id. This is the value `workerId` refers to elsewhere. Server-managed.
`organizationId`	UUID	Your organization. Taken from the API key, never from the request body. Read-only.
`name`	string	Display name. Required on create.
`customerIdentifier`	string	Your own identifier for this person, for example an employee number. Defaults to an empty string. Defaults to `""`.
`teamId`	UUID \| null	Team the person belongs to.
`status`	enum	Employment status. One of `active` \| `inactive` \| `terminated`. Defaults to `active`.
`archivedAt`	date-time \| null	Archive time, cleared on restore. Server-managed.
`isArchived`	boolean	Archived people are hidden from list results unless you ask for them. They are never deleted, so historical ids still resolve. Defaults to `false`.
`exemptFromAssignments`	boolean	`true` to leave the person out of assignment planning. Defaults to `false`.
`unionCode`	string \| null	Labor or union classification code. Stored as a plain string and not validated against the union code list.
`qbBadgeLink`	string \| null	QuickBase badge link, used by that integration.
`createdAt`	date-time	When the record was created. Server-managed.
`updatedAt`	date-time	When the record last changed. Server-managed.

People carry no identifier. They use the free-form customerIdentifier instead, which is yours to set: an employee number, a badge id, whatever you key on in your own system.

What you can write

Everything else in the table above is set by BuildingSwell.

Field	On create	On update
`name`	Required	Yes
`customerIdentifier`	Optional	Yes
`teamId`	Optional	Yes
`status`	Optional	Yes
`isArchived`	Optional	Yes
`exemptFromAssignments`	Optional	Yes
`unionCode`	Optional	Yes
`qbBadgeLink`	Optional	Yes

Archive and restore

There is no separate archive endpoint. Flip isArchived with a PATCH, and BuildingSwell handles the rest.

# Archive
PATCH /worker/<id>
{ "isArchived": true }

# Restore
PATCH /worker/<id>
{ "isArchived": false }

When you archive:

name and customerIdentifier both get an - (archived <n>) suffix, teamId is cleared, and the person’s open work sessions and daily-plan assignments are ended.

When you restore, the suffix comes off, and a name an active person has since taken is given the next free variant, for example Jane Doe (1).

An archived person is read-only. Any PATCH other than the restore itself comes back as 400.

Archived people drop out of reads, the same as every other archivable resource. GET /worker returns active people only, so ask for archived ones explicitly:

# Active people (the default)
GET /worker

# Archived people only
GET /worker?isArchived=true

Repeat the parameter when you want both at once:

# Active and archived together
GET /worker?isArchived=true&isArchived=false

GET /worker/{id} on an archived person returns 404, and no query parameter overrides that on the by-id route. Since a workerId on an old timesheet may well belong to an archived person, resolve ids through the list endpoint: GET /worker?id=<uuid>&isArchived=true&isArchived=false.

Deleting

People are never deleted. Both DELETE /worker/{id} and DELETE /worker/bulk return 403, so a historical workerId on a timesheet or QC entry never dangles. It still has to be read the way the warning above describes once the person is archived.Archive instead: PATCH /worker/{id} with { "isArchived": true }.

See archiving and deleting for how this compares with the rest of the API.

Common requests

# Build an id -> name map, archived people included so old ids still resolve
GET /worker?isArchived=true&isArchived=false

# Resolve a specific set of ids, archived people included
POST /worker/query
{ "id": ["<uuid>", "<uuid>"], "isArchived": [true, false], "select": ["id", "name"] }

# Only people currently on the roster
GET /worker?status=active

# Look someone up by your own identifier
GET /worker?customerIdentifier=E12345

# Head count by status
POST /worker/group-and-count
{ "groupByField": "status" }

# Create someone; only name is required
POST /worker
{ "name": "Jane Doe", "customerIdentifier": "E12345" }

Getting started

Core concepts

Resources

Materials and inventory

Delivery

Organization lists

Domain concepts

Examples

Fields

What you can write

Archive and restore

Deleting

Common requests

​Fields

​What you can write

​Archive and restore

​Deleting

​Common requests

Fields

What you can write

Archive and restore

Deleting

Common requests