openapi: 3.2.0
info:
  title: 8x8 Administration - Phone Number Management Phone Numbers API
  version: '1.0'
  description: 'Phone number management API providing endpoints to list and retrieve phone numbers.


    The current version of the API is v1.0.


    ## Authentication


    All requests to this API require authentication using an API key. Include your API key in the request header:


    ```

    x-api-key: YOUR_API_KEY

    ```


    ## Versioning


    Specify the API version using the `Accept` header:


    ```

    Accept: application/vnd.phonenumbers.v1+json

    ```


    ## Base URL


    `https://api.8x8.com/admin-provisioning`


    ## Endpoints


    | Endpoint | Method | Purpose | Async? |

    |----------|--------|---------|--------|

    | `/phone-numbers` | GET | Retrieve paginated list of phone numbers with filtering | No |

    | `/phone-numbers/{phoneNumber}` | GET | Retrieve a specific phone number''s details | No |


    ## OpenAPI Specification


    Download the complete OpenAPI specification: [phonenumber-api-v1.yaml](/administration/phonenumber-api-v1.yaml)

    '
servers:
- url: https://api.8x8.com/admin-provisioning
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: PhoneNumbers
paths:
  /phone-numbers:
    get:
      operationId: listPhoneNumbers
      summary: List phone numbers
      description: 'List phone numbers with optional filtering, sorting, and infinite scroll pagination.

        Uses scrollId-based pagination for efficient navigation through large datasets.


        Phone numbers must be in E.164 format (e.g., +14085551234).

        '
      tags:
      - PhoneNumbers
      parameters:
      - name: X-Request-Id
        in: header
        description: Optional request identifier for tracking
        required: false
        schema:
          type: string
          format: uuid
      - name: pageSize
        in: query
        description: 'Number of items per page (default: 100)'
        required: false
        schema:
          type: integer
          example: 100
      - name: scrollId
        in: query
        description: Scroll identifier for retrieving the next page of results
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: RSQL filter expression (e.g., 'phoneNumber==+14085551234', 'status==AVAILABLE;country==US')
        required: false
        schema:
          type: string
          example: status==AVAILABLE
      - name: sort
        in: query
        description: Sort expression. Use '+' prefix or no prefix for ascending order, '-' prefix for descending order (e.g., 'phoneNumber', '+phoneNumber', or '-phoneNumber')
        required: false
        schema:
          type: string
          example: phoneNumber
      responses:
        '200':
          description: Successful response with paginated phone numbers
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/PhoneNumberPage'
              example:
                data:
                - phoneNumber: '+14085551234'
                  nationalFormattedNumber: (408) 555-1234
                  country: US
                  category: LOCAL
                  origin: CLAIMED
                  status: AVAILABLE
                pagination:
                  pageSize: 100
                  hasMore: false
        '400':
          description: Bad Request - Invalid query parameters or filter syntax
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidSort:
                  summary: Invalid sort parameter
                  value:
                    status: 400
                    title: Validation error
                    errors:
                    - code: VALIDATION_ERROR
                      field: sort
                      message: Invalid sort parameter
                invalidFilter:
                  summary: Invalid filter syntax
                  value:
                    status: 400
                    title: Validation error
                    errors:
                    - code: VALIDATION_ERROR
                      field: filter
                      message: Invalid filter syntax
                invalidScrollId:
                  summary: Invalid scroll ID
                  value:
                    status: 400
                    title: Validation error
                    errors:
                    - code: VALIDATION_ERROR
                      field: scrollId
                      message: Invalid scroll identifier
                conflictingParameters:
                  summary: Conflicting query parameters
                  value:
                    status: 400
                    title: Conflicting query parameters
                    errors:
                    - code: CONFLICTING_QUERY_PARAMETER
                      message: Cannot use scrollId with other first-page query parameters
        '403':
          description: Forbidden - Customer ID mismatch or insufficient permissions
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                title: Forbidden
                errors:
                - code: FORBIDDEN
                  message: Access denied to this resource
        '408':
          description: Request Timeout - Downstream service timeout
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 408
                title: Request Timeout
                errors:
                - code: REQUEST_TIMEOUT
                  message: Request to downstream service timed out
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: Service unavailable
                errors:
                - code: SERVICE_UNAVAILABLE
                  message: Service unavailable
        '429':
          description: Too Many Requests - Rate limit exceeded
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                title: Too Many Requests
                errors:
                - code: TOO_MANY_REQUESTS
                  message: Rate limit exceeded, please try again later
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: Internal Server Error
                errors:
                - code: UNKNOWN
                  message: An unexpected error occurred
  /phone-numbers/{phoneNumber}:
    get:
      operationId: getPhoneNumber
      summary: Get phone number by ID
      description: 'Retrieve a specific phone number by its value.

        The phone number must be in E.164 format (e.g., +14085551234).

        '
      tags:
      - PhoneNumbers
      parameters:
      - name: X-Request-Id
        in: header
        description: Optional request identifier for tracking
        required: false
        schema:
          type: string
          format: uuid
      - name: phoneNumber
        in: path
        description: Phone number in E.164 format (e.g., +14085551234)
        required: true
        schema:
          type: string
          pattern: ^\+\d+$
          example: '+14085551234'
      responses:
        '200':
          description: Phone number retrieved successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
              example:
                phoneNumber: '+14085551234'
                nationalFormattedNumber: (408) 555-1234
                country: US
                category: LOCAL
                origin: CLAIMED
                status: AVAILABLE
        '400':
          description: Bad Request - Invalid phone number format
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                title: Invalid phone number
                detail: Invalid phone number 4085551234
                errors:
                - field: phoneNumber
                  code: VALIDATION_ERROR
                  message: Invalid phone number 4085551234
        '403':
          description: Forbidden - Customer ID mismatch or insufficient permissions
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                title: Forbidden
                errors:
                - code: FORBIDDEN
                  message: Access denied to this resource
        '404':
          description: Not Found - Phone number does not exist
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                title: Phone number not found
                errors:
                - code: NOT_FOUND
                  message: 'Phone number not found: customerId: CUST123 phoneNumber: +14085551234'
        '408':
          description: Request Timeout - Downstream service timeout
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 408
                title: Request Timeout
                errors:
                - code: REQUEST_TIMEOUT
                  message: Request to downstream service timed out
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: Service unavailable
                errors:
                - code: SERVICE_UNAVAILABLE
                  message: Service unavailable
        '429':
          description: Too Many Requests - Rate limit exceeded
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                title: Too Many Requests
                errors:
                - code: TOO_MANY_REQUESTS
                  message: Rate limit exceeded, please try again later
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.phonenumbers.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: Internal Server Error
                errors:
                - code: UNKNOWN
                  message: An unexpected error occurred
components:
  schemas:
    PhoneNumberPage:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PhoneNumber'
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    PhoneNumber:
      type: object
      properties:
        category:
          type:
          - string
          - 'null'
          enum:
          - LOCAL
          - TOLL_FREE
          description: The type of number, either LOCAL or TOLL_FREE
          example: LOCAL
        country:
          type:
          - string
          - 'null'
          description: ISO:3166-2 two-character country code
          example: US
        nationalFormattedNumber:
          type:
          - string
          - 'null'
          description: The number formatted for dialling within its home country
          example: (408) 555-1234
        origin:
          type:
          - string
          - 'null'
          enum:
          - PORTING
          - CLAIMED
          description: Source of the number
          example: CLAIMED
        phoneNumber:
          type:
          - string
          - 'null'
          description: The phone number
          example: '+14085551234'
          pattern: ^\+\d+$
        portingNumber:
          type:
          - string
          - 'null'
          description: During the porting process, a number to be ported can be linked to a temporary number which will be swapped out when the porting process completes
          example: '+14085551234'
        temporaryNumber:
          type:
          - string
          - 'null'
          description: During the porting process, a number to be ported can be linked to a temporary number which will be swapped out when the porting process completes
          example: '+14085551234'
        status:
          type:
          - string
          - 'null'
          enum:
          - PRE_PORTING
          - PORTING
          - AVAILABLE
          - ASSIGNED
          description: PRE_PORTING means linked to a temporary number but porting process has not started. PORTING means the porting process is underway. AVAILABLE means ready to be assigned to a service, e.g. a user or ring group. ASSIGNED means number is in-use by a service
          example: AVAILABLE
    Pagination:
      type: object
      properties:
        pageSize:
          type:
          - integer
          - 'null'
          description: Number of items per page
          example: 100
        pageNumber:
          type:
          - integer
          - 'null'
          description: Current page number (0-indexed)
          example: 0
        hasMore:
          type:
          - boolean
          - 'null'
          description: Indicates if there are more pages available
          example: false
        filter:
          type:
          - string
          - 'null'
          description: RSQL filter expression used in the request
          example: status==AVAILABLE
        sort:
          type:
          - string
          - 'null'
          description: Sort expression used in the request
          example: phoneNumber
        nextScrollId:
          type:
          - string
          - 'null'
          description: Scroll ID for retrieving the next page
    Error:
      type: object
      properties:
        field:
          type:
          - string
          - 'null'
          description: Field name related to the error
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type:
          - string
          - 'null'
          description: Detailed error message
          example: Phone number not found
    PaginationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    ErrorCode:
      type: string
      enum:
      - UNKNOWN
      - VALIDATION_ERROR
      - FORBIDDEN
      - CONFLICTING_QUERY_PARAMETER
      - SERVICE_UNAVAILABLE
      - NOT_FOUND
      - BAD_REQUEST
      - REQUEST_TIMEOUT
      - TOO_MANY_REQUESTS
      - CONFLICT
      description: Error code indicating the type of error
    Link:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL for the link
          example: https://api.8x8.com/admin-provisioning/phone-numbers?pageSize=100
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          description: HTTP status code
          example: 404
        instance:
          type:
          - string
          - 'null'
          description: URI reference that identifies the specific occurrence of the problem
        time:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the error occurred
          example: '2025-01-01T01:02:03Z'
        title:
          type:
          - string
          - 'null'
          description: Short, human-readable summary of the problem
          example: Phone number not found
        detail:
          type:
          - string
          - 'null'
          description: Human-readable explanation specific to this occurrence
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key