---
title: "List your numbers"
method: GET
path: "/api/v1/numbers"
tags: ["Phone Numbers"]
---

# List your numbers

`GET /api/v1/numbers`

## Request

- Base URL: `https://api.callnode.io`
- URL: `https://api.callnode.io/api/v1/numbers`
- Auth: API key in header `X-Api-Key` and API key in header `X-Timestamp` and API key in header `X-Signature`

Your numbers, newest first. Every filter is applied server-side and they combine (AND).

## Query parameters

- `status` string
- `type` 'local' | 'tollfree'
- `purchaseSource` 'web' | 'api'
- `tag` string
- `q` string

## Response `200`

Your numbers, newest first.

- object
  - `numbers` PhoneNumber[]
    - `id` string
    - `phoneNumber` string: Plus sign followed by 7–15 digits.
    - `type` 'local' | 'tollfree'
    - `friendlyName` string, nullable
    - `status` string
    - `purchaseSource` 'web' | 'api': How the number was purchased — via the dashboard (`web`) or this API (`api`).
    - `tags` string[]: Your own labels for the number. Trimmed, de-duplicated case-insensitively, returned on every number, filterable on the dashboard. PATCH replaces the whole list; send [] to clear.
    - `voice` object
      - `webhookUrl` string, uri, nullable
      - `webhookAuth` WebhookAuthStatus, nullable: How CallNode authenticates to your webhook. The secret itself is write-only and never returned.
        - `type` 'basic' | 'bearer' | 'header'
        - `headerName` string
        - `valueSet` boolean
      - `webhookTimeout` integer
      - `sipUri` string, nullable: SIP delivery target (BYOC / wholesale). Null when the number runs in webhook mode.
      - `srtp` boolean: Whether the sipUri delivery leg offers SRTP (only ever true beside a ;transport=tls address).
      - `trunkId` string, nullable: SIP trunk this number delivers inbound calls to. Null unless trunk delivery is configured.
      - `realtime` object, nullable: Realtime WebSocket mode (see /docs/realtime). Null when the number runs the per-turn webhook loop.
        - `url` string, uri: wss:// endpoint CallNode connects to per call
        - `auth` WebhookAuthStatus, nullable: How CallNode authenticates to your webhook. The secret itself is write-only and never returned.
          - `type` 'basic' | 'bearer' | 'header'
          - `headerName` string
          - `valueSet` boolean
        - `voice` string, nullable: Voice id used for say frames; null = platform default
    - `messaging` object
      - `webhookUrl` string, uri, nullable
      - `webhookAuth` WebhookAuthStatus, nullable: How CallNode authenticates to your webhook. The secret itself is write-only and never returned.
        - `type` 'basic' | 'bearer' | 'header'
        - `headerName` string
        - `valueSet` boolean
      - `enabled` boolean
      - `ready` boolean, nullable: Whether A2P messaging registration has completed for this number. Provisions asynchronously after purchase.
    - `monthlyRate` number
    - `perMinuteRate` number
    - `includedInSubscription` boolean
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `count` integer

## Other responses

- `401`: Missing, unknown, or badly signed credentials — check the HMAC and the timestamp skew.

---

[API](https://skmtc.dev/callnode/apis/callnode-outbound-api.md) · [All operations](https://skmtc.dev/callnode/apis/callnode-outbound-api/llms.txt) · [OpenAPI document](https://skmtc.dev/callnode/apis/callnode-outbound-api/revisions/c7da6ad06509?raw)