Learn about the Staffbase user model.
Whenever you get in touch with users in our API the data you get or need to send with are modelled following this user model. Please be aware of that all optional properties can be null. Properties that are marked as read-only cannot be changed when using our API directly.
| name | type | description |
|---|---|---|
| id | objectId read-only | The internal Staffbase id of the user. The system creates this property automatically: it is unique and cannot be changed. |
| status | string read-only | The status of a user could be activated, pending, or deactivated. The status activated belongs to a user who has signed up successfully and can login. The status pending belongs to a user who has been invited recently to the organisation but has not signed up yet. The status deactivated belongs to a user who should not be able to login anymore. |
| role | role type | Defines the role a user can have. Check out the role type for more information. |
| created | timestamp read-only | The timestamp for the date the user was created. |
| updated | timestamp read-only | The timestamp for the most recent date the user has been updated. |
| activated | timestamp read-only | The timestamp for the date the user was activated. If the user was deactivated and later re-activated, it always contains the timestamp of the last activation |
| firstName | string | The first name of the user. This property is a system profile field. |
| lastName | string | The last name of the user. This property is a system profile field. |
| publicEmailAddress | string optional | This is the email address that should be shown publicly in the user’s profile, not the primary email address used for password recovery and email notifications. This property is a system profile field. |
| phoneNumber | string optional | The user’s phone number. This is the phone number that should be shown publicly in the user’s profile. This property is a system profile field. |
| position | string optional | The position the user has in the company. This property is a system profile field. |
| department | string optional | The department the user belongs to. This property is a system profile field. |
| location | string optional | The location the user works at. This property is a system profile field. |
profile: { {{customProfileFieldId}} } | string optional | This property is a custom profile field. |
| name | type | description |
|---|---|---|
| externalID | string optional | This id can be set as an external id to identify the user in your organisation. Therefore, this property needs to be unique, too. It is only visible to the admin. |
| emails/primary | string optional | The primary email address of a user. This email address can be used for an email invitation and/or news email notifications. See the onboarding with email & password article on our support portal. |
| userName | string optional | The username a user logs in with. See the onboarding with username & password article on our support portal. |
| secret | string optional | The one-time password of a user. The user will have to change the one-time password during first login. |
| tags | set[string] optional | Tags are a set of attributes added to a user’s profile. These tags allow you to create automated groups based on specific conditions, also known as conditional groups. See also our Tagging for Conditional Group Assignment support article. Example: ["location:NYC", "profile:jobtype:accountant"]. |
| recoveryCode | string optional | The recovery code of a user to reset the password. See the account recovery section on our support portal. |
| recoveryCodeExpires | timestamp optional | Expiration date for recovery code in a timestamp format with milliseconds. By default the recovery code has no expiration date. |
| mandatoryGroupIDs | set[string] optional | Set of open group identifiers, for example: ["5fb67f34cc8c407fbdd11234","5fb67f34cc8c407fbdd11235"]. See the mandatory group management section on our support portal. |
| sendMail | boolean optional | This property determines if an email invitation is sent out from the Staffbase platform to the primary email address of a user. Only set this property to true when the invitation email is intended. |
| inviteMessage | string optional | Optional message to be included in the invitation mail when inviting a new user to the App. |
| avatar | Avatar Type optional | This property represents the avatar image of a user. Check out the Avatar type for more information. |
| config.locale | string optional | This property represents the content language (locale) of a user. Check out the Languages and Locale Codes for more information. Upon the first sign-in, a user’s content language is set based on the device or browser language used during the registration. This property is visible only to Administrators. |
This is an example JSON request for creating (POST) a user.
{ "externalID": "jd123", "userName": "john.doe", "secret": "start1234", "recoveryCode": "reset1234", "recoveryCodeExpires": "1640905200000", "emails/primary": "john@doe.com", "sendMail": false, "avatar": "{{URL}}", "role": { "type": "admin" }, /* fill custom profile fields */ "profile": { "{{customProfileFieldId}}": "{{valueXY}}" }, /* fill system profile fields */ "firstName": "John", "lastName": "Doe", "publicEmailAddress": "john@doe.com", "position": "Developer", "department": "Development & Research", "location": "Chemnitz", "phoneNumber": "+491234567890", /* set user's content language */ "config": { "locale": "en_US" }}This is an example JSON response for retrieving (GET) a user.
{ "activated": "2021-12-14T08:21:13.949Z", "avatar": { "original": { "url": "{{URL}}", }, "icon": { "url": "{{URL}}", }, "thumb": { "url": "{{URL}}" } }, "config": { "locale": "en_US" }, "created": "2021-02-28T09:39:44.431Z", "department": "Development & Research", "emails": [ { "value": "john@doe.com", "primary": true } ], "externalID": "jd123", "firstName": "John", "groupIDs": [], "id": "603b64e00c3fdb29134eb89b", "lastName": "Doe", "location": "Chemnitz", "mandatoryGroupIDs": null, "phoneNumber": "+491234567890", "position": "Developer", "profile": { /* summary of user system + custom profile fields */ "firstName": "John", "lastName": "Doe", "phoneNumber": "+491234567890", "publicEmailAddress": "john@doe.com", "location": "Chemnitz", "position": "Developer", "department": "Development & Research", "{{customProfileFieldId}}": "{{valueXY}}", "avatar": { "original": { "url": "{{URL}}", }, "icon": { "url": "{{URL}}", }, "thumb": { "url": "{{URL}}" } } }, "publicEmailAddress": "john@doe.com", "recoveryCode": { "expires": 1640905200000, "plain": "reset1234" }, "role": { "type": "admin" }, "userName": { "value": "john.doe", "providerID": "staffbase" }, "status": "activated", "tags": [ /* tags for group tagging */ "profile:{{customProfileFieldId}}:{{valueXY}}" ], "updated": "2021-02-28T09:39:44.441Z"}