Skip to main content
The BuildingSwell app calls this Users. The API calls it organization-member. This page uses the API name so it matches the requests you write.
A membership joins a user account to your organization and gives it a role. The account itself is shared across organizations, which is why its email and name arrive under a nested appUser object. Search columns: appUser.name, appUser.email
Requires admin access, or the User.Read and User.Update permissions.

​
Fields

Every property the API returns for a user.

​
Invite a user

POST /organization-member replaces the standard create. You send an email address, not a user id:
Pass name as well to set the display name on a brand-new account. If no account exists for that email, one is created. Either way an invitation goes out and appUser.status stays pending until the person accepts. Resend it if the first one was missed:

​
Update a membership

PATCH /organization-member/{id} accepts name, roleId, roleType, and workerId. Pass workerId: null to unlink the person record. name updates the display name on the linked user account, so one request is enough to correct a member’s name:
The new name comes back as appUser.name, since that is where it lives.
email cannot be changed. It identifies the login and is owned by the identity provider. Deleting and re-inviting the member creates a new account rather than moving the existing one, so an email change is a support request.

​
Deactivate instead of deleting

Deactivating takes away access but keeps the membership and its history, and it reverses cleanly:
Both respond 204 with no body. Reach for these rather than DELETE /organization-member/{id}.

​
Two status fields

status is the membership: whether the person can use your organization. appUser.status is the account: whether they have accepted their invite and verified their email. A pending account with an active membership is someone who was invited and has not signed in yet.

​
What you can write

Everything else in the table above is set by BuildingSwell. name and workerId are not membership columns: name is written to the linked user account and read back as appUser.name, and workerId links the person record. Neither appears on the membership itself. email is set once, on the invite, and cannot be changed afterwards.

​
Deleting

DELETE /organization-member/{id} is destructive.Permanently removes the membership, which cuts the user’s access to your organization. This cannot be undone.To take access away reversibly, use PATCH /organization-member/{id}/deactivate instead. That keeps the membership and its history, and it can be reversed with /reactivate.
See archiving and deleting for the full picture across resources.