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({ 
  number: "+1234567890" 
});

​
Parameters

​
number
string
required
The phone number to get details for, in E.164 format (e.g., “+1234567890”).

​
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({ 
  number: "+1234567890",
  billing_method: "monthly" // or "service_contract"
});
You can also lease a number with default billing: 
const res = await contiguity.lease.create({ 
  number: "+1234567890"
});

​
Parameters

​
number
string
required
The phone number to lease, in E.164 format (e.g., “+1234567890”).
​
billing_method
string
The billing method for the lease. Options: "monthly" for recurring monthly charges, "service_contract" for contract-based billing.

​
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({ 
  number: "+1234567890" 
});

​
Parameters

​
number
string
required
The leased phone number to get details for, in E.164 format (e.g., “+1234567890”).

​
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.

​
Terminate a Lease

End a lease for a phone number when you no longer need it. 
const res = await contiguity.lease.terminate({ 
  number: "+1234567890" 
});

​
Parameters

​
number
string
required
The leased phone number to terminate, in E.164 format (e.g., “+1234567890”).

​
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
});
⌘I