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

# Assign or update a phone number on a target user (SuperAdmin only)

> Adds or upserts a voice phone-number assignment on the target user for the given provider, atomically scoped by organizationId so the user must still belong to the org. Validates the provider and ObjectId formats. Requires SUPERADMIN.



## OpenAPI

````yaml /api-reference/openapi.yaml post /api/organizations/{organizationId}/phone-numbers
openapi: 3.0.3
info:
  title: Tether Relay and Tether API
  version: 1.0.0
  description: >-
    Route-derived OpenAPI contract generated from tether-relay backend sources.
    Regenerate with scripts/sync-openapi-from-backend.mjs.
servers:
  - url: https://your-instance.example.com
    description: Production
  - url: http://localhost:2212
    description: Local API service
security: []
tags:
  - name: AI
  - name: Applications
  - name: Approval
  - name: Auth
  - name: Automations
  - name: Calls
  - name: Campaigns
  - name: Contact Analytics
  - name: Contact Metrics
  - name: Contact Notes
  - name: Contacts
  - name: Conversation Monitor
  - name: Conversations
  - name: Departments
  - name: Email
  - name: Escalation Dashboard
  - name: Event Logs
  - name: Google Sheets
  - name: Marketplace
  - name: Messages
  - name: Notification Sounds
  - name: Notifications
  - name: Org Snapshots
  - name: Organizations
  - name: Outreach
  - name: Outreach Metrics
  - name: Outreach Sources
  - name: Pipelines
  - name: Processes
  - name: Prompts
  - name: Reminders
  - name: Sms
  - name: Templates
  - name: Traces
  - name: Training
  - name: Upload
  - name: User Snapshots
  - name: Users
  - name: Vertical
  - name: Webchats
  - name: Webhook
paths:
  /api/organizations/{organizationId}/phone-numbers:
    post:
      tags:
        - Organizations
      summary: Assign or update a phone number on a target user (SuperAdmin only)
      description: >-
        Adds or upserts a voice phone-number assignment on the target user for
        the given provider, atomically scoped by organizationId so the user must
        still belong to the org. Validates the provider and ObjectId formats.
        Requires SUPERADMIN.
      operationId: post_organizations_phone_numbers
      parameters:
        - in: path
          name: organizationId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgAssignPhoneNumberRequest'
      responses:
        '200':
          description: Phone number assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgPhoneNumberMutationResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationErrorResponse'
        '404':
          description: Target user not found in organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationErrorResponse'
        '500':
          description: Failed to assign phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    OrgAssignPhoneNumberRequest:
      type: object
      properties:
        targetUserId:
          type: string
          description: >-
            User in the organization who should receive the phone-number
            assignment; must belong to the calling org.
        provider:
          type: string
          description: 'Voice provider for this number: `twilio`, `sinch`, or `textgrid`.'
        phoneNumber:
          type: string
          description: Phone number to assign in E.164 format (e.g. +14165550102).
        isDefault:
          type: boolean
          description: >-
            When true, makes this the user's default outbound number for the
            given provider (defaults to true if omitted).
        isInboundEnabled:
          type: boolean
          description: >-
            When true, routes inbound calls/SMS for this number to the user
            (defaults to true if omitted).
        label:
          type: string
          description: >-
            Optional human-readable label shown alongside the number in the UI
            (e.g. "Main Outbound").
      required:
        - targetUserId
        - provider
        - phoneNumber
      additionalProperties: true
      example:
        targetUserId: 5f7b1c2e8a1d4e0012c3b4a6
        provider: twilio
        phoneNumber: '+14165550102'
        isDefault: true
        isInboundEnabled: true
        label: Main Outbound
    OrgPhoneNumberMutationResponse:
      type: object
      description: >-
        Returned by `POST` (assign) and `DELETE` (remove) phone-number
        endpoints.
      properties:
        success:
          type: boolean
          enum:
            - true
        message:
          type: string
      required:
        - success
        - message
      additionalProperties: true
      example:
        success: true
        message: twilio phone number assigned
    OrganizationErrorResponse:
      type: object
      properties:
        error:
          type: string
        details:
          type: string
      additionalProperties: true
      example:
        error: Organization not found
        details: No organization exists with the provided id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````