Wazo Phone Numbers API

openapi: 3.2.0
info:
  title: wazo-confd Phone Numbers API
  description: Confd exposes an API for managing core resources on a Wazo server such as users, extensions, devices, voicemails, queues, etc.
  version: '1.1'
  license:
    name: GPL v3
    url: http://www.gnu.org/licenses/gpl.txt
  contact:
    name: Wazo Dev Team
    url: https://wazo-platform.org/
    email: dev@wazo.community
  x-logo:
    url: https://wazo-platform.org/images/logo-black.svg
    backgroundColor: '#FAFAFA'
    altText: Wazo Logo
servers:
- url: /1.1
security:
- wazo_auth_token: []
tags:
- name: Phone Numbers
paths:
  /phone-numbers:
    get:
      operationId: list_phone_numbers
      summary: List phone numbers
      description: '**Required ACL:** `confd.phone-numbers.read`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/recurse'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/shared'
      - $ref: '#/components/parameters/main'
      responses:
        '200':
          description: Phone number list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberItems'
    post:
      operationId: create_phone_number
      summary: Add a new phone number
      description: '**Required ACL:** `confd.phone-numbers.create`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      responses:
        '201':
          description: Phone number created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '400':
          $ref: '#/components/responses/CreateError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumber'
        description: specification of the phone number to create
        required: true
  /phone-numbers/ranges:
    post:
      operationId: create_phone_numbers_range
      summary: Add a range of phone numbers
      description: '**Required ACL:** `confd.phone-numbers.create`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      responses:
        '201':
          description: Phone number created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberRangeResponse'
        '400':
          $ref: '#/components/responses/CreateError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberRange'
        description: specification of the phone number range to create
        required: true
  /phone-numbers/{phone_number_uuid}:
    get:
      operationId: get_phone_number
      summary: Get phone number
      description: '**Required ACL:** `confd.phone-numbers.{phone_number_uuid}.read`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/phone_number_uuid'
      responses:
        '200':
          description: Phone Number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: update_phone_numbers
      summary: Update Phone Number
      description: '**Required ACL:** `confd.phone-numbers.{phone_number_uuid}.update`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/phone_number_uuid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceUpdated'
        '400':
          $ref: '#/components/responses/UpdateError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberItems'
        required: true
    delete:
      operationId: delete_phone_number
      summary: Delete Phone Number
      description: '**Required ACL:** `confd.phone-numbers.{phone_number_uuid}.delete`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/phone_number_uuid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceDeleted'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /phone-numbers/main:
    get:
      operationId: get_phone_number_main
      summary: Get main phone number
      description: '**Required ACL:** `confd.phone-numbers.main.read`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      responses:
        '200':
          description: main phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '404':
          description: main phone number not found
          content:
            application/json:
              schema:
                $ref: '#/components/responses/NotFoundError'
    put:
      operationId: set_phone_number_main
      summary: set the 'main' phone number for the tenant
      description: '**Required ACL:** `confd.phone-numbers.main.update`'
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceUpdated'
        '400':
          $ref: '#/components/responses/UpdateError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - phone_number_uuid
              properties:
                phone_number_uuid:
                  type: string
                  description: UUID of the phone number to set as main
                  example: b5bcc98c-10cf-4a68-bf3d-802fb5170911
        description: specification of the phone number to set as main
        required: true
components:
  parameters:
    offset:
      required: false
      name: offset
      in: query
      description: Number of items to skip over in the list. Useful for pagination.
      schema:
        type: integer
    direction:
      required: false
      name: direction
      in: query
      description: Sort list of items in 'asc' (ascending) or 'desc' (descending) order
      schema:
        type: string
        enum:
        - asc
        - desc
    phone_number_uuid:
      name: phone_number_uuid
      in: path
      description: UUID of the phone number
      required: true
      schema:
        type: string
    order:
      required: false
      name: order
      in: query
      description: Name of the field to use for sorting the list of items returned.
      schema:
        type: string
    limit:
      required: false
      name: limit
      in: query
      description: Maximum number of items to return in the list
      schema:
        type: integer
    search:
      required: false
      name: search
      in: query
      description: Search term for filtering a list of items. Only items with a field containing the search term will be returned.
      schema:
        type: string
    recurse:
      name: recurse
      in: query
      description: Should the query include sub-tenants
      required: false
      schema:
        type: boolean
        default: false
    main:
      in: query
      name: main
      description: Only include the main phone number of the tenant
      schema:
        type: boolean
    tenantuuid:
      name: Wazo-Tenant
      in: header
      description: The tenant's UUID, defining the ownership of a given resource.
      required: false
      schema:
        type: string
    shared:
      in: query
      name: shared
      description: Only include shared phone numbers
      schema:
        type: boolean
  schemas:
    PhoneNumber:
      type: object
      description: a phone number resource, usable for outgoing caller id or incall routing
      properties:
        uuid:
          type: string
          description: Number UUID
          readOnly: true
        number:
          type: string
          description: The phone number text (in e.164 representation if possible)
        caller_id_name:
          type: string
          description: The Caller ID name that should be used when calling with this number as a Caller ID
        tenant_uuid:
          type: string
          description: uuid of tenant
          readOnly: true
        shared:
          type: boolean
          description: Whether or not this number is meant to be shared by multiple people
        main:
          type: boolean
          description: "Whether or not this is the main / default phone number for this tenant. \nOnly one number can be the main number for a given tenant.\n"
          default: false
          readOnly: true
      required:
      - number
      - shared
    Link:
      title: Link
      description: a pointer to a linked resource related in some way to the current resource
      properties:
        href:
          type: string
          description: The URL of the link
        rel:
          type: string
          description: The relationship of the link relative to the current resource
    PhoneNumberRangeResponse:
      type: object
      properties:
        created:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                description: Phone Number UUID
                readOnly: true
        links:
          type: array
          description: 'links to related resources

            include URLs of any registered phone number that are part of this range

            '
          items:
            $ref: '#/components/schemas/Link'
    Error:
      type: array
      items:
        type: string
    PhoneNumberItems:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
    PhoneNumberRange:
      type: object
      description: a request to register a range of phone number resources
      properties:
        start_number:
          type: string
          description: 'the first phone number part of a contiguous range of numbers to be registered in the `/phone-numbers` resource;

            a e.164 phone number, otherwise a phone number string part of a numbering plan dialable on the trunk network

            '
        end_number:
          type: string
          description: 'The last phone number part of the contiguous range to be registered in the `/phone-numbers` resource;

            a e.164 phone number, otherwise a phone number string part of a numbering plan dialable on the trunk network

            '
      required:
      - start_number
      - end_number
  responses:
    NotFoundError:
      description: The resource requested was not found on the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceUpdated:
      description: Resource was updated successfully
    UpdateError:
      description: An error occurred when updating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CreateError:
      description: An error occurred when creating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceDeleted:
      description: Resource was deleted successfully
  securitySchemes:
    wazo_auth_token:
      type: apiKey
      name: X-Auth-Token
      in: header
x-xivo-port: 9486
x-xivo-name: confd
x-apievangelist-source:
  harvested_from: https://github.com/wazo-platform/wazo-confd
  assembly: base plugin api.yml deep-merged with all plugin api.yml fragments, reproducing what the running service serves at /api/confd/1.1/api/api.yml (see wazo_confd/plugins/api/http.py — xivo.chain_map.ChainMap)
  spec_version: Swagger 2.0 (as published by Wazo)
  harvested: '2026-08-17'