Home > telephony > nts > function-reference > func.telecoms.num.browse
function telecoms.num.browse

See also:

Fetch a sample list of phone numbers available for allocation.

You can use this function to present users with a list of available phone numbers. These are numbers that are available for adding to their account either with telecoms.num.alloc if you are using a master API account, or via the various functions.

Arguments:

argrequired?syntaxinfo
custIDNposintcustID of account to which setup fees should apply (default is current account))
number.startsNstringoptional filter to specify the digits you want the sample numbers to begin with
chargebandNstringoptional filter to specify the chargeband of the numbers (ie number type) being returned
promo_codeNstringif you have a promo code, specify it here for discounts on setup fees
priceband.minNunsintSpecifies the minimum priceband of the returned numbers
priceband.maxNunsintSpecifies the maximum priceband of the returned numbers
limitNposintmax quantity of sample numbers to return (default 25)

Further argument information

custID

If you are using this function as the user who will be using the phone numbers on their own account then there is no need to supply this argument.

If however you are using this function using a master API user on behalf of your customers and you will be putting the number(s) onto their account (a sub-account of your API account) then you may wish to provide their custID in this argument, as any custom prices set against their own account will then be reflected in the results.

number.starts

Specify this argument if you are looking specficically for numbers starting with a particular sequence of digits.

For example, if you are specifically looking for London numbers (which start 020) then you would specify this argument with a value of 020 (or +4420 if you prefer).

chargeband

The chargeband of a number defines its type, eg z for freephone, SC007 for 6ppm numbers, GEO for UK geographic numbers (UK numbers starting 01 or 02) etc.

priceband.min

The priceband of a number depends on how memorable the number is depending on the sequence of digits.

For example, numbers in the lowest priceband (0) would typically be a fairly unmemorable set of digits with no obvious pattern, whereas numbers ending 100200 or 1234 are more memorable and therefore more desirable. These more desirable numbers are in a higher priceband and attract a setup fee proportional to their desirability.

Example 1

Request a sample list of 5 London numbers. Specify a limit of 5 to limit the results to 5 numbers, and specify number.starts as 020 to limit the results to numbers that start with these digits, which is the London area code.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.num.browse",
   "args" : {
      "limit" : 5,
      "number.starts" : "020"
   }
}

The response contains a list of number records showing the priceband of the number, the setup fee in pounds (£/GBP) and pence, and the chargeband of the number.

As much as reasonably possible, the response will show example numbers from a range of pricebands unless you have narrowed the selection with the priceband.min and/or priceband.max arguments.

JSON example response:

{
   "success" : 1,
   "results" : [
      {
         "chargeband" : "GEO",
         "number" : "02030184824",
         "monthly_spend_min" : "0.00",
         "setup_fee" : "0.00",
         "priceband" : "0"
      },
      {
         "chargeband" : "GEO",
         "monthly_spend_min" : "0.00",
         "number" : "02030184144",
         "setup_fee" : "0.99",
         "priceband" : "1"
      },
      {
         "priceband" : "2",
         "setup_fee" : "15.20",
         "monthly_spend_min" : "0.00",
         "number" : "02030184600",
         "chargeband" : "GEO"
      },
      {
         "number" : "02030182777",
         "monthly_spend_min" : "0.00",
         "chargeband" : "GEO",
         "priceband" : "3",
         "setup_fee" : "39.20"
      },
      {
         "priceband" : "4",
         "setup_fee" : "800.00",
         "number" : "02030184444",
         "monthly_spend_min" : "0.00",
         "chargeband" : "GEO"
      }
   ]
}

Example 2

Fetch a list of three highly desirable UK geographic numbers without caring whether they begin 01 or 02. All UK geographic numbers have the chargeband GEO so you can use this argument to specify you want UK geographic numbers.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.num.browse",
   "args" : {
      "limit" : 3,
      "priceband.min" : 5,
      "chargeband" : "GEO",
      "priceband.max" : 5
   }
}

As these numbers don't have a setup fee defined (ie setup_fee has been returned as null) these numbers are £POA. You would need to contact us to discuss the price.

JSON example response:

{
   "results" : [
      {
         "monthly_spend_min" : "0.00",
         "chargeband" : "GEO",
         "number" : "02827990000",
         "setup_fee" : null,
         "priceband" : "5"
      },
      {
         "monthly_spend_min" : "0.00",
         "chargeband" : "GEO",
         "setup_fee" : null,
         "number" : "02827998888",
         "priceband" : "5"
      },
      {
         "setup_fee" : null,
         "number" : "02827999555",
         "chargeband" : "GEO",
         "monthly_spend_min" : "0.00",
         "priceband" : "5"
      }
   ],
   "success" : 1
}

Example 3

Request a list of 10 basic 6ppm numbers. These will have a priceband of 0. 6ppm numbers are classified by having the Ofcom chargeband of SC007.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.num.browse",
   "args" : {
      "limit" : 10,
      "priceband.min" : 0,
      "priceband.max" : 0,
      "chargeband" : "SC007"
   }
}

JSON example response:

{
   "success" : 1,
   "results" : [
      {
         "monthly_spend_min" : "0.00",
         "priceband" : "0",
         "chargeband" : "SC007",
         "setup_fee" : "4.95",
         "number" : "08443302124"
      },
      {
         "priceband" : "0",
         "monthly_spend_min" : "0.00",
         "chargeband" : "SC007",
         "setup_fee" : "4.95",
         "number" : "08443302203"
      },
      {
         "number" : "08443302256",
         "setup_fee" : "4.95",
         "chargeband" : "SC007",
         "priceband" : "0",
         "monthly_spend_min" : "0.00"
      },
      {
         "setup_fee" : "4.95",
         "number" : "08443302267",
         "priceband" : "0",
         "monthly_spend_min" : "0.00",
         "chargeband" : "SC007"
      },
      {
         "chargeband" : "SC007",
         "monthly_spend_min" : "0.00",
         "priceband" : "0",
         "number" : "08443302283",
         "setup_fee" : "4.95"
      },
      {
         "chargeband" : "SC007",
         "priceband" : "0",
         "monthly_spend_min" : "0.00",
         "number" : "08443302285",
         "setup_fee" : "4.95"
      },
      {
         "number" : "08443302523",
         "setup_fee" : "4.95",
         "chargeband" : "SC007",
         "priceband" : "0",
         "monthly_spend_min" : "0.00"
      },
      {
         "monthly_spend_min" : "0.00",
         "priceband" : "0",
         "chargeband" : "SC007",
         "setup_fee" : "4.95",
         "number" : "08443302646"
      },
      {
         "number" : "08443302723",
         "setup_fee" : "4.95",
         "chargeband" : "SC007",
         "priceband" : "0",
         "monthly_spend_min" : "0.00"
      },
      {
         "monthly_spend_min" : "0.00",
         "priceband" : "0",
         "chargeband" : "SC007",
         "setup_fee" : "4.95",
         "number" : "08443302821"
      }
   ]
}