Documentation

Update Phone Number

Update label, inbound binding, or activation state of a phone number

Update label, inbound binding, or activation state of a phone number

Changing inbound_workflow_id re-syncs the inbound webhook with the provider; the response includes a provider_sync block with the result.

To remove an existing inbound binding, send clear_inbound_workflow: true. Sending inbound_workflow_id: null alone is treated as "no change".

Quick reference#

Update label, inbound binding, or activation state of a phone number. Send the request to PUT /api/v1/organizations/telephony-configs/{configid}/phone-numbers/{phonenumberid} on the Paladin API base URL.

Method	`PUT`
Path	`/api/v1/organizations/telephony-configs/{configid}/phone-numbers/{phonenumberid}`
Path parameters	configid, phonenumberid
Authentication	Use the authentication method shown in the OpenAPI block and the Authentication docs. Keep API keys server-side.

Before you call#

Confirm you are using the production base URL shown in the API reference.
Make sure any path IDs belong to the same Paladin organization as the credential you are using.
Validate request bodies and required fields before sending production traffic.

Common error checks#

Use 401 or 403 responses to check credentials, organization scope, and permissions.
Use 404 responses to check whether the referenced resource exists in the current organization.
Use 422 responses to inspect missing or invalid request fields.

OpenAPI#

PUT /api/v1/organizations/telephony-configs/{configid}/phone-numbers/{phonenumberid}

openapi: 3.1.0
info:
  title: Paladin API
  description: API for the Paladin app
  version: 1.0.0
servers:
  - url: https://app.paladin.northmanngrp.com
    description: Production

security: []
paths:
  /api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}:
    put:
      tags:
        - main
        - organizations
      summary: Update Phone Number
      operationId: >-
        update_phone_number_api_v1_organizations_telephony_configs__config_id__phone_numbers__phone_number_id__put
      parameters:
        - name: config_id
          in: path
          required: true
          schema:
            type: integer
            title: Config Id
        - name: phone_number_id
          in: path
          required: true
          schema:
            type: integer
            title: Phone Number Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PhoneNumberUpdateRequest:
      properties:
        label:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Label
        inbound_workflow_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Inbound Workflow Id
        clear_inbound_workflow:
          type: boolean
          title: Clear Inbound Workflow
          default: false
        is_active:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Active
        country_code:
          anyOf:
            - type: string
              maxLength: 2
              minLength: 2
            - type: 'null'
          title: Country Code
        extra_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extra Metadata
      type: object
      title: PhoneNumberUpdateRequest
      description: |-
        Partial update. ``address`` is intentionally immutable — to change a
        number, delete the row and create a new one.
    PhoneNumberResponse:
      properties:
        id:
          type: integer
          title: Id
        telephony_configuration_id:
          type: integer
          title: Telephony Configuration Id
        address:
          type: string
          title: Address
        address_normalized:
          type: string
          title: Address Normalized
        address_type:
          type: string
          title: Address Type
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        inbound_workflow_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Inbound Workflow Id
        inbound_workflow_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Workflow Name
        is_active:
          type: boolean
          title: Is Active
        is_default_caller_id:
          type: boolean
          title: Is Default Caller Id
        extra_metadata:
          additionalProperties: true
          type: object
          title: Extra Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        provider_sync:
          anyOf:
            - $ref: '#/components/schemas/ProviderSyncStatus'
            - type: 'null'
      type: object
      required:
        - id
        - telephony_configuration_id
        - address
        - address_normalized
        - address_type
        - is_active
        - is_default_caller_id
        - extra_metadata
        - created_at
        - updated_at
      title: PhoneNumberResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProviderSyncStatus:
      properties:
        ok:
          type: boolean
          title: Ok
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
      type: object
      required:
        - ok
      title: ProviderSyncStatus
      description: |-
        Result of pushing a phone-number change to the upstream provider.

        Returned alongside create/update responses when the route attempted to
        sync inbound webhook configuration. ``ok=False`` is a warning, not a
        fatal error — the DB write succeeded.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError