Get Started with the Phone Numbers API

TeleSign’s Phone Numbers API allows you to:

  • Search for phone numbers that you can lease to use as a sender or caller ID or both.
  • Retrieve a list of phone numbers currently leased to you.
  • Create a lease for a phone number you want.
  • Cancel a lease for a specified phone number.

This page provides instructions and references for features of the Phone Numbers API and associated tools.

General Information

All requests submitted for the Phone Numbers API:

  • Can be authenticated 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
  • Use one of these endpoints:
    • Search for a phone number (GET)-https://rest-ww.telesign.com/v1/phone_numbers/numbers
    • Retrieve a list of your currently leased phone numbers (GET) - https://rest-ww.telesign.com/v1/phone_numbers/leases
    • Create a lease for a phone number (POST) - https://rest-ww.telesign.com/v1/phone_numbers/leases
    • Cancel a lease for a phone number (DELETE) - https://rest-ww.telesign.com/v1/phone_numbers/leases/{lease_id}

Search for a Phone Number to Lease

If you want to lease a phone number from TeleSign for use with voice or SMS products, you can use TeleSign’s Phone Numbers API to do so. Go to the Search for a Phone Number to Lease page for more details.

If you want to buy a block of phone numbers in bulk, speak with your Customer Success Manager.

Create a Lease

If you want to lease a phone number, you can lease it using the /leases endpoint. Go to the Create a Lease page for more details.

If you want to know more about phone number pricing, check out Pricing for TeleSign Phone Numbers on the TeleSign website.

Retrieve a List of Your Leased Numbers

If you need to see what phone numbers you already leased from TeleSign, you can retrieve a list of your leased numbers. Go to the Retrieve a List of Your Leased Numbers page for more details.

Cancel a Lease

You can cancel a lease on a phone number you purchased using the /leases endpoint. Go to the Cancel a Lease page for more details.

Restrictions by Country

When using any of the endpoints for the Phone Numbers API, the following restrictions apply:

Country Restrictions/Requirements
France The end user (residential/corporate) must be located in the same geographic zone as the number. An official address is required before activation. For national numbers (09) an address in the country (mainland) is required.
Germany The end user (residential/corporate) must be located in the same geographic zone as the number. Proof of address is required before activation. For corporate: an extraction of the company register is required.
Italy If a number is to be used for call center activities, please note this regulator’s rule: It is compulsory to inform the calling customer about the location of the call center operator who is answering (agent). In case the agent is located in an extra-EU Country, it must be possible for the customer’s call to be immediately forwarded to another call center located in the European Community. Penalties for non-compliance with this law are huge, 150,000 EUR in case of missing or late communication to the call centers and 50,000 EUR to the call center that is not compliant. The end user (residential/corporate) must be located in Italy. Proof of address is required before activation.
Spain A copy of the ID/business registration and a local address in Spain are requested before activation. Mobile DID numbers can only be used for Person to Person communication. This service cannot be used for sending bulk notifications or other marketing campaigns which do not comply with the usage of long virtual numbers.
NOTE:

Due to these restrictions, phone numbers from these countries will not be available through the Phone Numbers API. Speak with your Customer Success Manager if you need numbers for these countries.

Next Steps

This section offers some suggestions for next steps to take.

  • Search for a Phone Number to Lease - Learn how to use the Phone Numbers API to search for a phone number to lease for use with one of TeleSign’s voice or SMS products.