User GET Resources

User by ID/UniqueId

GET /users/:id

or for fetching current session user

GET /users/me

Gets a single user by their ID/Global User ID/Unique ID. Ids will be tried in the following order:

  • ID, which is an integer.
  • Global User ID, which is a UUID.
  • Unique ID, which is any arbitrary string.
Parameter Type Default Description
deanonymize_deleted_users Boolean false Allows to override the anonymize_deleted_users network setting, if the user has the permission to see deleted users. Requires the role user_admin. See: Anonymization of deleted users
deanonymize_users_email Boolean false Allows to override the anonymize_users_email network setting, if the user has the permission to see the email of other users. Requires the role user_admin. See: email anonymization

Response

{
  "id": 42,
  "is_deleted": false,
  "is_hidden": false,
  "is_system": false,
  "is_technical_user": false,
  "language": "en",
  "gender": "m",
  "firstname": "Sherlock",
  "lastname": "Holmes",
  "email": "sherlock.holmes@example.com",
  "event_tracking_id": "95543d35-255c-11e9-86c5-0242ac110007",
  "auth_type": "simple",
  "location": "Baker Street 221B, London",
  "about": "Private Detective",
  "country": "uk",
  "company": "Ward, Lock & Co",
  "department": "Investigations",
  "position": "Master Detective",
  "image": "https://cdn.example.com/user/6/i_2d1b84215e2f035a22f6fec213d3b1d9.jpg",
  "first_seen": "2015-02-02T11:31:05.000Z",
  "last_seen": "2017-02-02T15:02:00.000Z",
  "customfields": { "occupation": "Detective" },
  "score_level": 4,
  "score_points": 84,
  "global_user_id": "95543d35-255c-11e9-86c5-0242ac110007"
}

List of Users

GET /users?filter=active

Delivers a list of Starmind Users. If not specified via include-parameter, the list only contains non-deleted and non-technical users.

Parameter Type Default Description
include_deleted Boolean false include_deleted is deprecated from version 2.43.0. Use the include parameter instead.
include_deleted will also return deleted users if true and the user has the permission to view deleted users. Because a special permission is required, deleted users are not anonymized, regardless of the anonymize_deleted_users setting.
include string Allows additional users to be returned, which aren't returned by default.
The current user must have special permission to use any of the includes. If deleted users are included, they will not be anonymised, regardless of the anonymize_deleted_users setting.
Allowed includes are:
  • deleted additionally includes deleted users
  • technical additionally includes technical users
  • hidden deprecated. will be accepted for backwards-compatibility but has no effect
  • system deprecated. synonym for technical
Multiple include criteria can be specified as comma-separated string. The response will then, in addition to those users who are returned by default, also include all users who satisfy any of the specified include criteria.
sort string id.asc Specify the criteria the result is sorted by. The allowed sort criteria are id, firstname, lastname, email, first_seen, last_seen. The format is CRITERION.DIRECTION,CRITERION.DIRECTION.

This parameter overrules the result ordering of the query parameter.
query String The search query.
The results are ordered by relevance for the given query (unless a sort parameter overrides this behaviour).
Consult the Concepts section for more technical details about search.
filter string Allows to filter the list of users with filter-criteria.
Allowed filters are:
  • active Show only active users
  • inactive Show only inactive users
role string Filter the list by user role. role must be a valid user-role. A list of valid roles can be found here.
deanonymize_users_email Boolean false Allows to override the anonymize_users_email network setting, if the user has the permission to see other users email. Requires the role user_admin. See: Email Anonymization
limit int 25 Sets how many hits are returned at once.
offset int 0 Offset from the first hit.
terms_version_not_accepted string The id of latest published Terms of Use. When provided, filters out users who did not accept the specifid Terms Of Use version.

Will return a paginated list of all users who match the given parameters.

{
    "total": 2,
    "_links": {
    "self": {
        "href": "/api/v1/users?query=holmes&offset=0&limit=10&include_deleted=false&filter=active&terms_version_not_accepted=3"
    }
    },
    "items": [
        {
          "id": 42,
          "is_deleted": false,
          "is_hidden": false,
          "is_system": false,
          "is_technical_user": false,
          "language": "en",
          "gender": "m",
          "firstname": "Sherlock",
          "lastname": "Holmes",
          "email": "sherlock.holmes@example.com",
          "event_tracking_id": "95543d35-255c-11e9-86c5-0242ac110007",
          "auth_type": "simple",
          "location": "Baker Street 221B, London",
          "about": "Private Detective",
          "country": "uk",
          "company": "Ward, Lock & Co",
          "department": "Investigations",
          "position": "Master Detective",
          "image": "https://cdn.example.com/user/6/i_2d1b84215e2f035a22f6fec213d3b1d9.jpg",
          "first_seen": "2015-02-02T11:31:05.000Z",
          "last_seen": "2017-02-02T15:02:00.000Z",
          "customfields": { "occupation": "Detective" },
          "score_level": 4,
          "score_points": 84,
          "global_user_id": "95543d35-255c-11e9-86c5-0242ac110007"
        },
        {
          "id": 43,
          "is_deleted": false,
          "is_hidden": false,
          "is_system": false,
          "is_technical_user": false,
          "language": "en",
          "gender": "m",
          "firstname": "Ana",
          "lastname": "Holmes",
          "email": "ana.holmes@example.com",
          "event_tracking_id": "43543d35-255c-11e9-86c5-0242ac110042",
          "auth_type": "simple",
          "location": "Baker Street 221B, London",
          "about": "Private Detective",
          "country": "uk",
          "company": "Ward, Lock & Co",
          "department": "Investigations",
          "position": "Master Detective",
          "image": "https://cdn.example.com/user/6/i_2d1b84215e2f035a22f6fec213d3b1aa.jpg",
          "first_seen": "2015-02-02T11:31:05.000Z",
          "last_seen": "2017-02-02T15:02:00.000Z",
          "customfields": { "occupation": "Detective" },
          "score_level": 4,
          "score_points": 84,
          "global_user_id": "95543d35-255c-11e9-86c5-0242ac110007"
        }
    ]
}

Expertise

GET /users/:id/expertise
Parameter Type Default Description
limit int 15 At most this many tags will be returned.

Gets a list of tags where the user has the highest expertise, sorted by "intensity". "Intensity" is a relative measure of expertise and can be "high", "medium", or "low".

In order to prevent the user from being identified as the poser of certain questions (see question poser anonymity), tags that are only linked with this user through question posing are excluded from the response.

The response will contain at most 30 tags, even if a higher value is specified for the limit parameter.

The response of this endpoint is entirely based on Starmind's AI. In order to give each user more control about the tags that are shown on their profile, the Know How endpoints can be used instead.

Response

[
    {
        "label": "Baker Street",
        "intensity": "high"
    },
    {
        "label": "Moriarty",
        "intensity": "high"
    },
    {
        "label": "Study",
        "intensity": "medium"
    },
    {
        "label": "Scarlet",
        "intensity": "low"
    }
]

Scores

GET /users/scores

If the user-score feature is enabled, gets an unpaginated list of all users with their scores, sorted by e-mail address. Deleted and debug users are excluded. Returns an error if the user-score extension is disabled.

Response

[
    {
            "email": "siger.holmes@example.com",
            "user_id": 17309,
            "level": 4,
            "points": 620,
            "last_update": "2015-08-09T11:31:05.000Z"
    },
    {
            "email": "sherlock.holmes@example.com",
            "user_id": 17310,
            "level": 28,
            "points": 39200,
            "last_update": "2015-08-09T11:31:05.000Z"
    }
]