A project is one customer job. Orders hang off a project, and most reporting rolls
up to it.
Identifier prefix: PROJ-
Search columns: name, identifier
Standard CRUD applies. See standard endpoints.
Fields
Every property the API returns for a project.
Creating a project
Only name is required:
Leave identifier out and you get one like PROJ-a1b2c. Send your own if you
already have a project number in another system, and it becomes the value you can
look the project up by later.
Every project gets a Jobsite
Creating a project also creates one project-owned Jobsite location, in the same
transaction. Your projects always have somewhere to ship to, and you never have to
create the Jobsite yourself.
Pass an address on create and it lands on that Jobsite:
jobsiteAddress is create-only, and a few things follow from that:
- Every field inside it is optional, so a partial address is fine.
country accepts US and CA.PATCH, PUT, and the bulk routes ignore the field rather than rejecting it.- It never comes back in a project response. Send the object with all fields
blank, or leave it out, and the Jobsite is created without an address.
What you can write
Everything else in the table above is set by BuildingSwell.
Archive and restore
There is no separate archive endpoint. Flip isArchived with a PATCH, and BuildingSwell handles the rest.
When you archive:
name and identifier both get an - (archived <timestamp>) suffix, where <timestamp> is the archive time in epoch milliseconds, so they stop colliding with your active projects. Match the suffix with a pattern, not a literal string.archivedAt is stamped with the current time.
When you restore, the suffix comes off. If an active project has taken the original name or identifier in the meantime, the next free variant is used instead, for example Warehouse A (1).
Archived records drop out of list results by default. Ask for them with an explicit filter:
Deleting
DELETE /project/{id} is destructive.Permanently removes the project row. This is not the archive operation and it cannot be undone.In practice this call fails with 409 for any project created through the API or the app. Every project owns at least one Jobsite location, and that link is ON DELETE RESTRICT, so the database refuses the delete while the Jobsite exists. Archive the project instead: PATCH /project/{id} with { "isArchived": true }.If the delete does go through, qc_inspection_set.projectId on any related QC entry is set to null and the entry itself is kept.
