Assembled

Assembled Agent State API

Read and write real-time agent state used to drive adherence reporting, live dashboards, and dynamic routing. Supports bulk state ingestion from upstream telephony and CRM platforms, a condensed non-overlapping timeline view, edit history, and platform-ID associations that link Assembled people to identities in Zendesk, Salesforce, Five9, and other integrated systems.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.assembled.com/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/assembled/refs/heads/main/openapi/assembled-agent-state-api-openapi.yml

OpenAPI Specification

assembled-agent-state-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Assembled Activities Agent State API
  description: 'Activities are the scheduled shifts, breaks, time-off blocks, training

    sessions, and meetings that make up an agent''s calendar in Assembled.


    The Activities API supports single and bulk activity creation, listing

    with rich filters, soft-delete semantics, and CRUD for activity types

    (the colour-coded categories shown on schedules). The event_changes

    endpoint surfaces an audit trail of schedule modifications.

    '
  version: '2026-05-24'
  contact:
    name: Assembled Support
    url: https://support.assembled.com
servers:
- url: https://api.assembledhq.com
  description: Production Server
security:
- BasicAuth: []
tags:
- name: Agent State
  description: Real-time and historical agent state
paths:
  /v0/agents/state:
    get:
      summary: Assembled Get Agent States
      description: Retrieve agent state records for a time range, optionally filtered by agent.
      operationId: getAgentStates
      tags:
      - Agent State
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      - in: query
        name: start_time
        required: true
        schema:
          type: string
          format: date-time
      - in: query
        name: end_time
        required: true
        schema:
          type: string
          format: date-time
      - in: query
        name: agent_ids
        description: Comma-separated list of Assembled agent IDs.
        schema:
          type: string
      responses:
        '200':
          description: Agent states
          content:
            application/json:
              schema:
                type: object
                properties:
                  states:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentState'
    post:
      deprecated: true
      summary: Assembled Update Agent State (Deprecated)
      description: Deprecated single-state update endpoint. Use /v0/agents/state/bulk instead.
      operationId: postAgentState
      tags:
      - Agent State
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentStateInput'
      responses:
        '200':
          description: Updated
  /v0/agents/state/bulk:
    post:
      summary: Assembled Bulk Update Agent States
      description: Submit a batch of agent state records ingested from upstream telephony or CRM platforms.
      operationId: bulkUpdateAgentStates
      tags:
      - Agent State
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                states:
                  type: array
                  items:
                    $ref: '#/components/schemas/AgentStateInput'
      responses:
        '202':
          description: Accepted for processing
  /v0/agents/state/condensed_timeline:
    get:
      summary: Assembled Get Condensed Agent State Timeline
      description: Returns a non-overlapping timeline of agent state changes — useful for adherence and shrinkage reports.
      operationId: getCondensedTimeline
      tags:
      - Agent State
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      - in: query
        name: start_time
        required: true
        schema:
          type: string
          format: date-time
      - in: query
        name: end_time
        required: true
        schema:
          type: string
          format: date-time
      - in: query
        name: agent_ids
        schema:
          type: string
      responses:
        '200':
          description: Condensed timeline
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeline:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentState'
  /v0/agents/state/edit:
    post:
      summary: Assembled Edit Agent State
      description: Insert, update, or delete agent state records.
      operationId: editAgentState
      tags:
      - Agent State
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                inserts:
                  type: array
                  items:
                    $ref: '#/components/schemas/AgentStateInput'
                updates:
                  type: array
                  items:
                    $ref: '#/components/schemas/AgentStateInput'
                deletes:
                  type: array
                  items:
                    type: string
                    description: State record IDs to delete
      responses:
        '200':
          description: Edit applied
  /v0/agents/state/edit/history:
    get:
      summary: Assembled Get Agent State Edit History
      description: Audit trail of edits made to agent state records.
      operationId: getEditHistory
      tags:
      - Agent State
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      - in: query
        name: start_time
        schema:
          type: string
          format: date-time
      - in: query
        name: end_time
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Edit history
components:
  schemas:
    AgentState:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        state:
          type: string
          example: available
        sub_state:
          type: string
          nullable: true
          example: chat
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
          nullable: true
        source:
          type: string
          example: zendesk
    AgentStateInput:
      type: object
      required:
      - agent_id
      - state
      - start_time
      properties:
        agent_id:
          type: string
        state:
          type: string
        sub_state:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        source:
          type: string
  parameters:
    ApiVersionHeader:
      in: header
      name: API-Version
      required: false
      schema:
        type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic