User Model

Learn about the Staffbase user model.

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.

Properties

nametypedescription
idobjectId read-onlyThe internal Staffbase id of the user. The system creates this property automatically: it is unique and cannot be changed.
statusstring read-onlyThe 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.
rolerole typeDefines the role a user can have. Check out the role type for more information.
createdtimestamp read-onlyThe timestamp for the date the user was created.
updatedtimestamp read-onlyThe timestamp for the most recent date the user has been updated.
activatedtimestamp read-onlyThe 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
firstNamestringThe first name of the user. This property is a system profile field.
lastNamestringThe last name of the user. This property is a system profile field.
publicEmailAddressstring optionalThis 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.
phoneNumberstring optionalThe 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.
positionstring optionalThe position the user has in the company. This property is a system profile field.
departmentstring optionalThe department the user belongs to. This property is a system profile field.
locationstring optionalThe location the user works at. This property is a system profile field.
profile: { {{customProfileFieldId}} }string optionalThis property is a custom profile field.
If you want to use the properties position, department and/or location for conditional group tagging, please use a custom profile field and enable tagging for the newly created custom field.

Additional properties

nametypedescription
externalIDstring optionalThis 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/primarystring optionalThe 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.
userNamestring optionalThe username a user logs in with. See the onboarding with username & password article on our support portal.
secretstring optionalThe one-time password of a user. The user will have to change the one-time password during first login.
tagsset[string] optionalTags 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"].
recoveryCodestring optionalThe recovery code of a user to reset the password. See the account recovery section on our support portal.
recoveryCodeExpirestimestamp optionalExpiration date for recovery code in a timestamp format with milliseconds. By default the recovery code has no expiration date.
mandatoryGroupIDsset[string] optionalSet of open group identifiers, for example: ["5fb67f34cc8c407fbdd11234","5fb67f34cc8c407fbdd11235"]. See the mandatory group management section on our support portal.
sendMailboolean optionalThis 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.
inviteMessagestring optionalOptional message to be included in the invitation mail when inviting a new user to the App.
avatarAvatar Type optionalThis property represents the avatar image of a user. Check out the Avatar type for more information.
config.localestring optionalThis 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.

Example (POST)

This is an example JSON request for creating (POST) a user.

1{
2 "externalID": "jd123",
3 "userName": "john.doe",
4 "secret": "start1234",
5 "recoveryCode": "reset1234",
6 "recoveryCodeExpires": "1640905200000",
7 "emails/primary": "john@doe.com",
8 "sendMail": false,
9 "avatar": "{{URL}}",
10 "role": {
11 "type": "admin"
12 },
13 /* fill custom profile fields */
14 "profile": {
15 "{{customProfileFieldId}}": "{{valueXY}}"
16 },
17 /* fill system profile fields */
18 "firstName": "John",
19 "lastName": "Doe",
20 "publicEmailAddress": "john@doe.com",
21 "position": "Developer",
22 "department": "Development & Research",
23 "location": "Chemnitz",
24 "phoneNumber": "+491234567890",
25 /* set user's content language */
26 "config": {
27 "locale": "en_US"
28 }
29}

Example (GET)

This is an example JSON response for retrieving (GET) a user.

1{
2 "activated": "2021-12-14T08:21:13.949Z",
3 "avatar": {
4 "original": {
5 "url": "{{URL}}",
6 },
7 "icon": {
8 "url": "{{URL}}",
9 },
10 "thumb": {
11 "url": "{{URL}}"
12 }
13 },
14 "config": {
15 "locale": "en_US"
16 },
17 "created": "2021-02-28T09:39:44.431Z",
18 "department": "Development & Research",
19 "emails": [
20 {
21 "value": "john@doe.com",
22 "primary": true
23 }
24 ],
25 "externalID": "jd123",
26 "firstName": "John",
27 "groupIDs": [],
28 "id": "603b64e00c3fdb29134eb89b",
29 "lastName": "Doe",
30 "location": "Chemnitz",
31 "mandatoryGroupIDs": null,
32 "phoneNumber": "+491234567890",
33 "position": "Developer",
34 "profile": {
35 /* summary of user system + custom profile fields */
36 "firstName": "John",
37 "lastName": "Doe",
38 "phoneNumber": "+491234567890",
39 "publicEmailAddress": "john@doe.com",
40 "location": "Chemnitz",
41 "position": "Developer",
42 "department": "Development & Research",
43 "{{customProfileFieldId}}": "{{valueXY}}",
44 "avatar": {
45 "original": {
46 "url": "{{URL}}",
47 },
48 "icon": {
49 "url": "{{URL}}",
50 },
51 "thumb": {
52 "url": "{{URL}}"
53 }
54 }
55 },
56 "publicEmailAddress": "john@doe.com",
57 "recoveryCode": {
58 "expires": 1640905200000,
59 "plain": "reset1234"
60 },
61 "role": {
62 "type": "admin"
63 },
64 "userName": {
65 "value": "john.doe",
66 "providerID": "staffbase"
67 },
68 "status": "activated",
69 "tags": [
70 /* tags for group tagging */
71 "profile:{{customProfileFieldId}}:{{valueXY}}"
72 ],
73 "updated": "2021-02-28T09:39:44.441Z"
74}