{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":470,"path":"api-reference/rest-apis/awa-agent-consult-api.md","title":"AWA Agent Consult API","bundle":null,"doc_type":null,"release":"australia","body":"\n# AWA Agent Consult API\n\nHandles agent consult work items.\n\nThis API requires the Advanced Work Assignment plugin \\(com.glide.awa\\) and the awa\\_integration\\_user role.\n\nFor more information about AWA, see [Advanced Work Assignment](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-overview.md).\n\nUse the [AWA Offer Work API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/awa-offer-work-api.md) to initiate a consult transfer to an agent or a queue.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## AWA Agent Consult - PUT /now/awa/consult/end\n\nEnds a consult work item.\n\nWhen a document is consult transferred to an agent, the respective work item must be closed with the appropriate consult state, either `Transferred` or `Ended`.\n\nA work item is a single piece of work handled by an AWA agent from start to finish. A work item is created based on a document, such as an interaction or task.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/consult/end`\n\nDefault URL: `/api/now/awa/consult/end`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ndocument\\_sys\\_id\n\n</td><td>\n\nSys\\_id of the document associated with the consult work item.A document is any record in any table, such as an interaction, case, or incident.\n\nData type: String\n\n</td></tr><tr><td>\n\nhand\\_over\n\n</td><td>\n\nFlag that indicates whether a consult transfer must be ended or transferred.Valid values:\n\n-   true: Transfer the document to consult agent and set the consult work item’s consult state as `Transferred`.\n-   false: Ends the consult transfer and set the consult work item’s consult state as`Ended`.\n\n**Note:** If the consult work item’s consult state is `Requested`, the state changes to `Cancelled`.\n\nData type: Boolean\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td id=\"entry-200-status-code\">\n\nSuccessful. The request was successfully processed.\n\n</td></tr><tr><td>\n\n400\n\n</td><td id=\"entry-400-status-code\">\n\nBad Request. A bad request type or malformed request was detected.\n\n</td></tr><tr><td>\n\n401\n\n</td><td id=\"entry-401-status-code\">\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n</td></tr><tr><td>\n\n403\n\n</td><td id=\"entry-403-status-code-awa\">\n\nForbidden.Possible reasons:\n\n-   The user doesn't have the awa\\_integration\\_user role.\n-   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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/installed-with-awa.md).\n\n</td></tr><tr><td>\n\n404\n\n</td><td id=\"entry-404-status-code\">\n\nNot found. The requested item wasn't found.\n\n</td></tr><tr><td>\n\n500\n\n</td><td id=\"entry-500-status-code\">\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsuccess\n\n</td><td>\n\nFlag that indicates whether the ending consult is successful.Valid values:\n\n-   true: The ending consult is successful.\n-   false: The ending consult is unsuccessful.\n\nData type: Boolean\n\n</td></tr><tr><td>\n\nmessage\n\n</td><td>\n\nSuccess or failure information for the ending consult.Possible values:\n\n-   `Consult is successfully ended.` – Success.\n-   `Cannot find the work item for document ID: <api_caller_sys_id>` – Make sure the active consult work item exists for the document.\n\nData type: String\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"https://instance.servicenow.com/api/now/awa/consult/end\" \\\n--request PUT \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data '{\n    \"document_sys_id\": \"59616aba87bd5210be070d48dabb35e6\",\n    \"hand_over\": \"true\"\n}' \\\n--user 'username':'password'\n```\n\n```\n{\n  \"result\": {\n    \"success\": true,\n    \"message\": \"Consult is successfully ended.\"\n  }\n}\n```\n\n"}}