Watchlist Integration
The Watchlist Integration APIs are broken down into the following sections:
Refer to Example Usage for Watchlist Integration examples.
Read APIs
These GET APIs are available to retrieve watch lists from the FortiSIEM database.
Get All Watch Lists
This API retrieves all the watch lists from FSIEM database.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/all |
Output
Response Status |
Response |
---|---|
Success |
{ "response": [{ "topGroup": false, "entries": [ { "lastSeen": 1613719690008, "naturalId": "PVVol_A001_A000356_POWER2_1613719690011", "dataCreationType": "SYSTEM", "firstSeen": 1613719690008, "count": 10, “custId”: 1, "triggeringRules": "Datastore Space Warning", "description": "WL Des", "id": 889401, "state": "Enabled", "entryValue": "PVVol_A001_A000356_POWER2", "expiredTime": 0, "ageOut": "1d" }, { "lastSeen": 1613719690000, "naturalId": "PVVol_A001_A000356_POWER2_1613719690011", "dataCreationType": "SYSTEM", "firstSeen": 1613719000000, "count": 100, "triggeringRules": "Datastore Space Warning", "description": "WL Des Testing again", "id": 889402, “custId”: 1, "state": "Disabled", "entryValue": "PVVol_A001_A000356_POWER2", "expiredTime": 0, "ageOut": "10d" } ], "isCaseSensitive": null, "dataCreationType": null, "displayName": "", "valueType": “STRING”, "description": null, "id": 0, “custId”: 1, "valuePattern": null, "ageOut": null }, { "topGroup": true, "entries": null, "isCaseSensitive": false, "dataCreationType": "USER", "displayName": "Test WL Group2", "valueType": “STRING”, "description": "Testing", "id": 897300, "valuePattern": null, "ageOut": "1w" } ], "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Get Watch List Entries Count
This API gives the count of watch list entries in any watch list group.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/cnt |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "entry_count": 6 }, "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Get Watch List by Watch List ID
This API retrieves a specific watch list with given watch list ID.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/<watch_list_id> |
Request Path Parameter
Field |
Description |
---|---|
Replace <watch_list_id> with numeric value. | Watch list id of a specific watch list. |
Output
Response Status |
Response |
---|---|
Success |
{ "response": [ { "topGroup": true, "entries": [ { "lastSeen": null, "naturalId": "172.30.57.65_1616469746578", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": null, "description": "Testing", "id": 888900, “custId”: 1, "state": "Enabled", "entryValue": "172.30.57.65", "expiredTime": null, "ageOut": "1w" }, { "lastSeen": null, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, “custId”: 1, "state": "Enabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": null, "ageOut": "1d" } ], "isCaseSensitive": false, "dataCreationType": "USER", "displayName": "Test WL Group", "valueType": “STRING”, "description": "", "id": 881750, “custId”: 1, "valuePattern": null, "ageOut": "1w" } ], "status": "Success" } |
Failure Ex: If ID contains non-numeric values (invalid data) Status Code – 404 Not Found |
{ "response": "DyWatchList@<watch_list_id> was not found", "status": "Failed" } |
Failure Ex: If no match, Status Code – 200 |
{ "response": "DyWatchList@<watch_list_id> was not found", "status": "Failed" } |
Get Watch List by Watch List Entry Value
This API retrieves watch lists which contains a watch list entry with given entry value.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/value |
Request Parameters
Field |
Type |
Description |
---|---|---|
entryValue |
String |
Entry value of watch list entry. |
Output
Response Status |
Response |
---|---|
Success |
{ "response": [ { "topGroup": true, "entries": [ { "lastSeen": null, "naturalId": "172.30.57.65_1616469746578", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": null, "description": "Testing", "id": 888900, "state": "Enabled", "entryValue": "172.30.57.65", "expiredTime": null, "ageOut": "1w" }, { "lastSeen": null, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Enabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": null, "ageOut": "1d" } ], "isCaseSensitive": false, "dataCreationType": "USER", "displayName": "Test WL Group", "valueType": “STRING”, "description": "", "id": 881750, "valuePattern": null, "ageOut": "1w" } ], "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If no match, Status Code – 200 |
{ "response": "No such Watch List with entry value: <entryValue> and watch list name: <watchlistName>", "status": "Failed" } |
Get Watch List by Watch List Entry ID
This API retrieves a specific watch list which contains a watch list entry with given entry ID.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/byEntry/<watch_list_entry_id> |
Request Path Parameters
Field |
Type |
Description |
---|---|---|
Replace <watch_list_entry_id> with specific watch list entry id |
Long |
Watch list entry id |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "topGroup": true, "entries": [ { "lastSeen": null, "naturalId": "172.30.57.65_1616469746578", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": null, "description": "Testing", "id": 888900, "state": "Enabled", "entryValue": "172.30.57.65", "expiredTime": null, "ageOut": "1w" }, { "lastSeen": null, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Enabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": null, "ageOut": "1d" } ], "isCaseSensitive": false, "dataCreationType": "USER", "displayName": "Test WL Group", "valueType": "STRING", "description": "", "id": 881750, "valuePattern": null, "ageOut": "1w" }, "status": "Success" } |
Failure Ex: If ID contains non-numeric values (invalid data) Status Code – 404 Not Found |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If no match, Status Code – 200 |
{ "response": " No such watch list exists", "status": "Failed" } |
Get Watch List Entry by Watch List Entry ID
This API retrieves a specific watch list entry given entry ID.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/<watch_list_entry_id> |
Request Path Parameters
Field |
Type |
Description |
---|---|---|
Replace <watch_list_entry_id> with specific watch list entry id. | Long | Watch list entry id |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": null, "naturalId": "172.30.57.65_1616469746578", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": null, "description": "Testing", "id": 888900, "state": "Enabled", "entryValue": "172.30.57.65", "expiredTime": null, "ageOut": "1w" }, "status": "Success" } |
Failure Ex: If ID contains non-numeric values (invalid data) Status Code – 404 Not Found |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If no match, Status Code – 200 |
{ "response": " No such watch list entry exists", "status": "Failed" } |
Update APIs
These POST APIs are available to update watch lists from the FortiSIEM database.
-
Update Last Seen Time of Watch List Entry by Watch List Entry ID
-
Update Last Seen Time of Watch List Entry by Watch List Entry Value
Update State of Watch List Entry by Watch List Entry ID
This API allows user to update watch list entry state (i.e., make it active/inactive).
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/active/<watch_list_entry_id> |
Request Path Parameters
Field |
Type |
Description |
---|---|---|
Replace <watch_list _entry_id> with specific watch list entry id | Long | Watch list entry id |
Request Parameters
Field |
Type |
Description |
---|---|---|
state | Boolean | Set specific entry to true/false state. |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": null, "naturalId": "172.30.57.65_1616469746578", "dataCreationType": null, "firstSeen": null, "count": null, "triggeringRules": null, "description": "Testing", "id": 888900, "state": "Disabled", "entryValue": "172.30.57.65", "expiredTime": null, "ageOut": "1w" }, "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex – If no match, status code - 200 |
{ "response": "Can't update state of watch list entry - No such watch list entry exists", "status": "Failed" } |
Update State of Watch List Entry by Watch List Entry Value
This API allows user to update the watch list entry state (i.e., make it active/inactive). This API requires a watch list group name where a required watch list entry exists.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/active |
Request Parameters
Field |
Type |
Description |
---|---|---|
watchlistId | Long | Watchlist ID |
value |
String |
Entry value of watch list entry |
state |
Boolean |
Set specific entry to true/false state |
custId |
Long |
Customer ID |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": null, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": 10, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Disabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": null, "ageOut": "1d" }, "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex – If no match, status code - 200 |
{ "response": "Can't update state of watch list entry - No such watch list entry exists", "status": "Failed" } |
Update Last Seen Time of Watch List Entry by Watch List Entry ID
This API allows user to update watch list entry’s last seen time.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/lastseen/<watch_list_entry_id> |
Request Path Parameters
Field |
Type |
Description |
---|---|---|
Replace <watch_list_ entry _id> with specific watch list entry id | Long | Watch list entry id |
Request Parameters
Field |
Type |
Description |
---|---|---|
lastSeenTime | Long | Long value of last seen time i.e. Unix timestamp |
custId |
Long |
Customer ID |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": 1612901760000, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": 10, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Disabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": 1612988160000, "ageOut": "1d" }, "status": "Success" } |
Failure Ex: If ID contains non-numeric values (invalid data) Status Code – 404 Not Found |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex – If no match, status code - 200 |
{ "response": "Can't update last seen time of watch list entry - No such watch list entry exists", "status": "Failed" } |
Update Last Seen Time of Watch List Entry by Watch List Entry Value
This API allows the user to update watch list entry’s last seen time. This API requires a watch list group name where the required watch list entry exists.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/lastseen |
Request Parameters
Field |
Type |
Description |
---|---|---|
watchlistId |
Long |
Watchlist ID |
value |
String |
Entry value of watch list entry |
lastSeenTime | Long | Long value of last seen time i.e. Unix timestamp |
custId |
Long |
Customer ID |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": 1612901760001, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": 10, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Disabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": 1612988160001, "ageOut": "1d" }, "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex – If no match, status code - 200 |
{ "response": "Can't update last seen time of watch list entry - No such watch list entry exists", "status": "Failed" } |
Update Count of Watch List Entry by Watch List Entry ID
This API allows user to update watch list entry’s count.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/count/<watch_list_entry_id> |
Request Path Parameters
Field |
Type |
Description |
---|---|---|
Replace <watch_list_ entry _id> with specific watch list entry id |
Long |
Watch list entry id |
Request Parameters
Field |
Type |
Description |
---|---|---|
count |
Long |
Count of watch list entry occurrence |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": 1612901760001, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": 100, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Disabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": 1612988160001, "ageOut": "1d" }, "status": "Success" } |
Failure Ex: If ID contains non-numeric values (invalid data) Status Code – 404 Not Found |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex – If no match, status code - 200 |
{ "response": "Can't update count of watch list entry - No such watch list entry exists", "status": "Failed" } |
Update Count of Watch List Entry by Watch List Entry Value
This API allows user to update watch list entry’s count. This API requires watch list group name where required watch list entry exists.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/count |
Request Parameters
Field |
Type |
Description |
---|---|---|
custId |
Long |
Customer ID |
watchlistId |
Long |
Watchlist ID |
value |
String |
Entry value of watch list entry |
count |
Long |
Count of watch list entry occurrence |
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": 1612901760001, "naturalId": "PVVol_A001_A000356_POWER23_1616480669538", "dataCreationType": null, "firstSeen": null, "count": 100, "triggeringRules": "Datastore Space Warning", "description": null, "id": 889400, "state": "Disabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": 1612988160001, "ageOut": "1d" }, "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex – If no match, status code - 200 |
{ "response": "Can't update count of watch list entry - No such watch list entry exists", "status": "Failed" } |
Add Watch List Entry(s) to Watch List Groups
This API allows user to add watch list entry(s) to one or more watch list groups.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/addTo |
Request Parameters
Field |
Type |
Description |
---|---|---|
watchlistId |
Long |
Watchlist ID |
Request Body
Field |
Type |
Description |
---|---|---|
Body | JSON Array of Watch list entry objects | Watch Entry |
entryValue(required) | String | Watch List entry value |
[ { "inclusive": false, "count": 10, "custId": 1, "triggeringRules": "Datastore Space Warning", "entryValue": "PVVol_A001_A000356_POWER2", "ageOut": "1d", "lastSeen": 1613601369215, "firstSeen": 1613601369215, "disableAgeout": false, "dataCreationType": "USER" } ] |
Output
Response Status |
Response |
---|---|
Success |
{ "response": "Successfully added to watch list - [IDs]", "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: Invalid data format in request parameters Status code - 200 |
{ "response": " Error while adding entries to watch lists - Invalid data format", "status": "Failed" } |
Failure Ex: If no entry value exists in Watchlist Entry Status code - 200 |
{ "response": “Error while adding entries to watch lists - WatchListEntry must have entryValue field", "status": "Failed" } |
Save Watch List Groups with Watch List Entry(s)
This API allows user to save one or more watch list groups to FSM database. Each watch list can contain one or more watch list entries.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/save |
Request Body
Field |
Type |
Description |
---|---|---|
Body | JSON Object of Watch list with watch list entry | Watch list with entry(s) |
displayName (required) | String | Display name for watch list group |
type (required) | String | Group type - ENUM |
entryValue (required) |
String |
Entry value of DyWatchlistEntry |
dataCreationType |
String |
Enum – {SYSTEM, USER} If value is null – Default value will be ‘SYSTEM’ |
|
|
|
{ "description": "Servers, network or storage devices", "displayName": "Resource Issues Test4","type": "DyWatchList", "isCaseSensitive": false, "dataCreationType": "USER", "topGroup": false, "valuePattern": null, "valueType": "STRING", "ageOut": "1d", "custId": 1, "entries": [{ "inclusive": true, "entryValue": "PVVol_A001_A000356_5new", "ageOut": "1d", "count": 1, "custId": 1, "firstSeen": 1612901760000, "lastSeen": 1612901760000, "triggeringRules": "Datastore Space Warning", "dataCreationType": "USER" }] } |
Output
Response Status |
Response |
---|---|
Success |
{ "response": [ { "topGroup": false, "entries": [ { "lastSeen": 1612901760000, "naturalId": "Nid", "dataCreationType": "USER", "firstSeen": 1612901760000, "count": 1, "triggeringRules": "Datastore Space Warning", "description": null, "id": 0, "state": "Enabled", "entryValue": null, "expiredTime": null, "ageOut": "1d" } ], "isCaseSensitive": null, "dataCreationType": "SYSTEM", "displayName": "Resource Issues Test WL Grp4", "valueType": "STRING", "description": "Servers, network or storage devices", "id": 899753, "valuePattern": null, "ageOut": null } ], "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If entry doesn’t have entry value Response code - 200 |
{ "response" : "Error while saving watch lists - WatchListEntry must have entryValue field", "status" : "Failed" } |
Failure Ex:
Response code - 200 |
{ "response": "Failed to save watchlist", "status": "Failed" } |
Update Specific Watch List Entry
This API allows user to update any watch list entry. The JSON object of watch list entry must contain valid watch list entry id otherwise it will be saved as a new entry to ungrouped watch list.
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/save |
Request Body
Field |
Type |
Description |
---|---|---|
Body | JSON Object of Watch list with watch list entry | Watch list entry |
entryValue(required) | String | Watch list entry value |
|
|
|
{ "lastSeen": 1612901760002, "dataCreationType": "USER", "firstSeen": 1612901760001, "count": 100, "custId": 1 "triggeringRules": "Datastore Space Warning", "description": "Testing again", "id": 889400, "inclusive": true, "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": 1612988160001, "ageOut": "2d", } |
Note: ID is mandatory to update watch list entry. If there is no id in JSON body, a new entry will be created.
Output
Response Status |
Response |
---|---|
Success |
{ "response": { "lastSeen": 1612901760002, "naturalId": "PVVol_A001_A000356_POWER23_1612901760002", "dataCreationType": "USER", "firstSeen": 1612901760001, "count": 100, "triggeringRules": "Datastore Space Warning", "description": "Testing again", "id": 889400, "state": "Enabled", "entryValue": "PVVol_A001_A000356_POWER23", "expiredTime": 1613074560002, "ageOut": "2d" }, "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If entry doesn’t have entry value Response code - 200 |
{ "response": "HTTP 400 Bad Request", "status": "Failed" } |
Delete APIs
The following POST Delete APIs are available.
Delete Watch List Entry by ID
This API allows user to delete watch list entry(s).
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/delete |
Request Body
Field |
Type |
Description |
---|---|---|
List of Long values | Watch List Entry ids | |
Ex: [500000, 500001] |
Output
Response Status |
Response |
---|---|
Success |
{ "response": "Deleted entries - [IDs]", "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If any exception occurs |
{ "response": " Error in deleting watch list entries – Exception message ", "status": "Failed" } |
Delete Watch List by ID
This API allows user to delete watch list(s).
Input URL | https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/delete |
Request Body
Field |
Type |
Description |
---|---|---|
List of Long values | Watch list ids | |
Ex: [500000, 500001] |
Output
Response Status |
Response |
---|---|
Success |
{ "response": "Deleted watch lists - [IDs]", "status": "Success" } |
Failure |
{ "response": "Reason for failure", "status": "Failed" } |
Failure Ex: If group is system defined group |
{ "response": "Deleting system defined group is not allowed", "status": "Failed" } |
Failure Ex: If any exception occurs |
{ "response": " Error in deleting watch lists – Exception message ", "status": "Failed" } |
JSON Object Formats
Watch List Entry JSON
Field |
Type |
Description |
---|---|---|
id | Long | Watch list entry id |
firstSeen | Long | First seen time – Unix format |
lastSeen | Long | Last seen time – Unix format |
expiredTime | Long | Expiry time – Unix format |
state | String | State of entry – Enabled/Disabled |
naturalId | String | Unique ID of watch list entry |
triggeringRules | String | FSM Rules – Comma separated |
entryValue | String | Entry value of Watch list entry |
description |
String |
Description |
ageOut |
String |
Age out (Expiry) |
count |
Long |
Occurrence count |
dataCreationType |
ENUM |
[SYSTEM, USER] |
Watch List JSON
Field |
Type |
Description |
---|---|---|
id | Long | Watch list group id |
naturalId | String | Unique ID of watch list |
isCaseSensitive | Boolean | |
ageOut | String | Age out (Expiry) |
entries | List<WatchListEntry> | List of Entries Refer to Watch List Entry JSON Table. |
displayName | String | Display name of watch list group |
name | String | Name of the watch list |
description | String | Entry value of Watch list description |
valueType |
ENUM |
Value type - STRING, IP, etc... |
topGroup |
Boolean |
True/false |
dataCreationType |
ENUM |
[SYSTEM, USER] |
valuePattern |
ENUM |
[IP, IPRANGE, CIDR] |