Get a list of numbers either leased by you or available to be leased.


We created a new viewing experience for our SMS API documentation. It's now all in one central location. Click here to check it out!


Parameter

Description

Required

filterPossible values are
owned - retrieve your own response numbers (default)
available - retrieve response numbers available for purchase
YES
pagePage number, for paginationNO
maxMaximum results returned per pageNO


Example: Get a list of numbers you have leased

curl https://api.transmitsms.com/get-numbers.json \
  -u 2e24c1cbdd987221e165d543f34b84bf:secret


JSON Response

{
  filter: "owned",
  numbers_total: 1,
  numbers: [
    {
      number: "61491570110",
      next_charge: "2013-08-14",
      auto_renew: true,
      status: "active",
      price: "29",
      forward_url: "http://example.com/sms"
    }
    ],
    page: {
      count: 1,
      number: 1
    }
}

XML Response

<?xmlversion="1.0"encoding="UTF-8"?>
<response>
  <filter>owned</filter>
  <numbers_total>1</numbers_total>
  <numbers>
    <number>61491570110</number>
    <next_charge>2013-08-14</next_charge>
    <auto_renew>true</auto_renew>
    <status>active</status>
    <price>29</status>
    <forward_url>http://example.com/sms</forward_url>
  </numbers>
  <page>
    <count>1</count>
    <number>1</number>
  </page>
</response>


Example: Get a list of numbers available for lease

curl https://api.transmitsms.com/get-numbers.json \
  -u 2e24c1cbdd987221e165d543f34b84bf:secret \
  -d filter=available


JSON Response

{
  filter: "available",
  numbers_total: 134,
  numbers: [
    {
      number: "61491570156",
      next_charge: null,
      auto_renew: true,
      status: "inactive",
      forward_url: "http://example.com/sms"
    }],
    page: {
      count: 14,
      number: 1
    }  
}

XML Response

<?xmlversion="1.0"encoding="UTF-8"?>
<response>
  <filter>available</filter>
  <numbers_total>134</numbers_total>
  <numbers>
    <number>61491570156</number>
    <next_charge>null</next_charge>
    <auto_renew>true</auto_renew>
    <status>inactive</status>
    <forward_url>http://example.com/sms</forward_url>
  </numbers>
  <page>
    <count>14</count>
    <number>1</number>
  </page>
</response>



PHP Examples

<?php
 include '../../APIClient2.php';

 $api = new transmitsmsAPI('API_KEY', 'API_SECRET');
 $offset = 0;
 $limit = 10;
 $result = $api->getNumbers($offset,$limit $filter='available');

 if ($result->error->code == 'SUCCESS') {
   echo 'There are {$result->numbers_total} numbers, 
     showing page {$result->page->number} of {$result->page->count} <hr>';
     
   foreach($result->numbersas$number){
     echo 'Number {$number->number} is {$number->status}
       and valid up to {$number->next_charge}<br>';
   }
     
 } else {
   echo 'Error: {$result->error->description}';
 }