Unified Software API to combine package data and software instance data

10.0.5 With the /api/sam/unified/current/software API, you can view the currently installed software instances and package data together.

Simplified integrations with one API that covers discovered software

The API shows the following information:
  • Currently installed software instances and package data
  • Software instances and package data that are not suppressed
  • Package data that is not recognized
  • The computer data that can be accessed through computer association, such as computer association


User You must have the View Endpoints and View Raw Data permissions to use this API.

Resource URL



GET /api/sam/unified/current/software?token=<token>

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Accept-Language (optional)
en-US (only English is supported)

Negotiates the language of the response. If the header is not specified, the content is returned in the server language.

Request format application/json
Response headers

Specifies the content type of the response.


Specifies the language of the response content. If the header is not specified, the content is returned in the server language.

Response payload Unified Software element
Response format application/json
Response codes

200 – OK

400 – "Bad Request" if a query parameter contains errors or is missing

Schema description

To retrieve the list of all columns that are returned by this association together with their descriptions, use the following request:
GET /api/sam/unified/current/schemas/software.json?token=<token>

Available columns

Table 2. Columns with information about computer details
Column Description Displayed by default Type
id Identifier of the component instance or package. Numeric
name Name of the component or package. String
release Release of the component or package version. String
detailed_version Detailed version of the component or package version. String
discoverable_guid Globally unique identifier (GUID) of the component or sha1 of the package. String
discoverable_family_guid Family GUID of the component. For packages, the returned value is null. String
publisher_name Component publisher or package vendor. String
discovery_start Date and time when the component or package was reported for the first time. The time is specified in the GMT time zone. String
discovery_path Path to the folder where the component is installed. For packages, the returned value is null. String
source Type of the software:
  • 0: component instance
  • 1: Windows package
  • 2: Unix package
computer.id ID of the computer where the software is discovered. Numeric
computer.name Name of the computer where the software is discovered. String

Applicable association

You can additionally retrieve data from the computer association.

Query parameters

Table 3. Query parameters
Parameter Description Required Value
columns Specify which columns to retrieve. If you do not specify this parameter, only default columns are retrieved.
Example: Retrieve release
order Specify how to sort the returned data. The default direction for sorting columns is ascending. If you want to specify a descending sort, append desc to the column name.
Example: Order by ID descending
URL?order[]=id desc
limit Specify the number of rows to retrieve. If you omit this parameter, all rows are retrieved.
Example: Retrieve 100 records
offset Specify the number of rows to skip for retrieving results. You can use it together with the limit parameter to paginate results.
Example: Retrieve 50 records starting after record 150
token A unique user authentication identifier. You can retrieve it by using REST API for retrieving authentication token. You can also log in to BigFix Inventory, hover over the User icon User icon, and click Profile. Then, click Show token. Alphanumeric
criteria Retrieve records that match specific conditions. The parameter should have the following structure, written in one line:
<criteria> ::= <left-brace> <boolean-operator> <colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>
<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> ::= <json-array> | <json-string> | <json-number> | <json-null>

For more information about operators, see: Common connectors and operators.

Example: Retrieve a software instance whose name contains "BigFix" or the discovery start is within a specific date range
URL?criteria={ "or": [ ["name", "contains", "BigFix"], 
{ "and": [ ["discovery_start", ">", "2018-10-01T00:00:00+00:00Z"], 
["discovery_start", "<", "2018-10-02T00:00:00+00:00Z"] ] } ] }

For columns that use the date and time values, you can retrieve data also for a period instead of a specific date. To do so, use last or next as <operator>, and then specify the time value in the following convention: PxD/PxW/PxM/PxY, where x is a number in the 1-999 range, and D, W, M, or Y is a designator that represents days, weeks, months, or years.

Example: Retrieve software instances that were first reported within the last 7 days

Example conversations

To review the suppressed windows packages, use the following API:
GET api/sam/raw_package_facts?columns[]=name&columns[]=
To review the suppressed UNIX packages, use the following API:
GET api/sam/raw_unix_package_facts?columns[]=name&columns[]=
To review the suppressed software instances, use the following API:
GET /api/sam/v2/software_instances?columns[]=component_name&columns[]
To view associated computer data, use the following API:
GET /api/sam/unified/current/software?columns[]=name&columns[]=release&columns[]