---
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 Offer Work API

# AWA Offer Work API {#ariaid-title1}

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

The AWA Offer Work API provides an endpoint to assign or transfer work items to agents.
This API is intended for use with Contact Center as a Service (CCAAS) integrations where the routing and assignment decision takes place in the external CCAAS system. This API allows an [inbox card](https://www.servicenow.com/docs/access?context=awa-inbox-layout&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US) to be shown to an agent in the ServiceNow
Agent Workspace as a notification to accept the work item.

This API requires the Advanced Work Assignment (com.glide.awa) plugin. To call this API, you must have either the awa_manager or awa_integration_user role.

For more information about AWA, see [Advanced Work Assignment](https://www.servicenow.com/docs/access?context=awa-overview&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).

## AWA Offer Work - POST /now/awa/documents/{document_table}/{document_sys_id}/offer {#ariaid-title2}

Assigns or transfers work items to agents.
A 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.

All agents receiving or transferring work items with this API must have the awa_agent and awa_external_user roles.

### URL format

Versioned URL: /api/now/{api_version}/awa/documents/{document_table}/{document_sys_id}/offer

Default URL: /api/now/awa/documents/{document_table}/{document_sys_id}/offer

### Supported request parameters

{#awa-offer-work-POST-docs-offer__entry__2}{#awa-offer-work-POST-docs-offer__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 |
| document_table | Name of the table associated with the document, such as the Interaction \[interaction\] table or Task \[task\] table. Data type: String |
| document_sys_id | Sys_id of the document to route to the agent or queue. Data type: String |
[Table 1. Path parameters]

{#awa-offer-work-POST-docs-offer__entry__10}

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

{#awa-offer-work-POST-docs-offer__entry__14}

| Name | Description |
|-|-|
| assignment | Required for new assignments. Object containing information about the assignment. Data type: Object { "after_timeout_presence": "String", "agent_sys_id": "String", "allowed_to_decline": Boolean, "display_option": "String", "enable_auto_assign": Boolean, "offered_on": "String", "timeout": Number } |
| assignment.after_timeout_presence | Sys_id of the presence state that the agent switches to if the timeout parameter expires. If the timeout parameter isn't passed, this parameter is ignored. For additional information on presence states, 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). Data type: String Default: Empty string (Agent presence state doesn't change). Table: AWA Presence State \[awa_presence_state\] |
| assignment.agent_sys_id | Required for new assignments. Sys_id of the available agent to receive the work item. The agent must have the awa_agent and awa_external_user roles. For information on how to determine if an agent is available, refer to [Agent Inbox controls](https://www.servicenow.com/docs/access?context=agent-experience&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US). Data type: String Table: User \[sys_user\] |
| assignment.allowed_to_decline | Flag that indicates whether agents are allowed to reject work items. If this parameter is `true`, the inbox card displays both the Accept and Reject buttons on the inbox card. Valid values: * true/yes/1: Agent can reject work items. * false/no/0: Agent can't reject work items. {#awa-offer-work-POST-docs-offer__ul_f35_d5n_5dc} Data type: Boolean Default: true |
| assignment.display_option | Display option for the card and tab when a work item is automatically assigned. This parameter is only valid if enable_auto_assign is <kbd class="ph userinput">true</kbd>. Valid values: * card_and_tab: Display both the card and tab. * card_only: Display only the card. {#awa-offer-work-POST-docs-offer__ul_m35_d5n_5dc} Data type: String Default: card_only |
| assignment.enable_auto_assign | Flag that indicates whether the work item should be automatically accepted or should allow the agent to manually accept or reject the work item. Valid values: * true/yes/1: Automatically accept. * false/no/0: Allow agent to manually accept or reject. {#awa-offer-work-POST-docs-offer__ul_o35_d5n_5dc} Data type: Boolean Default: false |
| assignment.offered_on | Work item offer time. The offer time is used to calculate the remaining time the agent has left to accept the work item in the inbox. It helps account for the discrepancy between the time when the API request gets processed, and when the third-party routing system invokes the API request. This parameter allows external systems calling this endpoint to configure the offer time of the work item so that it stays in synchronization with the external system's internal tracking of the work item. For example, if the work item was offered on 11:30:30, the timeout is 30 seconds, and the current time is 11:30:45, the countdown timer displays 00:15 (as in 15 seconds remaining). This value is stored in the offered_on field on the work item. This parameter is ignored if the timeout parameter isn't passed. Data type: String Format: UTC timestamp (yyyy-MM-dd'T'HH:mm:ss.SSS) |
| assignment.timeout | Amount of time that the work item stays in the agent's inbox waiting for the agent to accept the work assignment. Data type: Number Unit: Seconds Default: Empty string (No time limit). |
| external_segment_id | External identifier from the CCAAS system of the call segment offered to the agent. Data type: String |
| queue_id | Required for new assignments. Sys_id of the queue record or the queue identifier in an external system. If using a queue_id from an external system, it must be mapped to the Provider queue ID (external_id) field on the awa_queue record. Data type: String Table: Queue \[awa_queue\] |
| transfer | Required for transfer assignments. Object containing information about the transfer. If a value is provided for this parameter, the assignment is considered a transfer assignment. Data type: Object { "source_queue_id": "String", "target_id": "String", "target_type": "String", "transfer_type": "String" } |
| transfer.source_queue_id | Required for transfer assignments. Source queue from where the transfer is initiated. Sys_id of the queue record or the queue identifier in an external system. If using a queue_id from an external system, it must be mapped to the Provider queue ID (external_id) field on the awa_queue record. This parameter is used to create a work item before initiating the transfer if an active work item is not found. It enables transfers to be performed if the original interaction was created without any routing, such as for outbound calls. Data type: String Table: Queue \[awa_queue\] |
| transfer.target_id | Required for transfer assignments. Sys_id of the agent or queue record to transfer the assignment to. * If target_type is `agent`, target_id is the sys_id of the agent user record in the User \[sys_user\] table. * If target_type is `queue`, target_id is the sys_id of the queue record in the Queue \[awa_queue\] table or the queue identifier in an external system. {#awa-offer-work-POST-docs-offer__ul_arh_1zw_c2c} Data type: String |
| transfer.target_type | Required for transfer assignments. Type of record to transfer the assignment to. Valid values: * agent * queue {#awa-offer-work-POST-docs-offer__ul_irj_lwv_sdc} Data type: String |
| transfer.transfer_type | Required for transfer assignments. Type of transfer. Valid values: * blind * consult {#awa-offer-work-POST-docs-offer__ul_nds_zbw_sdc} Data type: String |
[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-offer-work-POST-docs-offer__entry__46}{#awa-offer-work-POST-docs-offer__accept-RESTAPI}{#awa-offer-work-POST-docs-offer__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-offer-work-POST-docs-offer__entry__52}

| 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-offer-work-POST-docs-offer__entry__56}{#awa-offer-work-POST-docs-offer__entry-200-status-code}{#awa-offer-work-POST-docs-offer__entry-401-status-code}{#awa-offer-work-POST-docs-offer__entry-404-status-code}{#awa-offer-work-POST-docs-offer__entry-500-status-code}

| 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. |
| 409 | Conflict. The request couldn't be processed due to an error with the provided document's work item or agent sys_id. |
| 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-offer-work-POST-docs-offer__entry__68}

| Name | Description |
|-|-|
| message | Response message with information about the assignment success or failure. Possible values: * `Manual assignment successfully requested` - Success. * `Caller <API_caller_sys_id> does not have the awa_manager or awa_integration_user role` -- The authenticated user making the API request must have either the awa_manager or awa_integration_user role. * `Work Item accepted can not be assigned` -- Work item can't be assigned because it is already accepted by an agent. For more information, see [Check work items and AWA events](https://www.servicenow.com/docs/access?context=awa-work-items-all&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US). * `<agent_sys_id> is not a valid agent` -- Agent doesn't have the awa_agent role. * `Transfer failed - couldn't blind transfer to agent` - Assignment wasn't transferred because the agent isn't in the Available state in AWA. * `Work Item is already assigned to <agent_sys_id>` -- Provided work item is assigned to another agent. * `Agent is not available` -- Agent isn't in the Available state in AWA. For more information, see [Agent Inbox controls](https://www.servicenow.com/docs/access?context=agent-experience&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US). * `Timeout value cannot be negative` -- Provided timeout value can't be negative. * `<presence_state_sys_id> is not a valid presence state` -- Provided presence state sys_id doesn't exist in the AWA Presence State \[awa_presence_state\] table. * `Offered time (<offered_on_timestamp>) must be in the following format: yyyy-MM-dd'T'HH:mm:ss.SSS` -- Provided offered_on timestamp must use the specified format. * `Offered time (<offered_on_timestamp>) must be before the current time, otherwise agent will have more time to accept the work item` -- Provided offered_on timestamp can't be before the time the request is made. * `Timestamp after timeout (<offered_on_timestamp >) must be after the current time, otherwise agent has no time to accept the work item` -- The timestamp after adding the timeout value to the provided offered_on timestamp must be after the time the request was made. * `<display_option> is not a valid display option` -- Provided display_option must be one of the following values: `card_only` or `card_and_tab`. * `%s is not a valid boolean value` -- Provided Boolean value must use one of the following formats: `yes/no`, `true/false`, `1/0`. * `The user does not have the 'awa_external_user' role` - Agent receiving the assignment must have the awa_external_user role. * `Document is not active` - Provided document must be active and not in a closed state. {#awa-offer-work-POST-docs-offer__ul_lrr_2nw_sdc} |
| success | Flag that indicates whether the assignment is successful. Possible values: * true: Assignment successful. * false: Assignment unsuccessful. {#awa-offer-work-POST-docs-offer__ul_pz5_tmw_sdc} Data type: Boolean |
| work_item | Details about the created or updated work item. Data type: Object { "display_name": "String", "document_id": "String", "document_table": "String", "queue": "String", "sys_id": "String" } |
| work_item.display_name | Display name of the document record. Data type: String |
| work_item.document_id | Sys_id of the document record. Data type: String |
| work_item.document_table | Name of the table associated with the document. Data type: String |
| work_item.queue | Sys_id of the queue record or the queue identifier in an external system. Data type: String Table: Queue \[awa_queue\] |
| work_item.sys_id | Sys_id of the work item. Data type: String Table: Work Item \[awa_work_item\] |
[ ]

### cURL request

This example shows how to assign a work item to an agent.

    curl "https://instance.servicenow.com/api/now/awa/documents/interaction/59616aba87bd5210be070d48dabb35e6/offer" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data '{ 
        "external_segment_id": "segment_59616aba87bd5210be070d48dabb35e6", 
        "queue_id": "92f8942787851210be070d48dabb35fb", 
        "assignment": { 
            "agent_sys_id": "0d584509c323120095ccd02422d3ae5b", 
            "allowed_to_decline": "true", 
            "enable_auto_assign": "false", 
            "timeout": 30, 
            "offered_on":"2024-04-03T23:09:31.000" 
        } 
    }' 
    --user 'username':'password'

The response shows that the work item is successfully assigned to the agent. You can verify the result in the Assigned to field of the Work Item \[awa_work_item\] record.

    { 
       "result": { 
          "work_item": { 
             "display_name": "Interaction: IMS0000221", 
             "sys_id": "bfa3a27e87bd5210be070d48dabb3588", 
             "document_id": "59616aba87bd5210be070d48dabb35e6", 
             "document_table": "interaction", 
             "queue": "92f8942787851210be070d48dabb35fb" 
          }, 
          "success": true, 
          "message": "Manual assignment successfully requested." 
       } 
    }