---
title: "List the customer's active and suspended DID numbers"
method: GET
path: "/did_numbers"
tags: ["DID-Numbers"]
---

# List the customer's active and suspended DID numbers

`GET /did_numbers`

## Request

- Base URL: `https://api.commpeak.com/portal`
- URL: `https://api.commpeak.com/portal/did_numbers`
- Auth: API key in header `Authorization`

Returns the customer's DID (inbound phone) numbers that are activated or suspended; numbers that are still being ordered or have been cancelled are not included. Each number contains its country, name, assigned identity and tags, billing details (monthly fee, next billing date, auto-renewal), whether SMS-to-email is available, and where incoming calls are forwarded to — a SIP URI, a SIP account or a PSTN number, with `forward_order` showing the configured forwarding type.

## Response `200`

Successful Response

- DIDNumbersResponse: Envelope returned by `GET /portal/did_numbers`.
  - `did_numbers` DIDNumberItem[], required
    - `number` string, required: Phone number in E.164 (no leading "+").
    - `name` string, nullable: Human-readable description (typically "Country - City - Type").
    - `state` string, nullable: Lifecycle state (e.g. "activated", "pending", "cancelled").
    - `country` string, nullable: ISO 3166-1 alpha-2 country code (e.g. "US").
    - `next_billing_date` string, nullable: Next monthly billing date (YYYY-MM-DD).
    - `auto_renewal` boolean, nullable: Whether the DID auto-renews on the next billing date.
    - `monthly_fee` number, nullable: Monthly fee in customer currency.
    - `identity` string, nullable: Identity document the DID is registered to.
    - `tags` string[], nullable: Free-form tag names attached to the DID.
    - `sms` boolean, nullable: Whether SMS-to-email is enabled for the DID.
    - `did_order` string, nullable: Short description of the originating order (order id + creation timestamp).
    - `forward_uri` string, nullable: Forwarding SIP URI, if configured.
    - `forward_sip` string, nullable: Forwarding SIP account name, if configured.
    - `forward_pstn` string, nullable: Forwarding PSTN number, if configured.
    - `forward_order` string, nullable: Order in which forward destinations are attempted (e.g. "sip_uri_pstn").

---

[API](https://skmtc.dev/commpeak/apis/commpeak-portal-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-portal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-portal-api/revisions/df57b0c16367?raw)