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

# Update phone number

> Update a phone number properties, this can be used to change the name, assign an inbound agent or enable/disable redirect.
The response includes the updated phone number details and headers about rate limiting.



## OpenAPI

````yaml /api-reference-v1/openapi.json patch /v1/phone-numbers/{phone_number_id}
openapi: 3.1.0
info:
  title: Rounded API
  description: Rounded API
  version: 1.0.0
servers:
  - url: https://api.callrounded.com
security:
  - ApiKeyHeader: []
paths:
  /v1/phone-numbers/{phone_number_id}:
    patch:
      tags:
        - phone-numbers
        - phone-numbers
      summary: Update phone number
      description: >-
        Update a phone number properties, this can be used to change the name,
        assign an inbound agent or enable/disable redirect.

        The response includes the updated phone number details and headers about
        rate limiting.
      operationId: update_phone_number_v1_phone_numbers__phone_number_id__patch
      parameters:
        - name: phone_number_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: The ID of the phone number to update.
            title: Phone Number Id
          description: The ID of the phone number to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberUpdateApiRequest'
              description: The phone number data to update.
      responses:
        '200':
          description: Successfully updated phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberUpdateApiResponse-Input'
          headers:
            ratelimit-limit:
              description: The number of requests allowed in the current rate limit period
              schema:
                type: integer
            ratelimit-remaining:
              description: >-
                The number of requests remaining in the current rate limit
                period
              schema:
                type: integer
            x-ratelimit-limit-minute:
              description: >-
                The number of requests allowed in the current minute window, if
                rate limit is set to minutes.
              schema:
                type: integer
            x-ratelimit-remaining-minute:
              description: >-
                The number of requests remaining in the current minute window,
                if rate limit is set to minutes.
              schema:
                type: integer
            x-ratelimit-limit-hour:
              description: >-
                The number of requests allowed in the current hour window, if
                rate limit is set to hourly.
              schema:
                type: integer
            x-ratelimit-remaining-hour:
              description: >-
                The number of requests remaining in the current hour window, if
                rate limit is set to hourly.
              schema:
                type: integer
            x-ratelimit-limit-<seconds>:
              description: >-
                The number of requests allowed in the current <seconds> window,
                where <seconds> is the number of seconds, if rate limit is set
                to seconds.
              schema:
                type: integer
            x-ratelimit-remaining-<seconds>:
              description: >-
                The number of requests remaining in the current <seconds>
                window, where <seconds> is the number of seconds, if rate limit
                is set to seconds.
              schema:
                type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: Bad request
                  type: api_error
                  status: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              examples:
                auth_error:
                  summary: Error from the API Service
                  value:
                    message: Unauthorized
                    type: auth_error
                    status: 401
                gateway_error:
                  summary: Error from the API Gateway
                  value:
                    message: Unauthorized
                    type: gateway_auth_error
                    status: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: Access forbidden
                  type: api_error
                  status: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: The request endpoint does not exist
                  type: http_error
                  status: 404
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: Invalid request body
                  type: validation_error
                  status: 422
                  details:
                    - field: email
                      message: Invalid email format
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: API rate limit exceeded
                  type: gateway_rate_limit_error
                  status: 429
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: An unexpected error occurred
                  type: generic_error
                  status: 500
components:
  schemas:
    PhoneNumberUpdateApiRequest:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: The phone number friendly name.
        inbound_agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Inbound Agent Id
          description: The agent ID that will handle incoming calls to this phone number.
        redirect:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Redirect
          description: Whether to redirect the phone number.
          default: false
        redirect_phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Phone Number
          description: The phone number to redirect to.
      type: object
      title: PhoneNumberUpdateApiRequest
    PhoneNumberUpdateApiResponse-Input:
      properties:
        message:
          type: string
          title: Message
        data:
          anyOf:
            - $ref: '#/components/schemas/PhoneNumberPstnGetApiResponseData'
            - $ref: '#/components/schemas/PhoneNumberSipGetApiResponseData'
          title: Data
        error:
          anyOf:
            - $ref: '#/components/schemas/ApiResponseError'
            - type: 'null'
        status:
          type: integer
          title: Status
          description: HTTP status code of the response.
          default: 200
      type: object
      required:
        - message
        - data
      title: PhoneNumberUpdateApiResponse
    ApiResponseError:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        status:
          type: integer
          title: Status
        details:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiResponseErrorDetail'
              type: array
            - type: 'null'
          title: Details
      type: object
      required:
        - message
        - type
        - status
      title: ApiResponseError
      example:
        details:
          - field: email
            message: Invalid email format
        message: An error occurred while processing your request
        status: 400
        type: generic_error
    PhoneNumberPstnGetApiResponseData:
      properties:
        type:
          type: string
          const: pstn
          title: Type
          default: pstn
        id:
          type: string
          format: uuid
          title: Id
          description: The ID of the phone number.
        number:
          type: string
          title: Number
          description: The phone number.
        name:
          type: string
          title: Name
          description: The phone number friendly name.
        inbound_agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Inbound Agent Id
          description: The agent ID that will handle incoming calls to this phone number.
        redirect:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Redirect
          description: >-
            Whether to redirect the phone number. If true, any calls to this
            phone number will be redirected to the `redirect_phone_number`
            overriding the agent assignment.
          default: false
        redirect_phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Phone Number
          description: The phone number to redirect to.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time the phone number was created.
      type: object
      required:
        - id
        - number
        - name
        - created_at
      title: PSTN Phone Number
    PhoneNumberSipGetApiResponseData:
      properties:
        type:
          type: string
          const: sip
          title: Type
          default: sip
        id:
          type: string
          format: uuid
          title: Id
          description: The ID of the phone number.
        number:
          type: string
          title: Number
          description: The phone number friendly name.
        name:
          type: string
          title: Name
          description: The phone number friendly name.
        inbound_agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Inbound Agent Id
          description: The agent ID that will handle incoming calls to this phone number.
        termination_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Termination Uri
          description: The SIP termination URI to use for outbound calls.
        termination_username:
          anyOf:
            - type: string
            - type: 'null'
          title: Termination Username
          description: The username used to authenticate with the SIP termination URI.
        origination_username:
          anyOf:
            - type: string
            - type: 'null'
          title: Origination Username
          description: >-
            The allowed username to accept inbound calls for this SIP trunk, by
            default no username is required.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time the phone number was created.
      type: object
      required:
        - id
        - number
        - name
        - termination_uri
        - termination_username
        - origination_username
        - created_at
      title: SIP Phone Number
    ApiResponseErrorDetail:
      properties:
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ApiResponseErrorDetail
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        The API Key created in [Rounded Studio](https://app.callrounded.com).

        - You can create it by going to the "API Keys" settings of your profile.

        - Need help? You can email us at
        [team@callrounded.com](mailto:team@callrounded.com) or join our [Discord
        community](https://discord.gg/en537j5z75).

````