AWA Offer Work API

  • Release version: Australia
  • Updated March 12, 2026
  • 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 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.

    Use the AWA Agent Consult API to handle agent consult work items.

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

    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

    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
    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 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    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.

    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.

    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.

    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 true.

    Valid values:
    • card_and_tab: Display both the card and tab.
    • card_only: Display only the card.

    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.

    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.

    Data type: String
    transfer.target_type Required for transfer assignments. Type of record to transfer the assignment to.
    Valid values:
    • agent
    • queue

    Data type: String
    transfer.transfer_type Required for transfer assignments. Type of transfer.
    Valid values:
    • blind
    • consult

    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.
    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.

    Response body parameters (JSON or XML)

    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.
    • <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.
    • 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.
    success Flag that indicates whether the assignment is successful.
    Possible values:
    • true: Assignment successful.
    • false: Assignment unsuccessful.

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