Skip to main content
POST
/
inventory
/
lease-numbers
Lease phone numbers
curl --request POST \
  --url https://apiv2.example.com/inventory/lease-numbers \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "types": [
    "CELL"
  ],
  "count": 2
}
'
{
  "numbers": [
    {
      "msisdn": "+15551234567",
      "type": "CELL",
      "grade": 5,
      "expiresAt": "2024-01-15T11:30:00Z",
      "availableAt": "2024-01-15T10:00:00Z",
      "leasedAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "region": "New York",
        "areaCode": "555"
      }
    }
  ],
  "leaseToken": "lease_abc123def456",
  "expiresAt": "2024-01-15T11:30:00Z"
}

Authorizations

​
X-Api-Key
string
header
required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Headers

​
X-Idempotency-Key
string

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.

Maximum string length: 256

Body

application/json

Request to lease phone numbers for use in orders.

​
types
enum<string>[]
required

Types of numbers to lease.

The type of phone number for different use cases.

Available options:
CELL,
FIXED,
DATA,
M2M
Example:
["CELL"]
​
count
integer
required

Number of phone numbers to lease.

Required range: 1 <= x <= 10
Example:

2

Response

Numbers leased successfully.

Result of a number leasing request.

​
numbers
object[]
required

The leased phone numbers.

​
leaseToken
string
required

Token to use when creating subscription line items with these numbers.

Provide this token in the leaseToken field when ordering or creating a subscription along with the chosen msisdn from the leased numbers.

Example:

"lease_abc123def456"

​
expiresAt
string<date-time>
required

When this lease expires if not used in an order.

Example:

"2024-01-15T11:30:00Z"