User Model

Learn about the Staffbase user model.

Employee App
Staffbase Intranet
Staffbase Email

Whenever you interact with users through our API, the data you receive or send is structured according to this user model. Keep in mind that all optional properties can be null, and properties marked as read-only cannot be modified when using the 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. 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).
role string The permission role of the user. Possible values: admin, editor, moderator, reader, restricted. Check out the role type for more information.
createdAt timestamp read-only The timestamp for the date the user was created.
activatedAt 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.
profile.firstName string The first name of the user. Nested inside the profile object.
profile.lastName string The last name of the user. Nested inside the profile object.
profile.publicEmailAddress string optional The email address shown publicly in the user’s profile. Not used for login or notifications. Nested inside the profile object.
profile.phoneNumber string optional The user’s phone number shown publicly in the user’s profile. Nested inside the profile object.
profile.position string optional The position the user has in the company. Nested inside the profile object.
profile.department string optional The department the user belongs to. Nested inside the profile object.
profile.location string optional The location the user works at. Nested inside the profile object.
profile.avatar Avatar Type optional The avatar image of a user. Nested inside the profile object. Check out the Avatar type for more information.
profile.{{customProfileFieldId}} string optional A 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.
name type description
externalId string optional An external id to identify the user in your organization. Must be unique. Visible to administrators only.
email object optional The 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.
userName object optional The 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.
secret string optional The 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.
recoveryCode object optional The 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.
sendMail boolean optional Whether 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.locale string optional The 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}}"
    }
}