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. Resources can be associated together to provide additional functionality. For example: By associating a voicemail with a user, calls will automatically fallback on to the voicemail when the user cannot answer.\n\nImplementation notes\n====================\n\nErrors\n------\n\nResponses containing errors will have a status code in the 400 or 500 class. A list of error messages will be returned in the body of the response as a JSON-encoded array:\n\n~~~\n[\n    \"Input error - User not found\",\n    \"Resource error - User not associated to a line\"\n]\n~~~\n\n\nUpdating resources via PUT\n--------------------------\n\nWhen updating a resource, all fields become optional. In other words, only values that have been changed need to be sent to the server. Please note that this behavior may change in future versions of the API."
  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:
  responses:
    NotFoundError:
      description: The resource requested was not found on the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceDeleted:
      description: Resource was deleted successfully
    ResourceUpdated:
      description: Resource was updated successfully
    CreateError:
      description: An error occurred when creating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpdateError:
      description: An error occurred when updating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    tenantuuid:
      name: Wazo-Tenant
      in: header
      description: The tenant's UUID, defining the ownership of a given resource.
      required: false
      schema:
        type: string
    phone_number_uuid:
      name: phone_number_uuid
      in: path
      description: UUID of the phone number
      required: true
      schema:
        type: string
    shared:
      in: query
      name: shared
      description: Only include shared phone numbers
      schema:
        type: boolean
    offset:
      required: false
      name: offset
      in: query
      description: Number of items to skip over in the list. Useful for pagination.
      schema:
        type: integer
    main:
      in: query
      name: main
      description: Only include the main phone number of the tenant
      schema:
        type: boolean
    order:
      required: false
      name: order
      in: query
      description: Name of the field to use for sorting the list of items returned.
      schema:
        type: string
    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
    recurse:
      name: recurse
      in: query
      description: Should the query include sub-tenants
      required: false
      schema:
        type: boolean
        default: false
    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
    limit:
      required: false
      name: limit
      in: query
      description: Maximum number of items to return in the list
      schema:
        type: integer
  schemas:
    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
    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
    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'
    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
    Error:
      type: array
      items:
        type: string
  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'