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

# List phone numbers

> List phone numbers with pagination. The response includes headers about rate limiting.

Pagination Options:
1. Page-based pagination (default):
   - Provide `page` and `limit` parameters.
   - Response includes `current_page`, `total_pages`, and `total_items`.
   - Best for UIs that need to jump to specific pages.

2. Cursor-based pagination:
   - Based on phone number `created_at` property (ISO 8601 datetime of last seen record).
   - Set `use_cursor=true`.
   - Provide `limit` parameter to control results per page (default: 50, max: 1000).
   - Response includes `next_cursor` for subsequent requests.
   - Best for efficiently paging through large datasets.



## OpenAPI

````yaml /api-reference-v1/openapi.json get /v1/phone-numbers
openapi: 3.1.0
info:
  title: Rounded API
  description: Rounded API
  version: 1.0.0
servers:
  - url: https://api.callrounded.com
security:
  - ApiKeyHeader: []
paths:
  /v1/phone-numbers:
    get:
      tags:
        - phone-numbers
        - phone-numbers
      summary: List phone numbers
      description: >-
        List phone numbers with pagination. The response includes headers about
        rate limiting.


        Pagination Options:

        1. Page-based pagination (default):
           - Provide `page` and `limit` parameters.
           - Response includes `current_page`, `total_pages`, and `total_items`.
           - Best for UIs that need to jump to specific pages.

        2. Cursor-based pagination:
           - Based on phone number `created_at` property (ISO 8601 datetime of last seen record).
           - Set `use_cursor=true`.
           - Provide `limit` parameter to control results per page (default: 50, max: 1000).
           - Response includes `next_cursor` for subsequent requests.
           - Best for efficiently paging through large datasets.
      operationId: list_phone_numbers_v1_phone_numbers_get
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            description: >-
              Page number for page-based pagination (1-indexed, by default or
              when `use_cursor=false`).
            default: 1
            title: Page
          description: >-
            Page number for page-based pagination (1-indexed, by default or when
            `use_cursor=false`).
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >-
              Maximum number of results to return per page (default: 50, max:
              1000).
            default: 50
            title: Limit
          description: >-
            Maximum number of results to return per page (default: 50, max:
            1000).
        - name: use_cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: >-
              Pagination mode selection: `true` for cursor-based pagination,
              `false` for page-based pagination.
            default: false
            title: Use Cursor
          description: >-
            Pagination mode selection: `true` for cursor-based pagination,
            `false` for page-based pagination.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Cursor for pagination based on the phone number `created_at`
              property (ISO 8601 datetime of last seen record).
            title: Cursor
          description: >-
            Cursor for pagination based on the phone number `created_at`
            property (ISO 8601 datetime of last seen record).
      responses:
        '200':
          description: Successfully retrieved phone numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberListApiResponse-Input'
          headers:
            ratelimit-limit:
              description: The number of requests allowed in the current rate limit period
              schema:
                type: integer
            ratelimit-remaining:
              description: >-
                The number of requests remaining in the current rate limit
                period
              schema:
                type: integer
            x-ratelimit-limit-minute:
              description: >-
                The number of requests allowed in the current minute window, if
                rate limit is set to minutes.
              schema:
                type: integer
            x-ratelimit-remaining-minute:
              description: >-
                The number of requests remaining in the current minute window,
                if rate limit is set to minutes.
              schema:
                type: integer
            x-ratelimit-limit-hour:
              description: >-
                The number of requests allowed in the current hour window, if
                rate limit is set to hourly.
              schema:
                type: integer
            x-ratelimit-remaining-hour:
              description: >-
                The number of requests remaining in the current hour window, if
                rate limit is set to hourly.
              schema:
                type: integer
            x-ratelimit-limit-<seconds>:
              description: >-
                The number of requests allowed in the current <seconds> window,
                where <seconds> is the number of seconds, if rate limit is set
                to seconds.
              schema:
                type: integer
            x-ratelimit-remaining-<seconds>:
              description: >-
                The number of requests remaining in the current <seconds>
                window, where <seconds> is the number of seconds, if rate limit
                is set to seconds.
              schema:
                type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: Bad request
                  type: api_error
                  status: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              examples:
                auth_error:
                  summary: Error from the API Service
                  value:
                    message: Unauthorized
                    type: auth_error
                    status: 401
                gateway_error:
                  summary: Error from the API Gateway
                  value:
                    message: Unauthorized
                    type: gateway_auth_error
                    status: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: Access forbidden
                  type: api_error
                  status: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: The request endpoint does not exist
                  type: http_error
                  status: 404
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: Invalid request body
                  type: validation_error
                  status: 422
                  details:
                    - field: email
                      message: Invalid email format
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: API rate limit exceeded
                  type: gateway_rate_limit_error
                  status: 429
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
              example:
                error:
                  message: An unexpected error occurred
                  type: generic_error
                  status: 500
components:
  schemas:
    PhoneNumberListApiResponse-Input:
      properties:
        message:
          type: string
          title: Message
          description: Response message indicating the status of the request.
          default: Calls retrieved successfully
        data:
          items:
            anyOf:
              - $ref: '#/components/schemas/PhoneNumberPstnGetApiResponseData'
              - $ref: '#/components/schemas/PhoneNumberSipGetApiResponseData'
          type: array
          title: Data
          description: List of phone number objects matching the query criteria.
        error:
          anyOf:
            - $ref: '#/components/schemas/ApiResponseError'
            - type: 'null'
        status:
          type: integer
          title: Status
          description: HTTP status code (200 for successful requests).
          default: 200
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: |-
            Next cursor value for cursor-based pagination
            (ISO 8601 datetime string, only present when `use_cursor=true`).
        current_page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Current Page
          description: Current page number (by default or when `use_cursor=false`).
        total_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Pages
          description: >-
            Total number of pages available (by default or when
            `use_cursor=false`).
        total_items:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Items
          description: >-
            Total count of items matching the query criteria (by default or when
            `use_cursor=false`).
      type: object
      required:
        - data
      title: PhoneNumberListApiResponse
    ApiResponseError:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        status:
          type: integer
          title: Status
        details:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiResponseErrorDetail'
              type: array
            - type: 'null'
          title: Details
      type: object
      required:
        - message
        - type
        - status
      title: ApiResponseError
      example:
        details:
          - field: email
            message: Invalid email format
        message: An error occurred while processing your request
        status: 400
        type: generic_error
    PhoneNumberPstnGetApiResponseData:
      properties:
        type:
          type: string
          const: pstn
          title: Type
          default: pstn
        id:
          type: string
          format: uuid
          title: Id
          description: The ID of the phone number.
        number:
          type: string
          title: Number
          description: The phone number.
        name:
          type: string
          title: Name
          description: The phone number friendly name.
        inbound_agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Inbound Agent Id
          description: The agent ID that will handle incoming calls to this phone number.
        redirect:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Redirect
          description: >-
            Whether to redirect the phone number. If true, any calls to this
            phone number will be redirected to the `redirect_phone_number`
            overriding the agent assignment.
          default: false
        redirect_phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Phone Number
          description: The phone number to redirect to.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time the phone number was created.
      type: object
      required:
        - id
        - number
        - name
        - created_at
      title: PSTN Phone Number
    PhoneNumberSipGetApiResponseData:
      properties:
        type:
          type: string
          const: sip
          title: Type
          default: sip
        id:
          type: string
          format: uuid
          title: Id
          description: The ID of the phone number.
        number:
          type: string
          title: Number
          description: The phone number friendly name.
        name:
          type: string
          title: Name
          description: The phone number friendly name.
        inbound_agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Inbound Agent Id
          description: The agent ID that will handle incoming calls to this phone number.
        termination_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Termination Uri
          description: The SIP termination URI to use for outbound calls.
        termination_username:
          anyOf:
            - type: string
            - type: 'null'
          title: Termination Username
          description: The username used to authenticate with the SIP termination URI.
        origination_username:
          anyOf:
            - type: string
            - type: 'null'
          title: Origination Username
          description: >-
            The allowed username to accept inbound calls for this SIP trunk, by
            default no username is required.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time the phone number was created.
      type: object
      required:
        - id
        - number
        - name
        - termination_uri
        - termination_username
        - origination_username
        - created_at
      title: SIP Phone Number
    ApiResponseErrorDetail:
      properties:
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ApiResponseErrorDetail
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        The API Key created in [Rounded Studio](https://app.callrounded.com).

        - You can create it by going to the "API Keys" settings of your profile.

        - Need help? You can email us at
        [team@callrounded.com](mailto:team@callrounded.com) or join our [Discord
        community](https://discord.gg/en537j5z75).

````