User Model

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.
enabledboolean read-onlyWhether or not this user is enabled according to the user's state.
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.
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.

Note: 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: [ "myOpenGroup1", "myOpenGroup2" ]. 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.

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}

Example (GET)

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

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