> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.uponai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update phone number assignment

> Assign, update, or remove outbound and inbound phone number bindings. Supports weighted agent arrays for inbound and outbound assignment, optional agent versions, and inbound A/B testing.



## OpenAPI

````yaml /openapi.json put /api/numbers/{number}/agent
openapi: 3.1.0
info:
  title: UponAI Platform API
  version: '2026-04-20'
  description: >-
    Programmatic control plane for configuring UponAI agents, LLM
    configurations, conversation flows, knowledge bases, calls, chats, voices,
    and test tooling. All endpoints require a bearer token obtained from your
    profile settings.
servers:
  - url: https://api.upon-ai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Calls
    description: Initiate and manage UponAI powered voice and web calls.
  - name: Agents
    description: Configure agents that power calls and web sessions.
  - name: LLM Models
    description: Manage reusable large language model configurations for agents.
  - name: Chat Agents
    description: Configure agents for browser and messaging chat sessions.
  - name: Chats
    description: Start and manage live chat sessions.
  - name: Conversation Flows
    description: Build and maintain reusable dialog graphs for agents.
  - name: Knowledge Bases
    description: Store and curate grounded knowledge sources.
  - name: Voices
    description: Discover, search, add, and clone speech synthesis voices.
  - name: Test Case Definitions
    description: Define simulation test cases for response engines.
  - name: Test Runs
    description: Retrieve results for individual and batch test runs.
  - name: Account
    description: Account level utilities and limits.
  - name: Phone Numbers
    description: List and assign phone numbers to agents.
paths:
  /api/numbers/{number}/agent:
    parameters:
      - $ref: '#/components/parameters/NumberPath'
    put:
      tags:
        - Phone Numbers
      summary: Update phone number assignment
      description: >-
        Assign, update, or remove outbound and inbound phone number bindings.
        Supports weighted agent arrays for inbound and outbound assignment,
        optional agent versions, and inbound A/B testing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePhoneNumberRequest'
            examples:
              default:
                value:
                  accountSid: 29e90072-fb58-4c6c-870a-43005115131e
                  workspaceId: 1
                  outboundAgentId: agent_d3c2df14e163c7ca8ac5b1bf38
                  outboundAgentVersion: 0
                  inboundAgents:
                    - agent_id: agent_d3c2df14e163c7ca8ac5b1bf38
                      agent_version: 0
                      weight: 0.5
                    - agent_id: agent_1f864a29b7c2ab407103c88335
                      agent_version: 0
                      weight: 0.5
                  inboundWebhookUrl: >-
                    https://app.uponai.com/inbound-dynamic-vars/1/uponaiworkspace-913
                  isTimeRoutingEnabled: false
      responses:
        '200':
          description: Updated phone number assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberUpdateResponse'
        '400':
          description: Invalid assignment payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The caller cannot access the requested account or workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The phone number or workspace was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    NumberPath:
      name: number
      in: path
      required: true
      schema:
        type: string
      description: Phone number or extension identifier to update.
  schemas:
    UpdatePhoneNumberRequest:
      type: object
      required:
        - accountSid
        - workspaceId
      properties:
        accountSid:
          type: string
        workspaceId:
          type: integer
        outboundAgentId:
          type: string
          nullable: true
        outboundAgentVersion:
          type: integer
        inboundAgents:
          type: array
          items:
            $ref: '#/components/schemas/AgentRef'
        inboundWebhookUrl:
          type: string
          format: uri
          nullable: true
        isTimeRoutingEnabled:
          type: boolean
    PhoneNumberUpdateResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        assignment:
          type: object
          properties:
            account_sid:
              type: string
            workspace_id:
              type: integer
            agent_id:
              type: string
              nullable: true
            inbound_agent_id:
              type: string
              nullable: true
            outbound_agents:
              type: array
              items:
                $ref: '#/components/schemas/AgentRef'
            inbound_agents:
              type: array
              items:
                $ref: '#/components/schemas/AgentRef'
            is_time_routing_enabled:
              type: boolean
            platform_import_error:
              type: boolean
            platform_import_error_message:
              type: string
              nullable: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    AgentRef:
      type: object
      properties:
        agent_id:
          type: string
        agent_version:
          type: integer
        weight:
          type: number
    PhoneNumber:
      type: object
      properties:
        id:
          type: integer
        number:
          type: string
        base_number:
          type: string
        account_sid:
          type: string
        workspace_id:
          type: integer
        agent_id:
          type: string
          nullable: true
        default_agent_id:
          type: string
          nullable: true
        inbound_agent_id:
          type: string
          nullable: true
        inbound_agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentRef'
        outbound_agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentRef'
        inbound_agent_version:
          type: integer
          nullable: true
        outbound_agent_version:
          type: integer
          nullable: true
        application_sid:
          type: string
          nullable: true
        phone_number_sid:
          type: string
          nullable: true
        inbound_webhook_url:
          type: string
          format: uri
          nullable: true
        is_time_routing_enabled:
          type: boolean
        platform_import_error:
          type: boolean
        platform_import_error_message:
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Generate tokens from your profile settings at app.uponai.com.

````