---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# AWA Agent API

# AWA Agent API {#ariaid-title1}

* Release version: Yokohama
* 
* Updated January 30, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 20 minutes to read

The AWA (Advanced Work Assignment) Agent API provides endpoints to
manage agent presence, channel availability, and workload.
This API requires the Advanced Work Assignment (com.glide.awa) plugin and the
awa_integration_user role. For more information, refer to [Advanced Work Assignment](https://www.servicenow.com/docs/access?context=awa-overview&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).

## AWA Agent - GET /now/awa/agents/{user_id} {#ariaid-title2}

Returns the current agent presence state and channel availability.

### URL format {#awa-GET-agents__section_hsf_jvl_cmb}

Versioned URL:
/api/now/{api_version}/awa/agents/{user_id}

Default URL:
/api/now/awa/agents/{user_id}  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#awa-GET-agents__entry__2}{#awa-GET-agents__version-not_optional-RESTAPI}{#awa-GET-agents__awa-api-ph-work_item_id}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| user_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. {#awa-GET-agents__ul_zcs_rh3_htb} Data type: String Table: AWA Work Item \[awa_work_item\] |
[Table 1. Path parameters]

{#awa-GET-agents__entry__8}

| Name | Description |
|-|-|
| None |   |
[Table 2. Query parameters]

{#awa-GET-agents__presence__entry__2}{#awa-GET-agents__ph-presence_channels_avail-awa}{#awa-GET-agents__ph-presence_channels_sys_id-awa}{#awa-GET-agents__ph-presence_sys_id-awa}

| Header | Description |
|-|-|
| presence.channels.available | Flag that indicates whether the channel is available. Possible values: * true: Channel is available. * false: Channel isn't available. {#awa-GET-agents__ul_qps_xwl_cmb} Data type: Boolean |
| presence.channels.sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| presence.sys_id | Presence state sys_id. Data type: String Table: Presence States \[awa_presence_state\] |
[Table 3. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-GET-agents__entry__20}{#awa-GET-agents__accept-RESTAPI}{#awa-GET-agents__content_type-RESTAPI}

| 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 4. Request headers]

{#awa-GET-agents__entry__26}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-GET-agents__entry__30}{#awa-GET-agents__entry-200-status-code}{#awa-GET-agents__entry-400-status-code}{#awa-GET-agents__entry-401-status-code}{#awa-GET-agents__entry-403-status-code-awa}{#awa-GET-agents__entry-404-status-code}{#awa-GET-agents__entry-500-status-code}

| 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.{#awa-GET-agents__li-403-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](https://www.servicenow.com/docs/access?context=installed-with-awa&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).{#awa-GET-agents__li-403-awa-disabled} {#awa-GET-agents__ul_gch_n34_tsb} |
| 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. |
[Table 6. Status codes]

### Response body parameters (JSON or XML)

{#awa-GET-agents__table_r2q_fbm_cmb__entry__2}{#awa-GET-agents__awa-api-entry-error}{#awa-GET-agents__awa-api-ph-error_detail}{#awa-GET-agents__awa-api-ph-error_message}{#awa-GET-agents__ph-presence-awa}{#awa-GET-agents__ph-presence_available-awa}{#awa-GET-agents__ph-presence_channels-awa}{#awa-GET-agents__d4275e338}{#awa-GET-agents__ph-presence_channels_name-awa}{#awa-GET-agents__d4275e406}{#awa-GET-agents__ph-presence_name-awa}{#awa-GET-agents__ph-presence_restrict_update-awa}{#awa-GET-agents__d4275e468}{#awa-GET-agents__awa-api-entry_status}{#awa-GET-agents__ph-sys_id-awa}{#awa-GET-agents__open-workItem_document-ph}{#awa-GET-agents__open-workItem_document_sysid-ph}{#awa-GET-agents__open-workItem_document_table-ph}{#awa-GET-agents__open-workItem_previousWorkItem-ph}{#awa-GET-agents__open-workItem_serviceChannel-ph}{#awa-GET-agents__open-workItem_serviceChannel_name-ph}{#awa-GET-agents__open-workItem_serviceChannel_sys_id-ph}{#awa-GET-agents__open-workItem_size-ph}{#awa-GET-agents__open-workItem_sysid-ph}{#awa-GET-agents__open-workItem_isQueueTransferred-ph}{#awa-GET-agents__open-workItem_isAutoAccepted-ph}

| Parameter | Description |
|-|-|
| 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. Data type: String |
| error.message | Message for the error encountered during the request process. Each error message has a corresponding description in the detail property. Possible values: * Record Not Found: Information provided in the request body is inaccurate or doesn't exist. * User Not Authenticated: User doesn't have the awa_integration_user role. {#awa-GET-agents__ul_om3_5sq_tsb} Data type: String |
| presence | Information about an agent's current presence state and channel. Data type: Object "presence": { "available": Boolean, "channels": [Array], "name": "String", "sys_id": "String" } |
| presence.available | Flag that indicates whether the agent is available. Possible values: * true: Agent is available. * false: Agent isn't available. {#awa-GET-agents__ul_ezb_kwl_cmb} Data type: Boolean |
| presence.channels | List of objects that describe the available channels of communication with the agent. Data type: Array of Objects "channels": [ { "available": Boolean, "name": "String", "sys_id": "String" } ] |
| presence.channels.available | Flag that indicates whether the channel is available. Possible values: * true: Channel is available. * false: Channel isn't available. {#awa-GET-agents__d4275e343} Data type: Boolean |
| presence.channels.name | Channel name, such as Chat or Phone. Data type: String |
| presence.channels.restrict_update | Flag that indicates whether the user can restrict updates, that is, select the channel for availability. Possible values: * true: The user can select this channel for availability. * false: The user can't select this channel for availability. {#awa-GET-agents__ul_xjk_kn4_tsb} Data type: Boolean |
| presence.channels.service_channel_type | Service channel type, such as chat. Possible values vary depending on plugins installed. Data type: String |
| presence.channels.sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| presence.name | Name of the agent's presence state. Possible values: * Available * Unavailable {#awa-GET-agents__ul_mlm_mxl_cmb} Data type: String |
| presence.restrict_update | Flag that indicates whether the user can restrict updates. Possible values: * true: User can restrict updates. * false: User can't restrict updates. {#awa-GET-agents__ul_dfh_cxl_cmb} Data type: Boolean |
| presence.sys_id | Presence state sys_id. Data type: String Table: Presence States \[awa_presence_state\] |
| 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 |
| sys_id | Agent sys_id. Data type: String |
| workItem | workItem: Information about the work item that is associated with the event.{#awa-GET-agents__open-workItem-p} Data type: String |
| workItem.document | workItem.document: List of documents associated with the work item task. Data type: String |
| workItem.document.sys_id | workItem.document.sys_id: Sys_id of the document assigned to the work item task. Data type: String |
| workItem.document.table | workItem.document.table: Name of the document table assigned to the task. Data type: String |
| workItem.previousWorkItem | workItem.previousWorkItem: Sys_id of the previous work item for the same document ID. For the non-transfer work items this value is empty. Data type: String |
| workItem.serviceChannel | workItem.serviceChannel: List of service channels associated with the work item task. Data type: String |
| workItem.serviceChannel.name | workItem.serviceChannel.name: Name of the service channel, such as Chat or Phone. Data type: String |
| workItem.serviceChannel.sys_id | workItem.serviceChannel.sys_id: Sys_id of the service channel. Data type: String |
| workItem.size | workItem.size: Agent's capacity used when this work item is assigned to the agent. Data type: String |
| workItem.sys_id | workItem.sys_id: Sys_id of the work item that was accepted or offered. Data type: String |
| workItem.isQueueTransferred | workItem.isQueueTransferred: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't. For more information on queue transfers, see [Transfer a chat to another queue](https://www.servicenow.com/docs/access?context=transfer-chat-queue&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). Data type: Boolean |
| workitem.isAutoAccepted | workItem.isAutoAccepted: Flag that indicates whether the work item was automatically accepted by the system. Set to true if the work item was auto-accepted. Data type: Boolean |
[Table 7. Response body parameters (JSON or XML)]

{#awa-GET-agents__table_r2q_fbm_cmb}  

### Sample cURL request

    curl -X GET \
    https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -u 'username':'password'\

    {
      "result": {
        "presence": {
          "name": "Available",
          "sys_id": "0b10223c57a313005baaaa65ef94f970",
          "available": true,
          "channels": [
            {
              "name": "Chat",
              "available": true,
              "sys_id": "27f675e3739713004a905ee515f6a7c3"
            }
          ]
        },
        "sys_id": "46d44a23a9fe19810012d100cca80666"
      }
    }

## AWA Agent - GET
/now/awa/agents/{user_id}/capacities {#ariaid-title3}

Returns an agent's channel capacities, universal capacity, and the current workload to
see if the agent can handle a case.
Use the [AWA Agent - PUT /now/awa/agents/{user_id}/capacities](https://www.servicenow.com/docs/wT8mT4S8FyHqEk_kkFZccQ#awa-PUT-capacities "Enables updating an agent's maximum capacity (workload) for channel capacities and universal capacity.") method to modify the channel and universal
capacities of an agent.  
See also:

* [Service channel capacity and
  utilization](https://www.servicenow.com/docs/access?context=awa-service-channel-capacity&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US)
* [Create or configure a service
  channel](https://www.servicenow.com/docs/access?context=awa-create-service-channel&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US)
* [Configure an agent's maximum
  universal capacity](https://www.servicenow.com/docs/access?context=awa-universal-capacity&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US)
{#awa-GET-capacities__ul_rl1_2wg_jtb}

### URL format {#awa-GET-capacities__section_hsf_jvl_cmb}

Versioned URL:
/api/now/{api_version}/awa/agents/{user_id}/capacities

Default URL:
/api/now/awa/agents/{user_id}/capacities  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters {#awa-GET-capacities__section_vg3_ydq_htb}

{#awa-GET-capacities__table_wg3_ydq_htb__entry__2}{#awa-GET-capacities__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| user_id | Sys_id of the agent listed. Data type: String Table: User \[sys_user\] |
[Table 8. Path parameters]

{#awa-GET-capacities__table_wg3_ydq_htb} {#awa-GET-capacities__table_xg3_ydq_htb__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 9. Query parameters]

{#awa-GET-capacities__table_xg3_ydq_htb} {#awa-GET-capacities__table_yg3_ydq_htb__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 10. Request body parameters (XML or JSON)]

{#awa-GET-capacities__table_yg3_ydq_htb}

### Headers {#awa-GET-capacities__section_zg3_ydq_htb}

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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-GET-capacities__table_ah3_ydq_htb__entry__2}{#awa-GET-capacities__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 11. Request headers]

{#awa-GET-capacities__table_ah3_ydq_htb} {#awa-GET-capacities__table_bh3_ydq_htb__entry__2}

| Header | Description |
|-|-|
| None |   |
[Table 12. Response headers]

{#awa-GET-capacities__table_bh3_ydq_htb}

### Status codes {#awa-GET-capacities__section_ch3_ydq_htb}

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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-GET-capacities__table_dh3_ydq_htb__entry__2}{#awa-GET-capacities__entry-200-status-code}{#awa-GET-capacities__entry-400-status-code}{#awa-GET-capacities__entry-401-status-code}{#awa-GET-capacities__entry-403-status-code-awa}{#awa-GET-capacities__entry-404-status-code}{#awa-GET-capacities__entry-500-status-code}

| 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.{#awa-GET-capacities__li-403-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](https://www.servicenow.com/docs/access?context=installed-with-awa&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).{#awa-GET-capacities__li-403-awa-disabled} {#awa-GET-capacities__ul_gch_n34_tsb} |
| 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. |
[Table 13. Status codes]

{#awa-GET-capacities__table_dh3_ydq_htb}

### Response body parameters (JSON or XML) {#awa-GET-capacities__section_agk_dmp_htb}

{#awa-GET-capacities__table_bgk_dmp_htb__entry__2}{#awa-GET-capacities__ph-presence_channels_sys_id-awa}{#awa-GET-capacities__ordr-row-error}{#awa-GET-capacities__awa-api-ph-universal_capacity}

| Name | Description |
|-|-|
| channels | List of objects that describe the available channels of communication with the agent. "channels": [ { "channel_sys_id": "String", "current_workload": Number, "max_capacity": Number } ] Data type: Array |
| channels.channel_sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| channels.current_workload | Number of work items on a specific service channel currently assigned to the agent. Data type: Number |
| channels.max_capacity | Maximum workload on a specific service channel that the agent can be actively assigned to at a time. Data type: String |
| 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. 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 |
| universal_capacity | Maximum capacity for the agent across all service channels. If an agent's current workload equals the maximum universal capacity, additional work items won't be assigned to the agent. This property only returns if a universal capacity record exists for this agent. Data type: Number |
| universal_workload | Number of work items across all service channels currently assigned to the specified agent. This property only returns if a universal capacity record exists for the agent. Data type: Number |
[ ]

{#awa-GET-capacities__table_bgk_dmp_htb}  

### Sample cURL request {#awa-GET-capacities__example_eh3_ydq_htb}

The following example shows how to get the capacity and workload values for a user.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
    --request GET \
    --header "Accept:application/json" \
    --user 'username':'password'

A successful response includes capacity values and workload for each channel.

    {
      "result": {
        "universal_workload": 2,
        "channels": [
          {
            "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
            "current_workload": 2,
            "max_capacity": 4
          }
        ],
        "universal_capacity": 10
      }
    }

## AWA Agent - GET
/now/awa/agents/{user_id}/presence_states {#ariaid-title4}

Returns an agent's presence states and indicates whether the agent is available or in
another presence state.

### URL format {#awa-GET-presence_states__section_hsf_jvl_cmb}

Versioned URL:
/api/now/{api_version}/awa/agents/{user_id}/presence_states

Default URL:
/api/now/awa/agents/{user_id}/presence_states  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#awa-GET-presence_states__entry__2}{#awa-GET-presence_states__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| user_id | Sys_id of the agent listed. Data type: String Table: User \[sys_user\] |
[Table 14. Path parameters]

{#awa-GET-presence_states__entry__8}

| Name | Description |
|-|-|
| None |   |
[Table 15. Query parameters]

{#awa-GET-presence_states__entry__12}

| Name | Description |
|-|-|
| None |   |
[Table 16. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-GET-presence_states__entry__16}{#awa-GET-presence_states__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 17. Request headers]

{#awa-GET-presence_states__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 18. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-GET-presence_states__entry__24}{#awa-GET-presence_states__entry-200-status-code}{#awa-GET-presence_states__entry-400-status-code}{#awa-GET-presence_states__entry-401-status-code}{#awa-GET-presence_states__entry-403-status-code-awa}{#awa-GET-presence_states__entry-404-status-code}{#awa-GET-presence_states__entry-500-status-code}

| 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.{#awa-GET-presence_states__li-403-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](https://www.servicenow.com/docs/access?context=installed-with-awa&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).{#awa-GET-presence_states__li-403-awa-disabled} {#awa-GET-presence_states__ul_gch_n34_tsb} |
| 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. |
[Table 19. Status codes]

### Response body parameters (JSON or XML) {#awa-GET-presence_states__section_agk_dmp_htb}

{#awa-GET-presence_states__table_bgk_dmp_htb__entry__2}{#awa-GET-presence_states__ordr-row-error}{#awa-GET-presence_states__ph-presence_available-awa}{#awa-GET-presence_states__ph-presence_channels_avail-awa}{#awa-GET-presence_states__ph-presence_channels_name-awa}{#awa-GET-presence_states__ph-presence_channels_sys_id-awa}{#awa-GET-presence_states__ph-presence_sys_id-awa}

| Name | Description |
|-|-|
| 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. 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 |
| \<presence state\> | List of the agent's presence state definitions as objects. Each object describes the state and includes the agent's channels. Data type: Array { "available": Boolean, "channels": [Array], "disable_inactivity_check": Boolean, "name": "String", "show_channels": Boolean, "sys_id": "String" } |
| \<presence state\>.available | Flag that indicates whether the agent is available. Possible values: * true: Agent is available. * false: Agent isn't available. {#awa-GET-presence_states__ul_ezb_kwl_cmb} Data type: Boolean |
| \<presence state\>.channels | List of objects that describe the available channels of communication with the agent. Data type: Array "channels": [ { "available": Boolean, "name": "String", "restrict_update": Boolean, "service_channel_type": "String", "sys_id": "String" } ] |
| \<presence state\>.channels.available | Flag that indicates whether the channel is available. Possible values: * true: Channel is available. * false: Channel isn't available. {#awa-GET-presence_states__ul_qps_xwl_cmb} Data type: Boolean |
| \<presence state\>.channels.name | Channel name, such as Chat or Phone. Data type: String |
| \<presence state\>.channels.sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| \<presence state\>.disable_inactivity_check | Flag that indicates whether to check for inactivity of this presence state. Valid values: * true: The presence state inactivity check is disabled. * false: The presence state inactivity check is enabled. {#awa-GET-presence_states__ul_alm_cjn_jtb} Data type: Boolean Default: false For information on how to modify this setting, see [Configure agent presence states](https://www.servicenow.com/docs/access?context=awa-configure-agent-presence&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US). |
| \<presence state\>.name | Name of the agent's presence state. The presence states installed by default are Available, Away, and Offline. Data type: String |
| \<presence state\>.order | Order in which this state is displayed in the agent inbox. Data type: Number |
| \<presence state\>.show_channels | Flag that indicates whether the agent has permission to change presence state, for example, from available to away. Valid values: * true: The user has permission to change the presence. * false: The user is restricted from changing the presence. {#awa-GET-presence_states__ul_qlh_xlh_jtb} Data type: Boolean |
| \<presence state\>.sys_id | Presence state sys_id. Data type: String Table: Presence States \[awa_presence_state\] |
| 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 |
[ ]

{#awa-GET-presence_states__table_bgk_dmp_htb}  

### Sample cURL request

The following example shows how to get the presence states for a specified agent.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/presence_states" \
    --request GET \
    --header "Accept:application/json" \
    --user 'username':'password'

The response body lists the agent's possible presence states and indicates that the agent
is available.

    {
      "result": [
        {
          "name": "Available",
          "order": 0,
          "show_channels": false,
          "sys_id": "0b10223c57a313005baaaa65ef94f970",
          "available": true,
          "channels": [
            {
              "name": "Chat",
              "available": true,
              "sys_id": "27f675e3739713004a905ee515f6a7c3",
              "restrict_update": false,
              "service_channel_type": "chat"
            }
          ],
          "disable_inactivity_check": false
        },
        {
          "name": "Away",
          "order": 1000,
          "show_channels": false,
          "sys_id": "41f9b8dfb31313005baa6e5f26a8dcac",
          "available": false,
          "channels": [],
          "disable_inactivity_check": false
        },
        {
          "name": "Offline",
          "order": 2000,
          "show_channels": false,
          "sys_id": "9cd83267575313005baaaa65ef94f98b",
          "available": false,
          "channels": [],
          "disable_inactivity_check": false
        }
      ]
    }

## AWA Agent - PUT /now/awa/agents/{user_id} {#ariaid-title5}

Sets the state of a specified agent's presence and, if provided, sets the agent's
channel availability for that state.

### URL format {#awa-PUT-agents__section_qzs_ncm_cmb}

Versioned URL:
/api/now/{api_version}/awa/agents/{user_id}

Default URL:
/api/now/awa/agents/{user_id}  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#awa-PUT-agents__entry__2}{#awa-PUT-agents__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| user_id | Sys_id of the agent. Data type: String Table: User \[sys_user\] |
[Table 20. Path parameters]

{#awa-PUT-agents__entry__8}

| Name | Description |
|-|-|
| None |   |
[Table 21. Query parameters]

{#awa-PUT-agents__entry__12}{#awa-PUT-agents__ph-presence_channels_sys_id-awa}{#awa-PUT-agents__ph-presence_sys_id-awa}

| Name | Description |
|-|-|
| presence.channels | List of objects that define which channels are available for the agent. Data type: Array of Objects "channels": [ { "available": Boolean, "sys_id": "String" } ] |
| presence.channels.available | Flag that indicates whether the channel is available. Possible values: * true: Channel is available. * false: Channel isn't available. {#awa-PUT-agents__ul_qps_xwl_cmb} Note: This setting must be specified to include channels in the response body. Data type: Boolean Default: false |
| presence.channels.sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| presence.sys_id | Presence state sys_id. Data type: String Table: Presence States \[awa_presence_state\] |
[Table 22. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-PUT-agents__entry__22}{#awa-PUT-agents__accept-RESTAPI}{#awa-PUT-agents__content_type-RESTAPI}

| 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 23. Request headers]

{#awa-PUT-agents__entry__28}

| Header | Description |
|-|-|
| None |   |
[Table 24. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-PUT-agents__entry__32}{#awa-PUT-agents__entry-200-status-code}{#awa-PUT-agents__entry-400-status-code}{#awa-PUT-agents__entry-401-status-code}{#awa-PUT-agents__entry-403-status-code-awa}{#awa-PUT-agents__entry-404-status-code}{#awa-PUT-agents__entry-500-status-code}

| 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.{#awa-PUT-agents__li-403-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](https://www.servicenow.com/docs/access?context=installed-with-awa&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).{#awa-PUT-agents__li-403-awa-disabled} {#awa-PUT-agents__ul_gch_n34_tsb} |
| 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. |
[Table 25. Status codes]

{#awa-PUT-agents__table_rcs_b2m_cmb__entry__2}{#awa-PUT-agents__awa-api-entry-error}{#awa-PUT-agents__awa-api-ph-error_detail}{#awa-PUT-agents__awa-api-ph-error_message}{#awa-PUT-agents__ph-presence-awa}{#awa-PUT-agents__ph-presence_available-awa}{#awa-PUT-agents__ph-presence_channels-awa}{#awa-PUT-agents__ph-presence_channels_avail-awa}{#awa-PUT-agents__ph-presence_channels_name-awa}{#awa-PUT-agents__d4275e406}{#awa-PUT-agents__ph-presence_name-awa}{#awa-PUT-agents__ph-presence_restrict_update-awa}{#awa-PUT-agents__d4275e468}{#awa-PUT-agents__awa-api-entry_status}{#awa-PUT-agents__ph-sys_id-awa}{#awa-PUT-agents__open-workItem_document-ph}{#awa-PUT-agents__open-workItem_document_sysid-ph}{#awa-PUT-agents__open-workItem_document_table-ph}{#awa-PUT-agents__open-workItem_previousWorkItem-ph}{#awa-PUT-agents__open-workItem_serviceChannel-ph}{#awa-PUT-agents__open-workItem_serviceChannel_name-ph}{#awa-PUT-agents__open-workItem_serviceChannel_sys_id-ph}{#awa-PUT-agents__open-workItem_size-ph}{#awa-PUT-agents__open-workItem_sysid-ph}{#awa-PUT-agents__open-workItem_isQueueTransferred-ph}{#awa-PUT-agents__open-workItem_isAutoAccepted-ph}

| Parameter | Description |
|-|-|
| 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. Data type: String |
| error.message | Message for the error encountered during the request process. Each error message has a corresponding description in the detail property. Possible values: * Record Not Found: Information provided in the request body is inaccurate or doesn't exist. * User Not Authenticated: User doesn't have the awa_integration_user role. {#awa-PUT-agents__ul_om3_5sq_tsb} Data type: String |
| presence | Information about an agent's current presence state and channel. Data type: Object "presence": { "available": Boolean, "channels": [Array], "name": "String", "sys_id": "String" } |
| presence.available | Flag that indicates whether the agent is available. Possible values: * true: Agent is available. * false: Agent isn't available. {#awa-PUT-agents__ul_ezb_kwl_cmb} Data type: Boolean |
| presence.channels | List of objects that describe the available channels of communication with the agent. Data type: Array of Objects "channels": [ { "available": Boolean, "name": "String", "sys_id": "String" } ] |
| presence.channels.available | Flag that indicates whether the channel is available. Possible values: * true: Channel is available. * false: Channel isn't available. {#awa-PUT-agents__d4275e343} Data type: Boolean |
| presence.channels.name | Channel name, such as Chat or Phone. Data type: String |
| presence.channels.restrict_update | Flag that indicates whether the user can restrict updates, that is, select the channel for availability. Possible values: * true: The user can select this channel for availability. * false: The user can't select this channel for availability. {#awa-PUT-agents__ul_xjk_kn4_tsb} Data type: Boolean |
| presence.channels.service_channel_type | Service channel type, such as chat. Possible values vary depending on plugins installed. Data type: String |
| presence.channels.sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| presence.name | Name of the agent's presence state. Possible values: * Available * Unavailable {#awa-PUT-agents__ul_mlm_mxl_cmb} Data type: String |
| presence.restrict_update | Flag that indicates whether the user can restrict updates. Possible values: * true: User can restrict updates. * false: User can't restrict updates. {#awa-PUT-agents__ul_dfh_cxl_cmb} Data type: Boolean |
| presence.sys_id | Presence state sys_id. Data type: String Table: Presence States \[awa_presence_state\] |
| 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 |
| sys_id | Agent sys_id. Data type: String |
| workItem | workItem: Information about the work item that is associated with the event.{#awa-PUT-agents__open-workItem-p} Data type: String |
| workItem.document | workItem.document: List of documents associated with the work item task. Data type: String |
| workItem.document.sys_id | workItem.document.sys_id: Sys_id of the document assigned to the work item task. Data type: String |
| workItem.document.table | workItem.document.table: Name of the document table assigned to the task. Data type: String |
| workItem.previousWorkItem | workItem.previousWorkItem: Sys_id of the previous work item for the same document ID. For the non-transfer work items this value is empty. Data type: String |
| workItem.serviceChannel | workItem.serviceChannel: List of service channels associated with the work item task. Data type: String |
| workItem.serviceChannel.name | workItem.serviceChannel.name: Name of the service channel, such as Chat or Phone. Data type: String |
| workItem.serviceChannel.sys_id | workItem.serviceChannel.sys_id: Sys_id of the service channel. Data type: String |
| workItem.size | workItem.size: Agent's capacity used when this work item is assigned to the agent. Data type: String |
| workItem.sys_id | workItem.sys_id: Sys_id of the work item that was accepted or offered. Data type: String |
| workItem.isQueueTransferred | workItem.isQueueTransferred: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't. For more information on queue transfers, see [Transfer a chat to another queue](https://www.servicenow.com/docs/access?context=transfer-chat-queue&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). Data type: Boolean |
| workitem.isAutoAccepted | workItem.isAutoAccepted: Flag that indicates whether the work item was automatically accepted by the system. Set to true if the work item was auto-accepted. Data type: Boolean |
[Table 26. Response body parameters (JSON or XML)]

{#awa-PUT-agents__table_rcs_b2m_cmb}  

    curl -X PUT \
     https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -u 'username':'password'\
    -d '{"presence": {\
      "sys_id": "0b10223c57a313005baaaa65ef94f970",\
      "channels": [{ \
      "sys_id": "0bbdedbb3b892300a2bac9bb34efc445",\
      "available": true
    }] 
    }}

    {
      "result": {
        "presence": {
          "name": "Available",
          "sys_id": "0b10223c57a313005baaaa65ef94f970",
          "available": true,
          "channels": [
            {
              "name": "Chat",
              "available": true,
              "sys_id": "27f675e3739713004a905ee515f6a7c3"
            }
          ]
        },
        "sys_id": "46d44a23a9fe19810012d100cca80666"
      }
    }

## AWA Agent - PUT
/now/awa/agents/{user_id}/capacities {#ariaid-title6}

Enables updating an agent's maximum capacity (workload) for channel capacities and
universal capacity.
Use the [AWA Agent - GET /now/awa/agents/{user_id}/capacities](https://www.servicenow.com/docs/wT8mT4S8FyHqEk_kkFZccQ#awa-GET-capacities "Returns an agent's channel capacities, universal capacity, and the current workload to see if the agent can handle a case.") method to retrieve the current channel and
universal capacities of an agent.  
See also:

* [Service channel capacity and
  utilization](https://www.servicenow.com/docs/access?context=awa-service-channel-capacity&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US)
* [Create or configure a service
  channel](https://www.servicenow.com/docs/access?context=awa-create-service-channel&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US)
* [Configure an agent's maximum
  universal capacity](https://www.servicenow.com/docs/access?context=awa-universal-capacity&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US)
{#awa-PUT-capacities__ul_rl1_2wg_jtb}

### URL format {#awa-PUT-capacities__section_hsf_jvl_cmb}

Versioned URL:
/api/now/{api_version}/awa/agents/{user_id}/capacities

Default URL:
/api/now/awa/agents/{user_id}/capacities  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#awa-PUT-capacities__entry__2}{#awa-PUT-capacities__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| user_id | Sys_id of the agent listed. Data type: String Table: User \[sys_user\] |
[Table 27. Path parameters]

{#awa-PUT-capacities__entry__8}

| Name | Description |
|-|-|
| None |   |
[Table 28. Query parameters]

{#awa-PUT-capacities__entry__12}

| Name | Description |
|-|-|
| channels | Mandatory if updating the maximum value of one or more channels for the specified agent. JSON object containing one or more key-value pairs mapping the channel to its maximum capacity for each channel assigned to the agent. Data type: Object The pair is in the following format: * Key (channel sys_id) -- Channel sys_id. Data type: String * Value (maximum capacity) -- Maximum workload on a specific service channel that the agent can be actively assigned to at a time. Data type: Number {#awa-PUT-capacities__ul_e35_r3g_jtb} channels: {"<channel_sys_id>": <max_capacity>} |
| universal_capacity | Mandatory if universal capacity is being updated. Maximum capacity for the agent across all service channels. If an agent's current workload equals the maximum universal capacity, additional work items won't be assigned to the agent. Data type: Number |
[Table 29. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-PUT-capacities__entry__18}{#awa-PUT-capacities__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 30. Request headers]

{#awa-PUT-capacities__entry__22}

| Header | Description |
|-|-|
| None |   |
[Table 31. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#awa-PUT-capacities__entry__26}{#awa-PUT-capacities__entry-200-status-code}{#awa-PUT-capacities__entry-400-status-code}{#awa-PUT-capacities__entry-404-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 404 | Not found. The requested item wasn't found. |
[Table 32. Status codes]

### Response body parameters (JSON or XML) {#awa-PUT-capacities__section_agk_dmp_htb}

{#awa-PUT-capacities__table_bgk_dmp_htb__entry__2}{#awa-PUT-capacities__ph-presence_channels_sys_id-awa}{#awa-PUT-capacities__ordr-row-error}{#awa-PUT-capacities__awa-api-ph-universal_capacity}

| Name | Description |
|-|-|
| channels | List of objects that describe the available channels of communication with the agent. "channels": [ { "channel_sys_id": "String", "max_capacity": Number } ] Data type: Array |
| channels.channel_sys_id | Channel sys_id. Data type: String Table: Service Channels \[awa_service_channel\] |
| channels.max_capacity | Maximum workload on a specific service channel that the agent can be actively assigned to at a time. Data type: String |
| 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. 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 |
| universal_capacity | Maximum capacity for the agent across all service channels. If an agent's current workload equals the maximum universal capacity, additional work items won't be assigned to the agent. This property only returns if a universal capacity record exists for this agent. Data type: Number |
[ ]

{#awa-PUT-capacities__table_bgk_dmp_htb}  

### Sample cURL request

The following example shows how to change the agent's universal capacity and the maximum
capacity for a specified channel.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
    --request PUT \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data "{
     \"channels\": { \"27f675e3739713004a905ee515f6a7c3\": 6 },
     \"universal_capacity\" : 12
    }" \
    --user 'username':'password'

A successful response includes the updated capacity values.

    {
      "result": {
        "channels": [
          {
            "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
            "max_capacity": 6
          }
        ],
        "universal_capacity": 12
      }
    }