REST Approval

Single endpoint that provides details about existing approvals in the system.

For prompts to people who do not use Splunk SOAR (external prompts), see REST External prompts.

/rest/approval

List of all approvals.

Syntax 

https://<username>:<password>@<host>/rest/approval

GET

List of approvals.

Example request

Get a list of approvals. 

curl -k -u username:password https://localhost/rest/approval -G -X GET

Example response

A successful GET will return a 200 response, and a JSON formatted list of approvals. 

{
"count": 5,
"data": [
{
"status": "expired",
"owner_type": "User",
"action_run": 23,
"playbook_run": 60,
"escalated_approval": null,
"name": "prompt_1",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-07-16T23:22:39.149000Z",
"close_time": "2019-07-16T23:52:39.247000Z",
"id": 1,
"due_time": "2019-07-16T23:52:39.115000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 13,
"message": "pending-manual-action",
"type": "manual",
"display": true,
"responses": []
},
{
"status": "expired",
"owner_type": "User",
"action_run": 50,
"playbook_run": 66,
"escalated_approval": null,
"name": "task_1",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-07-29T23:28:43.149000Z",
"close_time": "2019-07-29T23:58:43.209000Z",
"id": 2,
"due_time": "2019-07-29T23:58:43.118000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-manual-action",
"type": "manual",
"display": true,
"responses": []
},
{
"status": "pending",
"owner_type": "Action Reviewer",
"action_run": 51,
"playbook_run": 67,
"escalated_approval": null,
"name": "approval for add tag",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-08-19T05:38:05.728000Z",
"close_time": null,
"id": 3,
"due_time": "2019-08-20T05:38:05.726000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-approval",
"type": "parameter",
"display": true,
"responses": []
},
{
"status": "pending",
"owner_type": "Action Reviewer",
"action_run": 52,
"playbook_run": 68,
"escalated_approval": null,
"name": "approval for add tag",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-08-19T05:38:58.723000Z",
"close_time": null,
"id": 4,
"due_time": "2019-08-20T05:38:58.721000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-approval",
"type": "parameter",
"display": true,
"responses": []
},
{
"status": "pending",
"owner_type": "Action Reviewer",
"action_run": 53,
"playbook_run": 69,
"escalated_approval": null,
"name": "approval for activate device",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-08-19T16:25:03.062000Z",
"close_time": null,
"id": 5,
"due_time": "2019-08-20T16:25:03.060000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-approval",
"type": "parameter",
"display": true,
"responses": []
}
],
"num_pages": 1
}

POST

Create approvals.

/rest/approval/<id>

Get the data of one approval.

Syntax 

https://<username>:<password>@<host>/rest/approval/<id>

GET

List the approval data from one approval ID.

Example request

Get a list of approvals. 

curl -k -u username:password https://localhost/rest/approval/1 -G -X GET

Example response

A successful GET will return a 200 response, and a JSON formatted list of data for one approval ID. 

{
	"status": "expired",
	"owner_type": "User",
	"action_run": 9,
	"playbook_run": 59,
	"escalated_approval": null,
	"name": "task_1",
	"parent": null,
	"node_guid": "9a8092d6-c3ad-4c61-b92a-005bb179cfc6",
	"start_time": "2020-01-22T19:39:43.239000Z",
	"close_time": "2020-01-22T20:09:43.295000Z",
	"id": 1,
	"due_time": "2020-01-22T20:09:43.221000Z",
	"version": 1,
	"jitc": {},
	"asset": null,
	"owner": 1,
	"message": "pending-manual-action",
	"type": "manual",
	"display": true,
	"responses": []
}

List the datapaths from one approval ID.

Example request

Get a JSON object containing the datapaths for the approval ID 

curl -k -u username:password https://localhost/rest/approval/?block_results=True -G -X GET

Add the block_results flag to the query to receive a JSON object containing the datapaths for the approval ID. For additional details, see /rest/playbook_run/<id>/block_results.

/rest/approval/<id>/detail_summary_view

List details of approvals for a particular container.

Syntax 

https://<username>:<password>@<host>/rest/approval/<id>/detail_summary_view

GET

List details of approvals for a container where 21 is the approval ID in the example request.

Example request

List details of approvals. 

curl -k -u username:password https://localhost/rest/approval/21/detail_summary_view -G -X GET

Example response

A successful GET for approvals notification type will return a 200 response, and a JSON formatted list of details. 

{
    "update_time": "2019-08-19T21:43:58.892936Z",
    "container_id": 291,
    "time_left": 80128.535132,
    "next_owner": null,
    "action_name": "user initiated post ip action",
    "due_time": "2019-08-20T20:05:57.814000Z",
    "asset": {
        "action_whitelist": {},
        "validation": {},
        "tenants": [],
        "description": "Default Asset Configuration for AbuseIPDB",
        "tags": [],
        "type": "reputation",
        "primary_voting": 0,
        "product_version": "",
        "effective_user": 2,
        "product_name": "AbuseIPDB",
        "disabled": false,
        "token": null,
        "version": 1,
        "secondary_voting": 0,
        "configuration": {
            "api_key": "r56jEhzRlV/TR9CWLzDgN0GtxWrYQskkOl5ypVGUCNu1KKfy5f9EA40TY2piQLKCL040OtANINfTtV3vWF5kmElSRfHpb275bkN7didzCPpgpLg0PincyjONjA7P+d4e"
        },
        "product_vendor": "AbuseIPDB",
        "id": 70,
        "name": "abuse_ip_db"
    },
    "action_type": "post ip",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "username",
    "notification_type": "approvals",
    "type": "asset",
    "notification_targets": [{
        "app_id": 152,
        "parameters": [{
            "comment": "ddd",
            "ip": "3.3.3.33",
            "categories": "dd"
        }],
        "assets": [
            70
        ]
    }]
}

Example response

A successful GET for prompts notification type will return a 200 response, and a JSON formatted list of details. 

{
    "playbook_repo": "local",
    "update_time": "2019-08-19T21:58:03.846035Z",
    "playbook_name": "pb-prompt",
    "container_id": 292,
    "time_left": 1758.571971,
    "next_owner": null,
    "action_name": "prompt_1",
    "due_time": "2019-08-19T22:28:03.817000Z",
    "asset": null,
    "action_type": "prompt",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "username",
    "notification_type": "prompts",
    "type": "manual",
    "notification_targets": [{
        "app_id": 0,
        "parameters": [{
            "to": "root@localhost",
            "message": "test",
            "mins_to_act": 30,
            "user_ids": [
                1
            ],
            "response_types": [{
                "prompt": "",
                "options": {
                    "type": "message"
                }
            }]
        }],
        "assets": []
    }]
}

Example response

A successful GET for manual tasks notification type will return a 200 response, and a JSON formatted list of details. 

{
    "update_time": "2019-08-19T22:04:59.289861Z",
    "container_id": 293,
    "time_left": 3383.812224,
    "next_owner": null,
    "action_name": "user initiated task-18172",
    "due_time": "2019-08-19T23:04:59.240000Z",
    "asset": null,
    "action_type": "task",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "username",
    "notification_type": "manual tasks",
    "type": "manual",
    "notification_targets": []
}

Example response

A successful GET for action reviewers notification type will return a 200 response, and a JSON formatted list of details. 

{
    "playbook_repo": "local",
    "update_time": "2019-08-19T22:14:06.436276Z",
    "playbook_name": "pb-reviewer",
    "container_id": 294,
    "time_left": 78412.135004,
    "next_owner": null,
    "action_name": "geolocate_ip_1",
    "due_time": "2019-08-20T20:05:58.356000Z",
    "asset": null,
    "action_type": "geolocate ip",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "username",
    "notification_type": "action reviews",
    "type": "parameter",
    "notification_targets": [{
        "app_id": 124,
        "parameters": [{
            "ip": "2.3.2.22"
        }],
        "assets": [
            2
        ]
    }]
}

The return values of note follow:

Field Type Description
asset JSON Object Can be empty depending on the notification type and if it contains an asset. See REST Assets for further information about assets.
container_id String The container Id of the playbook action run.
due_time String Time (UTC) when this action is due ( time at which the SLA expires/expired ).
next_owner String The next owner for an approval, such as soar_local_admin.
notification_targets JSON Object JSON object containing a variety of parameters entered in response to prompt.
notification_type String prompts, approvals, manual tasks, action reviews.
owner String The current owner's display name, such as username.
playbook_name String The playbook name.
playbook_repo String The name of the the playbook repository.
prompt String The options available to respond to a prompt such as:
  • list: a list of pre-selected strings
  • message: a user-inputted string
  • range: a number in the range specified by the prompt response

It returns a dictionary that organizes the response answer percentage by response.

time_left String The due time minus the current time, in seconds.
type String Mapping for prettifying notification types, such as:
  • prompt -> prompts
  • asset -> approvals
  • task -> manual tasks
  • parameter -> action reviews

The response varies depending on the notification type, which is a sub-type of approvals. The output is similar to /rest/notification/<id>/detail_summary_view used for mobile. See REST Notification.