REST API reference › API reference › API implementation and reference

Release: Australia · Updated: 2026-03-12 · Official documentation · View source

AWA Inbox Actions API

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.

Parent Topic:REST API reference

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

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\]

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
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.
404	Record not found. The channel ID provided is not valid.
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)

Name	Description
display\_value	Display value of the Reason field in the Reject Reasons \[awa\_reject\_reason\] table.Data type: String
order	Order in which the reject reasons are listed in the agent inbox.Data type: Number
value	Value of the reject reason field stored in the database.Data type: String
Sys\_id	Sys\_id of a rejection reason for this service channel.Data type: String Table: Reject Reasons \[awa\_reject\_reason\]

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

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

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

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.

Status code	Description
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)

Name	Description
documentTable	Name of the table listing the document assigned to this work item.Data type: String
documentSysId	Sys_id of the document record assigned to the task.Data type: String Table: In the table identified in the documentTable field.
error	Details describing an error encountered during the request process.Data type: Object `"error": { "detail": "String", "message": "String" }`
error.detail	Details of the error encountered during the request process. Possible values: `Missing agent ID`: The agent_id wasn't provided in the request body. `Missing work item ID`: The work_item_id wasn't provided in the request body. `Work item is assigned to a different agent`: The specified work item is not assigned to the specified agent. `Wrong work item ID`: The work item provided in the request body is inaccurate or doesn't exist. `Work item is not in pending accept state`: The work item provided in the request body is in a state other than Pending Accept. Data type: String
error.message	Message for the error encountered during the request process. The description is provided in the error.detail property.Data type: String
status	Status of an unsuccessful request. This property is only included in the response if there is an error.Valid value: `failure` Data type: String

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

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

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

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.

Status code	Description
200	Successful. The request was successfully processed.
400	Invalid request. Possible reasons: - Missing agent ID. - Missing work item ID. - Missing reject reason 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.
404	Not found. The requested item wasn't found.Possible reasons: - Wrong agent ID – There is no record for the specified user. - Wrong reject reason ID – There is no record for the specified reject reason. - Wrong work item ID – There is no record for the specified work item.
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)

Name	Description
agent\_id	Sys\_id of the agent listed.Data type: String Table: User \[sys\_user\]
error	Details describing an error encountered during the request process.Data type: Object `"error": { "detail": "String", "message": "String" }`
error.detail	Details of the error encountered during the request process. Possible values: `Missing agent ID` – The agent_id wasn't provided in the request body. `Missing reject reason item ID` – The reject_reason_id wasn't provided in the request body. `Missing work item ID`: The work_item_id wasn't provided in the request body. `There is no record for awa_reject_reason : <reason_sys_id>` – The reject_reason_id provided in the request body doesn't have a matching record in the Reject Reasons [awa_reject_reason] table. `There is no record for awa_work_item : <work_item_sys_id>` – The work_item_id provided in the request body doesn't have a matching record in the AWA Work Item [awa_work_item] table. `There is no record for sys_user : <agent_sys_id>` – The agent_id provided in the request body doesn't have a matching record in the User [sys_user] table. `Work item is not in pending accept state`: The work item provided in the request body is in a state other than Pending Accept. Data type: String
error.message	Message for the error encountered during the request process. The description is provided in the error.detail property.Data type: String
status	Status of an unsuccessful request. This property is only included in the response if there is an error.Valid value: `failure` Data type: String
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. Data type: String

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"
  }
}