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

# Assign agent to SIP trunk number API

> Set or clear the agent that answers inbound calls to a SIP trunk number via PATCH /trunk/numbers/{number_id}.

<Warning>
  An empty body clears the number's agent, the same as `{"agent_id": null}`. Calls to a number with no agent go to the trunk's `default_inbound_agent_id`, and are refused when that is not set either.
</Warning>


## OpenAPI

````yaml PATCH /trunk/numbers/{number_id}
openapi: 3.1.0
info:
  title: Bolna API
  description: >-
    Use and leverage Bolna Voice AI using APIs through HTTP requests from any
    language in your applications and workflows.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.bolna.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: SIP trunks
    description: >-
      Bring-your-own-carrier SIP trunks, their gateways, carrier IPs and
      numbers.
paths:
  /trunk/numbers/{number_id}:
    patch:
      tags:
        - SIP trunks
      description: >
        Assigns the agent that answers inbound calls to a trunk number, or
        clears it with `"agent_id": null`.


        A number without an agent is answered by its trunk's
        `default_inbound_agent_id`. When neither is set, inbound calls to the
        number are refused with SIP `404`.


        `agent_id` is the only field this endpoint changes, and omitting it
        clears the assignment just as `null` does.
      parameters:
        - in: path
          name: number_id
          required: true
          schema:
            type: string
            format: uuid
          description: The number's `id`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrunkNumberAgentRequest'
            examples:
              assign:
                summary: Assign an agent
                value:
                  agent_id: 123e4567-e89b-12d3-a456-426614174000
              clear:
                summary: Clear the assignment
                value:
                  agent_id: null
      responses:
        '200':
          description: The updated number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrunkNumber'
        '400':
          description: >-
            `agent_id` is not one of your agents. The agent must belong to your
            organisation and to the same sub-account as the number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrunkMessageError'
              example:
                message: agent not in tenant
        '404':
          description: No live number with this ID belongs to your account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrunkMessageError'
              example:
                message: trunk_numbers:5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9
        '422':
          description: The body has an unknown field, or `number_id` is not a UUID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrunkValidationError'
components:
  schemas:
    TrunkNumberAgentRequest:
      type: object
      properties:
        agent_id:
          type: string
          nullable: true
          description: >-
            Agent that answers inbound calls to this number. `null`, or leaving
            the field out, clears the assignment.
          example: 123e4567-e89b-12d3-a456-426614174000
    TrunkNumber:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9
        trunk_id:
          type: string
          format: uuid
          example: 3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21
        e164:
          type: string
          example: '+12025550143'
        destination_key:
          type: string
          example: '12025550143'
        agent_id:
          type: string
          nullable: true
          description: >-
            Agent that answers inbound calls to this number. When `null`, the
            trunk's `default_inbound_agent_id` answers.
          example: 123e4567-e89b-12d3-a456-426614174000
        last_inbound_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When this number last took an inbound call, updated at most once a
            minute.
        last_outbound_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When an outbound call was last placed from this number, updated at
            most once a minute.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_deleted:
          type: boolean
        deleted_at:
          type: string
          format: date-time
          nullable: true
    TrunkMessageError:
      type: object
      description: >-
        Error body for `400`, `403` and `404` responses from the SIP trunk
        endpoints.
      required:
        - message
      properties:
        message:
          type: string
          description: >-
            Human-readable reason. On a `404` it names the ID that was not
            found.
    TrunkValidationError:
      type: object
      description: >-
        Error body for `422` responses from the SIP trunk endpoints. The
        rejected input is never echoed back.
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
                description: Where the error is, such as `["body", "channels"]`.
              msg:
                type: string
                description: What is wrong.
              type:
                type: string
                description: >-
                  Pydantic error type, such as `value_error` or
                  `less_than_equal`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.