Skip to main content

​
Managing Number Leases

Lease phone numbers to use as dedicated senders for your messages, improving deliverability and brand recognition.

​
Check Available Numbers

View available phone numbers that can be leased for your account. 
const res = await contiguity.lease.available();

​
Parameters

No parameters required.

​
Response

​
available
boolean
Indicates if there are numbers available for leasing.
​
numbers
object[]
Array of available phone numbers with their details.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
Get Number Details

Get detailed information about a specific phone number, including capabilities and pricing. 
const res = await contiguity.lease.get("+1234567890");

​
Parameters

​
number
string
required
Phone number in E.164 format. First argument.

​
Response

​
number
object
Phone number details and formatting information.
​
capabilities
string[]
Array of supported capabilities for this number (e.g., [“sms”, “voice”]).
​
pricing
object
Pricing information for leasing this number.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
Lease a Number

Create a lease for a phone number to use it as a sender. 
const res = await contiguity.lease.create("+1234567890", { billing_method: "monthly" });
You can also lease a number with default billing: 
const res = await contiguity.lease.create("+1234567890");

​
Parameters

​
number
string
required
Phone number in E.164 format. First argument.
​
options
object
Optional. e.g. { billing_method: "monthly" }.

​
Response

​
lease_id
string
Unique identifier for the created lease.
​
status
string
Current status of the lease (e.g., “active”, “pending”).
​
billing
object
Billing information and configuration for the lease.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
View Leased Numbers

Get a list of all numbers you currently have leased. 
const res = await contiguity.lease.leased();

​
Parameters

No parameters required.

​
Response

​
leased
boolean
Indicates if any numbers are currently leased.
​
numbers
object[]
Array of currently leased phone numbers with their details.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
Get Lease Details

Get detailed information about a specific lease. 
const res = await contiguity.lease.details("+1234567890");

​
Parameters

​
number
string
required
Leased phone number in E.164. First argument.

​
Response

​
lease_id
string
Unique identifier for the lease.
​
lease_status
string
Current status of the lease (e.g., “active”, “expired”, “terminated”).
​
billing
object
Billing information and current charges for the lease.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
Configure a lease

Customize a leased number’s failover behavior. 
const res = await contiguity.lease.configure({
  number: "+13059478667",
  failover: { enabled: true, mode: "selective", numbers: ["+15551234567"] }
});

​
Parameters

​
number
string
required
Leased phone number in E.164 format.
​
failover
object
required
Failover configuration.

​
Response

​
number
string
The configured number.
​
failover
object
Applied failover config: enabled, mode, numbers.
​
metadata
object
Request metadata: id, timestamp, api_version, object.

​
Terminate a Lease

End a lease for a phone number when you no longer need it. 
await contiguity.lease.terminate("+1234567890");

​
Parameters

​
number
string
required
Leased phone number in E.164. First argument.

​
Response

​
lease_id
string
Unique identifier for the terminated lease.
​
status
string
Confirmation status of the termination (e.g., “terminated”).
​
terminated_at
timestamp
ISO 8601 formatted timestamp of when the lease was terminated.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
Using Leased Numbers

Once you have a leased number, you can use it as the from parameter in your messaging: 
// Use leased number as sender for SMS
const res = await contiguity.text.send({
  to: "+1234567890",
  message: "Hello from your dedicated number!",
  from: "+15555555555" // your leased number
});

// Use leased number as sender for iMessage
const res = await contiguity.imessage.send({
  to: "+1234567890",
  message: "Hello via iMessage!",
  from: "+15555555555" // your leased number
});