Want to provide feedback?

Write to docs@telesign.com.

Create a Lease

After you find a phone number that you want to lease (for use as caller ID, sender ID, or to work with Inbound SMS), you will need to create a lease for the selected phone number. The https://rest-ww.telesign.com/phone_numbers/leases endpoint allows you to create a lease for a specified phone number using a POST request.

If you have your credentials and access to the Phone Numbers API, you can try a test request in the Phone Numbers API Explorer below to see how creating a lease works. You can also get a code snippet for the request.


For your test request to work, you need a phone number you want to lease. Refer to the Search for a Phone Number to Lease page for instructions on searching for numbers that suit your needs. When you have a number you want to lease, make a note of it for use with the Phone Numbers API Explorer below.


If you want to see phone number pricing information, refer to the Pricing for TeleSign Phone Numbers page on the TeleSign website.

Phone Numbers API Explorer
NOTE: The time shown in ms is not indicative of regular transmission rates, and only applies to the Phone Numbers API Explorer. If you run this test on a phone number, you will lease that phone number and be charged accordingly.
Send requests directly from the browser (CORS must be enabled)
No $$.env variables are being used in this request.

The Phone Numbers API Explorer is set up in the above example to accept the phone number you want to lease, and the two digit country code associated with the phone number. If you try this test out, a lease will be set up for the phone number and you will be charged for it.

If you lease an sms_capable number, support for SMS Verify, SMS, and Inbound SMS is added. If you lease a voice_capable number, support for Voice Verify and Voice is added.

As a post-paid customer, an invoice item is generated for the current month and states the recurring fee, using the recurrence period listed for the phone number. No end is placed on the generated lease.

To add your credentials and see the request run, do the following:

  1. Click the Auth [basic] tab and for Username add your customer ID. For Password add your API key.
  2. Click the Body tab and in the phone_number field, enter the complete phone number you want to lease. If you do not have a phone number you want to lease, do a search for one using the instructions on the Search for a Phone Number to Lease page. In the country_iso2 field, enter the two-digit country code associated with the phone number. (See available parameters on the API reference page - POST v1/leases.
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.

Leases Information

This section provides general information about the /leases endpoint of the Phone Numbers API.

  • The URI is https://rest-ww.telesign.com/v1/phone_numbers/leases
  • You can authenticate with Basic (easiest to implement) and Digest
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type - application/x-www-form-urlencoded in request headers

Next Steps

This section offers some suggestions for next steps to take.

  • Review available parameters for your request on the POST /leases page.
  • Cancel a Lease - Learn how to use the Phone Numbers API to cancel a lease on a phone number you leased previously.
  • Retrieve a List of Your Leased Numbers - Learn how to use the Phone Numbers API to retrieve a list of phone numbers you leased from TeleSign.