User Model

Learn about the Staffbase user model.

Employee App
Staffbase Intranet
Staffbase Email

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.

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. Possible values: activated (can log in), pending (invited but not yet signed up), deactivated (login disabled), deleted (account removed), contact (Staffbase Email only, no login access).
rolestringThe permission role of the user. Possible values: admin, editor, moderator, reader, restricted. Check out the role type for more information.
createdAttimestamp read-onlyThe timestamp for the date the user was created.
activatedAttimestamp 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.
profile.firstNamestringThe first name of the user. Nested inside the profile object.
profile.lastNamestringThe last name of the user. Nested inside the profile object.
profile.publicEmailAddressstring optionalThe email address shown publicly in the user’s profile. Not used for login or notifications. Nested inside the profile object.
profile.phoneNumberstring optionalThe user’s phone number shown publicly in the user’s profile. Nested inside the profile object.
profile.positionstring optionalThe position the user has in the company. Nested inside the profile object.
profile.departmentstring optionalThe department the user belongs to. Nested inside the profile object.
profile.locationstring optionalThe location the user works at. Nested inside the profile object.
profile.avatarAvatar Type optionalThe avatar image of a user. Nested inside the profile object. Check out the Avatar type for more information.
profile.{{customProfileFieldId}}string optionalA custom profile field value. Use the profile field ID as the key.
If you want to use the properties profile.position, profile.department and/or profile.location for conditional group tagging, please use a custom profile field and enable tagging for the newly created custom field.
nametypedescription
externalIdstring optionalAn external id to identify the user in your organization. Must be unique. Visible to administrators only.
emailobject optionalThe primary email used for email invitations and notifications. It is an object in the format: { "value": "...", "source": "system" }. See the onboarding with email & password article for details.
userNameobject optionalThe username used by a user for login. It is an object in the format: { "source": "user" }. See the onboarding with username & password article for details.
secretstring optionalThe one-time password or access code of a user. The user must change it on first login. If no secret is provided, one is auto-generated based on the app’s password policy.
recoveryCodeobject optionalThe recovery code for password reset. The object includes two fields: plain, which holds the actual recovery code value, and expires, which defines the expiration timestamp in milliseconds. By default, no expiration time is set. See the account recovery sectionfor details.
sendMailboolean optionalWhether to send an email invitation to the user’s primary email address. Set this to true when an invitation is intended. Defaults to true if omitted.
config.localestring optionalThe content language (locale) of the user. For supported values, see Languages and Locale Codes.
Upon the first sign-in, a user’s content language is set based on the device or browser language used during 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": {
        "plain": "reset1234",
        "expires": "1640905200000"
    },
    "email": "john@doe.com",
    "sendMail": false,
    "role": "admin",
    /* fill custom profile fields and avatar */
    "profile": {
        "firstName": "John",
        "lastName": "Doe",
        "publicEmailAddress": "john@doe.com",
        "position": "Developer",
        "department": "Development & Research",
        "location": "Chemnitz",
        "phoneNumber": "+491234567890",
        "{{customProfileFieldId}}": "{{valueXY}}",
        "avatar": {
            "original": { "url": "{{URL}}" },
            "icon": { "url": "{{URL}}" },
            "thumb": { "url": "{{URL}}" }
        }
    },
    /* set user's content language */
    "config": {
      "locale": "en_US"
    }
}

This is an example request and response for retrieving (GET) a specific user.

Terminal window
export USERID="603b64e00c3fdb29134eb89b"
export AUTH="Basic {{Token}}"


curl -X GET "https://exampleapp.staffbase.com/api/users/$USERID" \
  -H "Authorization: $AUTH" \
  -H "Accept: application/vnd.staffbase.accessors.user.v3+json" \
  -H "Content-Type: application/vnd.staffbase.accessors.user.v3+json" \
  --compressed | json_pp

Example response:

{
    "id": "603b64e00c3fdb29134eb89b",
    "createdAt": "2021-02-28T09:39:44.431Z",
    "activatedAt": "2021-12-14T08:21:13.949Z",
    "externalId": "jd123",
    "role": "admin",
    "status": "activated",
    "email": {
        "value": "john@doe.com",
        "source": "system"
    },
    "userName": {
        "source": "user"
    },
    "config": {
        "locale": "en_US"
    },
    "profile": {
        /* system profile fields */
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+491234567890",
        "publicEmailAddress": "john@doe.com",
        "location": "Chemnitz",
        "position": "Developer",
        "department": "Development & Research",
        "avatar": {
            "original": {
                "url": "{{URL}}",
                "width": 250,
                "height": 250,
                "size": 12086,
                "format": "png",
                "mimeType": "image/png"
            },
            "icon": {
                "url": "{{URL}}",
                "format": "png",
                "mimeType": "image/png"
            },
            "thumb": {
                "url": "{{URL}}",
                "format": "png",
                "mimeType": "image/png"
            }
        },
        /* custom profile fields */
        "{{customProfileFieldId}}": "{{valueXY}}"
    }
}