---
title: "Replace with a fresh port on the same carrier"
method: POST
path: "/v1/ports/{id}/replace"
tags: ["ports"]
---

# Replace with a fresh port on the same carrier

`POST /v1/ports/{id}/replace`

## Request

- Base URL: `https://api.portproof.org`
- URL: `https://api.portproof.org/v1/ports/{id}/replace`
- Auth: HTTP bearer

The old port is retired and the subscription moves to the new one. A dedicated port from the partner network keeps its id: the device is swapped and host, ports and credentials change. Requires an `Idempotency-Key` header (CONTRACT §1): the same key with the same body within 24 h replays the stored response; a different body returns 409 `idempotency_conflict`.

## Path parameters

- `id` string, required

## Response `200`

Default Response

- object
  - `id` string, required
  - `state` 'provisioning' | 'available' | 'reserved' | 'sold' | 'leased' | 'migrating' | 'quarantined' | 'retired', required
  - `site_code` string, required
  - `country` string, required
  - `carrier` object, required
    - `id` string, required
    - `name` string, required
    - `mcc_mnc` string, required
    - `ip_stack` 'v4' | 'v6_464xlat' | 'dual', required
  - `operator` 'owned' | 'partner', required
  - `listeners` object, required
    - `host` string, required
    - `http_port` integer, required
    - `socks_port` integer, required
  - `credentials` object, nullable, required
    - `username` string, required
    - `password` string, required
    - `http` object
      - `host` string, required
      - `port` integer, required
      - `username` string, required
      - `password` string, required
    - `socks5` object
      - `host` string, required
      - `port` integer, required
      - `username` string, required
      - `password` string, required
  - `allowlist` string[], required
  - `egress_v4` string, nullable, required
  - `egress_v6_prefix` string, nullable, required
  - `v4_is_nat64` boolean, required
  - `ip_since` string, date-time, nullable, required
  - `rotation_interval_s` integer, required
  - `sticky_until` string, date-time, nullable, required
  - `cooldown_until` string, date-time, nullable, required
  - `last_rotation_at` string, date-time, nullable, required
  - `telemetry_since` string, date-time, nullable, required
  - `usage_today` object, required
    - `bytes` integer, required
    - `cap_bytes` integer, required
  - `uptime_30d_pct` number, nullable, required
  - `subscription` object, nullable, required
    - `id` string, required
    - `org_id` string, required
    - `port_id` string, required
    - `sku` string, required
    - `term` 'monthly' | 'weekly' | 'daily', required
    - `price_cents` integer, required
    - `currency` 'EUR' | 'USD', required
    - `starts_at` string, date-time, required
    - `ends_at` string, date-time, required
    - `auto_renew` boolean, required
    - `state` 'active' | 'grace' | 'suspended' | 'ended', required
    - `provider_ref` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `evidence` 'signed' | 'observed', required
  - `attestation` 'signed' | 'observed', required
  - `network` 'own' | 'partner'
  - `capabilities` object, nullable
    - `replace` boolean, required
    - `cancel` boolean, required
    - `allowlist` boolean, required
    - `auto_swap` boolean, required
    - `rotation_interval` boolean, required
    - `password_change` boolean, required
  - `renewal` object, nullable
    - `auto_renew` boolean, required
    - `ends_at` string, date-time, required
    - `price_cents` integer, required
    - `can_renew` boolean, required
  - `rotation_url` string, uri

## Other responses

- `404`: Default Response
- `409`: Default Response
- `429`: Default Response
- `502`: Default Response

---

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