---
title: Inventory
description: Manage phone number inventory, SIM cards, and reservations.
---

# Inventory

Manage phone number inventory, SIM cards, and reservations.

## [POST /inventory/lease-numbers](/api-reference/inventory#tag/inventory/POST/inventory/lease-numbers)

Lease phone numbers

Reserve phone numbers from inventory for use in orders. This allows customers to choose specific
numbers before completing their order.

**Availability**: This feature is part of our premium number selection offering and may not be
available for all product offerings. Check the response for availability information.

**Usage Flow**:
1. Lease numbers to get a lease token
2. Use the lease token and chosen msisdn in subscription line items
3. Numbers are automatically released if not used before expiry

**Important**: Leased numbers expire after a short time (typically 1 hour) to
prevent inventory hoarding.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code.

### Request body (required)

Type: `object`

- `types` (`array of NumberType`, required, example ["CELL"]) — Types of numbers to lease.
- `count` (`integer`, required, >= 1, <= 10, example 2) — Number of phone numbers to lease.

### Responses

#### 200

Numbers leased successfully.

Type: [NumberLeaseResult](/api-reference/models.md#models/NumberLeaseResult)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/inventory/lease-numbers \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "types": [
    "CELL"
  ],
  "count": 2
}'
```

## [GET /inventory/sims/{iccid}](/api-reference/inventory#tag/inventory/GET/inventory/sims/{iccid})

Get SIM details

Retrieve details of a SIM card from inventory by its ICCID.

For eSIM cards linked to a subscription, the response includes live installation status
from the network operator, showing whether the profile has been downloaded, installed,
or enabled on a device.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `iccid` (`string`, required) — The ICCID of the SIM card to retrieve.

### Responses

#### 200

SIM details retrieved successfully.

Type: [InventorySim](/api-reference/models.md#models/InventorySim)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/inventory/sims/8946200508271016579 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```