The AWA Inbox Actions API provides endpoints to accept or reject a work item on behalf of an agent. This API also retrieves reject reasons for rejected work items.

This API requires the Advanced Work Assignment (com.glide.awa) plugin and awa_integration_user role. For more information, refer to Advanced Work Assignment.

AWA Inbox Actions – GET /awa/inbox/actions/reject_reasons/{channel_id}

Gets the work item reject reasons for a specified service channel.

URL format

Versioned URL: /api/now/awa/inbox/actions/reject_reasons/{channel_id}

Default URL: /api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
channel_id Sys_id of a service channel.

Data type: String

Table: Service Channels [awa_service_channel]
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example

The following example shows how to retrieve reject reasons for the Chat service channel.

curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Response body displaying rejected tasks with reasons for rejection.

{
  "result": [
    {
      "order": 2,
      "value": "Not my expertise",
      "display_value": "Not my expertise",
      "sys_id": "31e3fa29b38023002e7b6e5f26a8dc17"
    },
    {
      "order": 1,
      "value": "Busy",
      "display_value": "Busy",
      "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
    }
  ]
}

AWA Inbox Actions – POST /awa/inbox/actions/accept

Accepts a work item in Pending Accept state on behalf of an agent.

URL format

Versioned URL: /api/now/{api_version}/awa/inbox/actions/accept

Default URL: /api/now/awa/inbox/actions/accept

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 7. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 8. Query parameters
Name Description
None
Table 9. Request body parameters (XML or JSON)
Name Description
agent_id Sys_id of the agent listed.

Data type: String

Table: User [sys_user]
work_item_id Sys_id of the work item.
The work item must meet the following criteria:
  • Work item must be assigned to the specified agent.
  • Work item must be in Pending Accept state.

Data type: String

Table: AWA Work Item [awa_work_item]

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 11. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 12. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
400 Invalid request.
Possible reasons:
  • Missing agent ID.
  • Missing work item ID.
  • Work item is assigned to a different agent.
  • Work item isn't in pending accept state.
401 Unauthorized. The user credentials are incorrect or have not been passed.
403 Forbidden.
Possible reasons:
  • The user doesn't have the awa_integration_user role.
  • The value of the glide.awa.enabled property isn't true. This property is listed in the System Property [sys_property] table if the Advanced Work Assignment (com.glide.awa) plugin is installed. For more information, see Components installed with Advanced Work Assignment.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Example: cURL request

The following example shows how to change the state of a selected agent's work item from Pending Accept to Accepted.

curl "https://instance.service-now.com/api/now/awa/inbox/actions/accept" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
 \"work_item_id\":\"fd69abfc878b01101ae365b83cbb35fe\"
}" \
--user 'username':'password'

The response body lists the sys_id and table of the document related to the work item.

{
  "result": {
    "documentSysId": "57af7aec73d423002728660c4cf6a71c",
    "documentTable": "incident"
  }
}

AWA Inbox Actions – POST /awa/inbox/actions/reject

Rejects a work item in Pending Accept state on behalf of an agent. On success, Assigned to field is empty and the value of the Rejected field is true for the specified work item.

URL format

Versioned URL: /api/now/{api_version}/awa/inbox/actions/reject

Default URL: /api/now/awa/inbox/actions/reject

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 13. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
Name Description
agent_id Sys_id of the agent listed.

Data type: String

Table: User [sys_user]
reject_reason_id Sys_id of a rejection reason for this service channel.

Data type: String

Table: Reject Reasons [awa_reject_reason]
work_item_id Sys_id of the work item.
The work item must meet the following criteria:
  • Work item must be assigned to the specified agent.
  • Work item must be in Pending Accept state.

Data type: String

Table: AWA Work Item [awa_work_item]

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 16. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 17. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example

The following example shows how to reject an assigned work item with the "not my expertise" reason.

curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
    \"work_item_id\":\"3ed5df4d87cf01101ae365b83cbb35af\",
    \"reject_reason_id\":\"31e3fa29b38023002e7b6e5f26a8dc17\"
}" \
--user 'username':'password'

Successful output displays the same work item, reject reason, and user ID provided in the request body. The specified work item in the AWA Work Item [awa_work_item] table has an empty Assigned to field and the value of the Rejected field is true.

{
  "result": {
    "work_item_id": "3ed5df4d87cf01101ae365b83cbb35af",
    "reject_reason_id": "31e3fa29b38023002e7b6e5f26a8dc17",
    "agent_id": "46c9e158a9fe198101d44d0d22cb640d"
  }
}