Skip to main content

Users

SaaS: Users (1.1.0)

Download OpenAPI specification:Download

API for interacting with SaaS Users.

Tasks

Get task

Returns the details of the given task.

Authorizations:
bearerAuth
path Parameters
id
required
string

The unique ID of the task.

Responses

Response samples

Content type
application/json
{
  • "id": "483c67cf-e247-4a82-bef7-b86a29560788",
  • "name": "Export users",
  • "status": "Complete",
  • "description": "The export completed successfully.",
  • "_links": {
    }
}

Users

Get users

Returns a collection of users.

Authorizations:
bearerAuth
query Parameters
page_size
integer <= 1000
Default: 100

The maximum number of items in the response.

page_number
integer <int64>
Default: 1

The page number.

filter
string
Example: filter=?filter=field1 -eq "abc"

For more information on the available operators and which data types those operators work on, see Filter API call results.

sort
string
Example: sort=?sort=field1:asc

For more information on sorting capability and examples, see Sort API call results.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "items": [
    ]
}

Get user KPIs

Returns a collection of users' key performance indicators.

Authorizations:
bearerAuth
query Parameters
fromDate
required
string
Example: fromDate=2024-05-01T00:00:00Z

The start date from which the historical key performance indicator data should be returned.

toDate
required
string
Example: toDate=2024-06-01T00:00:00Z

The end date to which the historical key performance indicator data should be returned.

Responses

Response samples

Content type
application/json
{
  • "active": 10,
  • "activeChartData": [
    ],
  • "activeTrend": 10,
  • "currentActiveChartData": [
    ],
  • "currentInactiveChartData": [
    ],
  • "currentNoActivityChartData": [
    ],
  • "currentTotalChartData": [
    ],
  • "inactive": 10,
  • "inactiveChartData": [
    ],
  • "inactiveTrend": 10,
  • "noActivity": 10,
  • "noActivityChartData": [
    ],
  • "noActivityTrend": 10,
  • "total": 10,
  • "totalChartData": [
    ],
  • "totalTrend": 10
}

Get user

Returns the details of a user.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: a7a75b83-2690-4cc9-b652-a0fbe93dba4a

The unique ID of the user.

Responses

Response samples

Content type
application/json
{
  • "country": "Japan",
  • "createdDate": "2024-05-25T00:00:00Z",
  • "department": "Engineering",
  • "discoveryTypes": {
    },
  • "displayName": "John Doe",
  • "email": "john.doe@organization.com",
  • "id": "2f86b198-04f3-4770-ad08-b32518206da0",
  • "isEnabled": true,
  • "isInReview": true,
  • "isOnline": true,
  • "isQualified": true,
  • "lastActive": "2024-06-28T00:00:00Z",
  • "licenseCount": 5,
  • "potentialSavings": 500,
  • "status": "Active",
  • "userCostPerMonth": 1000,
  • "username": "john.doe_1@org.com"
}

Update user

Modifies is-in-review, is-online and is-qualified user properties.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: a7a75b83-2690-4cc9-b652-a0fbe93dba4a

The unique ID of the user.

Request Body schema: application/merge-patch+json
isOnline
required
boolean

true if user only exists as SaaS user; who does not have a device that is inventoried in your organization. This is common for, for example, consultants and other temporary staff; otherwise, false.

isInReview
required
boolean

true if is user is one you need to analyze further, or as a reminder for taking action on their subscriptions; otherwise, false.

isQualified
required
boolean

true if user is to be included in Snow's services which incur a cost; otherwise, false.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "isOnline": true,
  • "isInReview": true,
  • "isQualified": true
}

Response samples

Content type
application/json
{
  • "country": "Japan",
  • "createdDate": "2024-05-25T00:00:00Z",
  • "department": "Engineering",
  • "discoveryTypes": {
    },
  • "displayName": "John Doe",
  • "email": "john.doe@organization.com",
  • "id": "2f86b198-04f3-4770-ad08-b32518206da0",
  • "isEnabled": true,
  • "isInReview": true,
  • "isOnline": true,
  • "isQualified": true,
  • "lastActive": "2024-06-28T00:00:00Z",
  • "licenseCount": 5,
  • "potentialSavings": 500,
  • "status": "Active",
  • "userCostPerMonth": 1000,
  • "username": "john.doe_1@org.com"
}

Get user applications

Returns a collection of applications that have been detected as being used by the given user.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: a7a75b83-2690-4cc9-b652-a0fbe93dba4a

The unique ID of the user.

query Parameters
page_size
integer <= 1000
Default: 100

The maximum number of items in the response.

page_number
integer <int64>
Default: 1

The page number.

filter
string
Example: filter=?filter=field1 -eq "abc"

For more information on the available operators and which data types those operators work on, see Filter API call results.

sort
string
Example: sort=?sort=field1:asc

For more information on sorting capability and examples, see Sort API call results.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "items": [
    ]
}

Get user subscriptions

Returns a collection of subscriptions in use by the given user.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: a7a75b83-2690-4cc9-b652-a0fbe93dba4a

The unique ID of the user.

query Parameters
page_size
integer <= 1000
Default: 100

The maximum number of items in the response.

page_number
integer <int64>
Default: 1

The page number.

filter
string
Example: filter=?filter=field1 -eq "abc"

For more information on the available operators and which data types those operators work on, see Filter API call results.

sort
string
Example: sort=?sort=field1:asc

For more information on sorting capability and examples, see Sort API call results.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "items": [
    ]
}

Get user discovery sources

Returns a collection of discovery sources for the given user.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: a7a75b83-2690-4cc9-b652-a0fbe93dba4a

The unique ID of the user.

query Parameters
page_size
integer <= 1000
Default: 100

The maximum number of items in the response.

page_number
integer <int64>
Default: 1

The page number.

filter
string
Example: filter=?filter=field1 -eq "abc"

For more information on the available operators and which data types those operators work on, see Filter API call results.

sort
string
Example: sort=?sort=field1:asc

For more information on sorting capability and examples, see Sort API call results.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "items": [
    ]
}

Bulk update users

Modifies a collection of user properties the provided applications.

Authorizations:
bearerAuth
Request Body schema: application/json
filter
string

For more information on the available operators and which data types those operators work on, see Filter API call results.

scope
required
string
Enum: "Only" "All" "AllExcept"

The scope of the update operation.

ids
Array of strings

The IDs that the operation is performed on.

required
object (UserStatus)

The update to be applied to all IDs.

onlineOnly
boolean

true if the user is marked as online only; otherwise, false.

review
boolean

true if the user is marked as for review; otherwise, false.

qualified
boolean

true if the user is marked as qualified; otherwise, false.

Responses

Request samples

Content type
application/json
{
  • "filter": "name -eq Per",
  • "scope": "All",
  • "ids": [
    ],
  • "body": {
    }
}

Response samples

Content type
application/json
{
  • "id": "483c67cf-e247-4a82-bef7-b86a29560788",
  • "_links": {
    }
}

Get bulk update users summary

Returns the details of a completed async bulk update operation.

Authorizations:
bearerAuth
path Parameters
id
required
string

The unique ID of the summary.

Responses

Response samples

Content type
application/json
{
  • "successCount": 10,
  • "failedCount": 10,
  • "failed": {
    },
  • "failureReason": "These users failed for reasons x and y."
}