Device API

Modified on Tue, 9 Sep at 1:44 PM

TABLE OF CONTENTS

Explanation
Requirements
List of API methods
1. Getting Started with PowerShell
2. Requesting device information
3. Query the job status
4. Getting the result of the job
5. JobData Example
Security Info Status Values

Explanation

This API allows you to request information related to devices. Since gathering this data can take some time, the process is divided into three steps:

Start a Request – You submit a request for the information you need.
Check the Status – You check if the processing is finished.
Get the Result – Once it's ready, you can retrieve the result.

Requirements

You will need to create/edit an Personal Access Token in the five(9s) Console and grant it access to the "/api/devices/" right.
This API is available with Console Version 5.1.27 and later.

A PowerShell script or any other tool that can make REST API calls can be used.

List of API methods

Name	Description	Request Parameters	Response
RequestEpmInventory	Device information gathered by the EPM agent	SerialNumbers or Hostnames or Computer_Idns (int List) or none (to request all devices) LastSyncDate (to fetch only data that has been changed since the given date)	JobId (Guid)
RequestCustomInventory	Custom Inventory information managed by the five(9) Console
RequestSecurityInfo	Infos about detected Vulnerabilities
RequestDatabaseViews	Custom database views/tables (configured on the admin site)
RequestAllInfos	All of the above
GetJobStatus	Retrieving job status	Guid (the job id)	Status StatusDetails
GetJobData	Fetching job results	Guid (the job id) Page (int, default 1) PageSize (int, default 100)	see 5. JobData Example

1. Getting Started with PowerShell

Here we define some variables that will be used for all the following code snippets.

cls;
$ErrorActionPreference = "Stop"

# General
$baseUri = "http://<yourEpmHostname>/five9sWS/api/devices";
$personalAccessToken = "ABC123456789DEF123456789XYZ123456789"; // needs to have access to this api
$headers = @{
    "Authorization" = "PAT $personalAccessToken"
    "Content-Type"  = "application/json"
}
enum JobStatus {
    Pending   = 1
    Running   = 2
    Success   = 3
    Failure   = 4
}

2. Requesting device information

# Example request
$body = @{
    Hostnames = @("Win10-Test2", "Windows7-DN54")
    LastSyncDate = [DateTime]::UtcNow.AddDays(-7)
} | ConvertTo-Json -Depth 100
$response = Invoke-RestMethod -Uri "$($baseUri)/RequestAllInfos" -Method Post -Headers $headers -Body $body
$jobId = $response.JobId
Write-Host $response

3. Query the job status

$body = @{
    Guid = "$jobId"
} | ConvertTo-Json
Write-Host $body
Start-Sleep -Seconds 30 # we need to wait, the job can be a long running operation
$jobStatusResponse = Invoke-RestMethod -Uri "$($baseUri)/GetJobStatus" -Method Post -Headers $headers -Body $body -ErrorAction Stop
$jobStatusResponse | ConvertTo-Json -Depth 100
Write-Host $jobStatusResponse
if ($jobStatusResponse.Status -eq [JobStatus]::Running) {
    Write-Host "Job is still running..."
} elseif ($jobStatusResponse.Status -eq [JobStatus]::Success) {
    Write-Host "Job completed successfully."
    $jobCompleted = $true
} elseif ($jobStatusResponse.Status -eq [JobStatus]::Failure) {
    Write-Host "Job failed."
} else {
    Write-Host "Job status is unexpected."
}

4. Getting the result of the job

# Get job result only if completed successfully
if ($jobCompleted) {
    $body = @{Guid = "$jobId"} | ConvertTo-Json
    $jobResult = Invoke-RestMethod -Uri "$($baseUri)/GetJobData" -Method Post -Headers $headers -Body $body
    $jobResult | ConvertTo-Json -Depth 100
    Write-Host $jobResult
} else {
    Write-Host "Job did not complete successfully. Results will not be retrieved."
}

5. JobData Example

Some sections of data contain an last change date (e.g. Custom Inventory "UpdatedAt"column. If you provide a LastSyncDate parameter we omit devices that have do have any recent data

{
  "ReturnedCount": 1,
  "TotalCount": 1,
  "Results": [
    {
      "Computer_Idn": 10,
      "SerialNumber": "VMware-56 4d 78 db e0 23 67 d9-8b 85 07 b3 ba d9 4a 1f",
      "DeviceId": "{A98F1370-E8FF-406B-A464-76AD9D937D05}",
      "DeviceName": "WIN10-TEST2",
      "DisplayName": "WIN10-TEST2",
      "CustomInventory": {
        "Device Type": "Notebook (Laptop)",
        "End of Life": "2025-03-19",
        "Extended Warranty": "True",
        "Planned Win11 Update": "2025-06-12",
        "Tag ID #": "UnitTest - Tag ID #",
        "Location": "Berlin",
        "PatchGroup": "Sharepoint Servers",
        "PatchStep": "Test Labor",
        "PatchStepFastTrack": "",
        "User to notify": "",
        "UpdatedAt": "2025-08-01T10:00:24.6830000Z"
      },
      "EpmInventory": {
        "Computer_Idn": 10,
        "DeviceName": "WIN10-TEST2",
        "Type": "Virtual Workstation",
        "Description": null,
        "LoginName": "ADMINISTRATOR",
        "HWLastScanDate": "2025-08-06T15:13:34",
        "SWLastScanDate": "2025-08-06T15:14:20",
        "UpdateLastScanDate": "2025-08-06T15:19:59.72",
        "PatchSWLastScanDate": null,
        "LastUpdInvSvr": "2025-08-06T15:15:42",
        "LastStartUpTime": "2025-08-04T08:22:51",
        "ComputerLocation": "59s16.local/Computers",
        "LDAPLocation": "CN=WIN10-TEST2,CN=Computers,DC=59s16,DC=local",
        "RecordDate": "2019-02-09T22:28:57.98",
        "DaysHardware": null,
        "DaysVulnerabil": null,
        "DaysStartUp": null,
        "SerialNum": "VMware-56 4d 78 db e0 23 67 d9-8b 85 07 b3 ba d9 4a 1f",
        "Model": "VMware Virtual Platform",
        "Manufacturer": "VMware, Inc.",
        "ChassisType": "Other",
        "OsType": "Microsoft Windows 10 Enterprise Edition, 64-bit",
        "ReleaseID": "2009",
        "Scopes": [
          {
            "Scope_Idn": 1230,
            "ScopeName": "All Win Devices"
          },
          {
            "Scope_Idn": 1290,
            "ScopeName": "EMS - Sharepoint Servers - Autofix"
          }
        ]
      },
      "SecurityInfo": [
        {
          "Vulnerability_Idn": 10,
          "Vul_ID": "LDMS1100.RC.1",
          "Status": 4,
          "StatusText": "Autofix",
          "FirstDetectionDate": "2019-07-04T15:32:08.783"
        },
        {
          "Vulnerability_Idn": 18628,
          "Vul_ID": "TB18-5291_INTL",
          "Status": 4,
          "StatusText": "Autofix",
          "FirstDetectionDate": "2023-02-24T13:15:14.123"
        }
      ],
      "DatabaseViews": {}
    }
  ],
  "DevicesNotFound": [
    "Windows7-DN54"
  ]
}

Security Info Status Values

public enum DeviceSecurityInfoStatus
{
    Excluded = 1,
    Planned = 2,
    Pending = 3,
    Autofix = 4,
    InstallFailure = 5,
    InstallSuccess = 6,
}