openapi: 3.0.0
info:
  title: 8x8 Administration - Phone Number Management 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: []
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:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    PhoneNumber:
      type: object
      properties:
        category:
          type: string
          enum: [LOCAL, TOLL_FREE]
          description: "The type of number, either LOCAL or TOLL_FREE"
          example: "LOCAL"
          nullable: true
        country:
          type: string
          description: "ISO:3166-2 two-character country code"
          example: "US"
          nullable: true
        nationalFormattedNumber:
          type: string
          description: "The number formatted for dialling within its home country"
          example: "(408) 555-1234"
          nullable: true
        origin:
          type: string
          enum: [PORTING, CLAIMED]
          description: "Source of the number"
          example: "CLAIMED"
          nullable: true
        phoneNumber:
          type: string
          description: "The phone number"
          example: "+14085551234"
          pattern: '^\+\d+$'
          nullable: true
        portingNumber:
          type: string
          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"
          nullable: true
        temporaryNumber:
          type: string
          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"
          nullable: true
        status:
          type: string
          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"
          nullable: true
    PhoneNumberPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          nullable: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    Pagination:
      type: object
      properties:
        pageSize:
          type: integer
          description: Number of items per page
          example: 100
          nullable: true
        pageNumber:
          type: integer
          description: Current page number (0-indexed)
          example: 0
          nullable: true
        hasMore:
          type: boolean
          description: Indicates if there are more pages available
          example: false
          nullable: true
        filter:
          type: string
          description: RSQL filter expression used in the request
          example: "status==AVAILABLE"
          nullable: true
        sort:
          type: string
          description: Sort expression used in the request
          example: "phoneNumber"
          nullable: true
        nextScrollId:
          type: string
          description: Scroll ID for retrieving the next page
          nullable: true
    PaginationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        href:
          type: string
          description: URL for the link
          example: "https://api.8x8.com/admin-provisioning/phone-numbers?pageSize=100"
          nullable: true
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 404
          nullable: true
        instance:
          type: string
          description: URI reference that identifies the specific occurrence of the problem
          nullable: true
        time:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: "2025-01-01T01:02:03Z"
          nullable: true
        title:
          type: string
          description: Short, human-readable summary of the problem
          example: "Phone number not found"
          nullable: true
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          nullable: true
    Error:
      type: object
      properties:
        field:
          type: string
          description: Field name related to the error
          nullable: true
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Detailed error message
          example: "Phone number not found"
          nullable: true
    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