TABLE OF CONTENTS
- Explanation
- Requirements
- List of API methods
- 1. Getting Started with PowerShell
- 2. Validating with platform defaults
- 3. Validating with custom ports
- 4. Batch validation
- 5. ConnectivityValidationResponse Example
- Platform Values
- Protocol Values
- CheckType Values
Explanation
This API allows you to validate network connectivity between the five(9s) Console server and a target device. It performs a series of checks — DNS resolution, ICMP ping, TCP/UDP port tests, and Ivanti agent validation — and returns a detailed result for each check.
Connectivity validation requests are processed synchronously and return immediately with the full result set.
Requirements
You will need to create/edit a Personal Access Token in the five(9s) Console and grant it access to the "/api/connectivity/" right.
This API is available with Console Version 5.3.24 and later.
A PowerShell script or any other tool that can make REST API calls can be used.
Configuration
The default Timout can be changed via setting "PingTimeout" and the default ports for the validation can be edited under Admin - General Settings - API Settings - Connectivity API.
List of API methods
| Name | Description | Request Parameters | Response |
|---|---|---|---|
| ValidateConnectivity | Perform a full connectivity check against a target hostname or IP address | Hostname (string, required) Hostname or IP address of the target device Platform (int?, optional) Target OS platform — selects the default port list when CustomPorts is not provided (0=Windows, 1=Linux, 2=Mac). Defaults to Windows. CustomPorts (int[], optional) Explicit list of port numbers to check. When provided, overrides the platform default port list. Maximum 50 ports. Protocol (string, optional) Protocol to use for custom port checks: "TCP", "UDP", or "TCP/UDP" for both. Defaults to TCP when null or empty. Ignored when CustomPorts is not provided. TimeoutInMs (int, optional) overrides the default timeout for validating the ports. | ConnectivityValidationResponse (see example below) |
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/connectivity";
$personalAccessToken = "ABC123456789DEF123456789XYZ123456789"; # needs to have access to this api
$headers = @{
"Authorization" = "PAT $personalAccessToken"
"Content-Type" = "application/json"
}2. Validating with platform defaults
Validate connectivity to a device using the platform's default port list:
# Validate a Windows device using default ports
$body = @{
Hostname = "my-windows-server"
Platform = 0 # 0=Windows, 1=Linux, 2=Mac
} | ConvertTo-Json -Depth 100
$response = Invoke-RestMethod -Uri "$($baseUri)/Validate" -Method Post -Headers $headers -Body $body
Write-Host "Hostname : $($response.Hostname)"
Write-Host "Overall : $($response.OverallSuccess)"
$response.Results | Format-Table TestName, CheckType, Success, Details -AutoSize3. Validating with custom ports
Override the default port list and specify which ports and protocol to test:
# Custom TCP ports
$body = @{
Hostname = "my-linux-server"
CustomPorts = @(22, 9593, 9595)
Protocol = "TCP"
} | ConvertTo-Json -Depth 100
$response = Invoke-RestMethod -Uri "$($baseUri)/Validate" -Method Post -Headers $headers -Body $body
$response.Results | Format-Table TestName, CheckType, Success, Details -AutoSize
# Custom ports checked on both TCP and UDP
$body = @{
Hostname = "my-server"
CustomPorts = @(135, 445, 9595)
Protocol = "TCP/UDP"
} | ConvertTo-Json -Depth 100
$response = Invoke-RestMethod -Uri "$($baseUri)/Validate" -Method Post -Headers $headers -Body $body
$response.Results | Format-Table TestName, CheckType, Success, Details -AutoSize4. Batch validation
Loop through a list of hostnames, collect all results and export to CSV:
$hostnames = @("server-01", "server-02", "server-03")
$allResults = @()
foreach ($hostname in $hostnames) {
Write-Host "Validating $hostname..."
$body = @{
Hostname = $hostname
Platform = 0
} | ConvertTo-Json -Depth 100
$response = Invoke-RestMethod -Uri "$($baseUri)/Validate" -Method Post -Headers $headers -Body $body
foreach ($result in $response.Results) {
$allResults += [PSCustomObject]@{
Hostname = $response.Hostname
OverallSuccess = $response.OverallSuccess
TestName = $result.TestName
CheckType = $result.CheckType
Success = $result.Success
Details = $result.Details
}
}
}
Write-Host "`nTotal check results: $($allResults.Count)"
$allResults | Export-Csv -Path "connectivity-results.csv" -NoTypeInformation
# Show only failed checks
$failed = $allResults | Where-Object { -not $_.Success }
Write-Host "`nFailed checks: $($failed.Count)"
$failed | Format-Table Hostname, TestName, CheckType, Details -AutoSize5. ConnectivityValidationResponse Example
The response includes an overall result and a per-check breakdown:
{
"Hostname": "my-windows-server",
"OverallSuccess": false,
"Results": [
{
"TestName": "DNS Resolution",
"CheckType": 1,
"Success": true,
"Details": "Resolved to 192.168.1.50."
},
{
"TestName": "ICMP Ping",
"CheckType": 0,
"Success": true,
"Details": "Round-trip time: 2 ms."
},
{
"TestName": "Port 135 TCP",
"CheckType": 2,
"Success": true,
"Details": "Port is open."
},
{
"TestName": "Port 445 TCP",
"CheckType": 2,
"Success": false,
"Details": "Connection timed out."
},
{
"TestName": "Port 9595 UDP",
"CheckType": 3,
"Success": false,
"Details": "Unable to verify port status (no rejection received within timeout)"
},
{
"TestName": "Agent Validation (ldping)",
"CheckType": 4,
"Success": false,
"Details": "Agent did not return a valid response."
}
]
}Platform Values
The Platform parameter selects the default port list when CustomPorts is not provided:
| Value | Platform | Description |
|---|---|---|
| 0 | Windows | Default. Uses the Windows default port list configured in Console settings. |
| 1 | Linux | Uses the Linux default port list configured in Console settings. |
| 2 | Mac | Uses the Mac default port list configured in Console settings. |
Protocol Values
The Protocol parameter controls which transport protocol is used when CustomPorts is provided:
| Value | Description |
|---|---|
| null / empty | Defaults to TCP only. |
| "TCP" | Test each custom port over TCP only. |
| "UDP" | Test each custom port over UDP only. |
| "TCP/UDP" | Test each custom port over both TCP and UDP (creates two checks per port). |
CheckType Values
The CheckType field on each result indicates what kind of check was performed:
| Value | CheckType | Description |
|---|---|---|
| 0 | IcmpPing | ICMP echo request (ping) to measure reachability and round-trip time. |
| 1 | Dns | DNS hostname resolution. Failure here does not block subsequent checks if an IP is provided directly. |
| 2 | TcpPort | TCP connection attempt to the specified port with a 3-second timeout. |
| 3 | UdpPort | UDP probe to the specified port. A missing ICMP unreachable response within the timeout is treated as open/filtered. |
| 4 | AgentValidation | Ivanti agent ldping check to verify the agent is running and reachable on port 9595. |
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article