AWA Routing API

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read

    • The AWA Routing API provides endpoints to route a document to a queue.

    This API requires the Advanced Work Assignment plugin (com.glide.awa) and the awa_integration_user role.

    AWA Routing - POST /now/awa/queues/{queue_sys_id}/work_item

    If an active work item exists, routes a document to a queue. If an active work item does not exist for the specified document, creates a work item and set its fields accordingly.

    URL format

    Versioned URL: /api/now/{api_version}/awa/queues/{queue_sys_id}/work_item

    Default URL: /api/now/awa/queues/{queue_sys_id}/work_item

    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
    queue_sys_id Sys_id of the queue record.

    Data type: String

    Table: Queue [awa_queue]
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    Name Description
    document_sys_id Sys_id of the document to route to the queue.

    Data type: String
    document_table Name of the table associated with the document, such as incident.

    Data type: String

    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
    Content-Type Data format of the request 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.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    404 Not found. The requested item wasn't found.
    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_name Name of the document to route by this work item, such as case record.

    Data type: String
    document_sys_id Sys_id of the document to route to the queue.

    Data type: String
    document_table Name of the table associated with the document.

    Data type: String
    queue_sys_id Sys_id of the queue on which to route a document.

    Data type: String
    sys_id Sys_id of the work item assigned to the queue.

    Data type: String

    Sample cURL request

    curl -X POST \
  https://instance.servicenow.com/api/now/awa/queues/339eed3f3b892300a2bac9bb34efc4c3/work_item \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-u 'username':'password'
-d '{
  "document_sys_id": "9c573169c611228700193229fff72400",
  "document_table": "incident"
}'
    {
  "result": {
    "sys_id": "cd57f90ddbb26300db2051735e9619f0",
    "document_table": "incident",
    "document_sys_id": "9c573169c611228700193229fff72400",
    "queue_sys_id": "339eed3f3b892300a2bac9bb34efc4c3",
    "display_name": "Incident: INC0000001"
  }
}