---
title: "Make a number the caller ID for outbound calls"
method: PUT
path: "/api/v1/phone-numbers/{did}/default"
tags: ["Phone numbers"]
---

# Make a number the caller ID for outbound calls

`PUT /api/v1/phone-numbers/{did}/default`

## Request

- Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from)
- URL: `https://wardenpoint.com/api/v1/phone-numbers/{did}/default`
- Auth: API key in header `X-API-Key`

Binds an already-owned number as what the company presents when it calls out. Exactly one number can hold this, so the previous default loses it in the same step — there is no separate call to clear it, and no way through this API to end up with none once one has been chosen. Idempotent: repeating it on the same number changes nothing. Free and reversible; the money was spent when the number was bought. A number that is suspended or still awaiting provider confirmation is refused, because a caller ID that cannot carry calls breaks every outbound call at once. PATCH is accepted on the same path with identical semantics.

## Path parameters

- `did` string, uuid, required

## Response `200`

The number, now default.

- object
  - `data` PhoneNumber: An external number the company owns. Unlike every other object in this API it disappears on its own when it stops being paid for, so `expires_at`, `auto_renew` and `renewal_failures` are part of its normal reading, not diagnostics.
    - `uuid` string, uuid: Stable identifier — every phone-number endpoint takes this.
    - `number` string: E.164.
    - `country_code` string, nullable
    - `city` string, nullable
    - `number_type` 'local' | 'mobile' | 'tollfree' | 'national', nullable: Kind of number, as classified when it was bought.
    - `status` 'assigned' | 'pending_purchase' | 'suspended': `assigned` — live. `pending_purchase` — the provider has not confirmed yet. `suspended` — three renewal charges in a row failed; the number no longer carries calls and cannot be made the default caller ID until it is paid for. Those three are the only ones the listing returns; the column also holds `available`, `reserved` and `retired`, which mean the number is not the company's any more.
    - `monthly_cost` number, float: Charged to the company credit balance every month while `auto_renew` is on.
    - `currency` string
    - `auto_renew` boolean: True keeps charging `monthly_cost` to the credit balance each month. False lets the number lapse at `expires_at`, after which it stops carrying calls and leaves the company.
    - `is_default` boolean: Whether outbound calls present this number. Exactly one number per company can hold it.
    - `expires_at` string, date-time, nullable: End of the paid period. With auto_renew on this is the next charge date, not a deadline; with it off, the moment the number stops working.
    - `is_expiring_soon` boolean: True within five days of expiry.
    - `renewal_failures` integer: Consecutive failed renewal charges. At three the number goes `suspended`. A non-zero value means the credit balance did not cover the charge.
    - `created_at` string, date-time

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the config.write ability, or the number belongs to another company.
- `404`: No number with this UUID.
- `422`: The number is not live — suspended, or still awaiting provider confirmation.
- `429`: Too many number changes in a short window.

---

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