telecoms.rates.ingress function

Home > telephony > nts > function-reference > func.telecoms.rates.ingress

function telecoms.rates.ingress

Lookup ingress rates.

Arguments:

arg	required?	syntax	info
`parent_custID`	N	posint	custID of supplier (parent) account
`custID`	N *	unsint	custID of account to which rates should apply (default is current account))
`default`	N *	boolean	if supplied, default rates charged by parent_custID will be returned
`number`	Y **	strictphone	if supplied, rates for calls in to this number will be returned
`rangeID`	Y **	posint	if supplied, rates for calls to numbers in this range will be returned
`range_typeID`	Y **	posint	if supplied, rates for calls to numbers in ranges of this type will be returned
`chargeband`	Y **	string	if supplied, rates for calls to numbers in this chargeband will be returned
`telcoID`	conditional ***	posint	required if range_typeID or chargeband are supplied; identifies the range-owning telco
`service`	Y	enum:nts\|ida	the service that will be used with the number (required unless you specify the number arg with a number matching one already on the customer account)
`ingress_type`	Y	enum:pstn\|sip	defines whether calls will arrive over the public telephone network (pstn) or over VoIP (sip)
`svcchg_keyword`	N	string	eg "bronze" if the number is to have a service charge, specify it by name here
`svcchg_optionID`	N	posint	if the number is to have a service charge, specify it by ID here

* custID and default are mutually exclusive.

** you should supply just one of number, rangeID, range_typeID, chargeband.

*** telcoID is required if you specify range_typeID or chargeband.

Notes:

custID will default to the custID whose credentials are being used to access the API, unless default is supplied.
If you want to just fetch default customer rates for customers of a particular account, supply the parent account in parent_custID and specify a custID of 0
If you specify the number argument, if this matches a number on the customer's account then this will be used to determine the service. If you specify a number not matching one on the customer's account, you must also supply the service argument.

Return values

A list of all matching rate records is returned. If more than one rate record is returned, they will differ in the trigger_minutes value. Records contain the below fields. Note that negative values in the per minute and connection charge fields indicate a rebate.

custID - the custID against whom this rate record is defined. This function will only return applicable rates, so if you have specified a custID value when calling it, this field will either contain that value (if it is a custom rate for that customer) or zero (which indicates a default rate for all customers of the parent custID).
trigger_minutes - the minimum number of minutes (in any given month) the customer needs to have done on this number (or number type if a registered partner) in order to qualify for this rate. At call time, the system applies the zero trigger minute rate, but retrospectively, volume rebates are calculated using higher trigger_minutes rates if the customer has generated sufficient call volume. If a customer's call volume exceeds several records' trigger_minutes values, the highest will be used.
minseconds - the minimum number of seconds per call the system will charge for
freeseconds - if non-zero, the per minute charges for a call don't start counting up until this many seconds have elapsed
pk_short_s, offpk_short_s, we_short_s - if the call has fewer than this many seconds duration for peak, offpeak and weekends, it will count as a short call
ingress_type - indicates the ingress type defined for this record (an empty string value will match all ingress types)
service - indicates the service type defined for this record (an empty string value will match all service types)
pk_uGBPconn - connection fee if the call connects during peak time (1 uGBP = 0.000001 GBP)
offpk_uGBPconn - connection fee if the call connects during offpeak time (1 uGBP = 0.000001 GBP)
we_uGBPconn - connection fee if the call connects during a weekend (1 uGBP = 0.000001 GBP)
pk_uGBPpm - per minute charge for any time a call is connected during peak time
offpk_uGBPpm - per minute charge for any time a call is connected during offpeak time
we_uGBPpm - per minute charge for any time a call is connected during a weekend
pk_uGBPpms - per minute charge for any time a call is connected during peak time (short calls only - see pk_short_s,offpk_short_s,we_short_s)
offpk_uGBPpms - per minute charge for any time a call is connected during offpeak time (short calls only - see pk_short_s,offpk_short_s,we_short_s)
we_uGBPpms - per minute charge for any time a call is connected during weekends (short calls only - see pk_short_s,offpk_short_s,we_short_s)
minchg_uGBP - minimum charge per call; if this is NULL/undefined then there is no minimum charge. This value can be negative (in which case it would indicate a maximum rebate per call)

Additionally, if the number argument is supplied, the return data will have a number_on_account value which will indicate whether the number matched one on the customer's account (1 indicates yes, 0 indicates no). If the number is not on the customer's account, the rates returned are those the customer would be charged/rebated if they did have that number on their account. Note that this does not indicate whether the number is actually available for purchase.

Examples

Example requests

Perl example request:

POST https://live.apicontrol.co.uk/1/json

# get rates I pay:
$rates = $api->get_rates_ingress(number=>$number);

# get default rates I charge:
$rates = $api->get_rates_ingress(number=>$number, default=>1);

 # get rates I charge to $my_customer
$rates = $api->get_rates_ingress(number=>$number, custID=>$my_customer);

 # get default rates that $him charges his customers
$rates = $api->get_rates_ingress(number=>$number, parent_custID=>$him, default=>1);

 # get rates that $him charges $his_customer
$rates = $api->get_rates_ingress(number=>$number, parent_custID=>$him, custID=$his_customer);

Example response

Perl example response:

{
  'success' => 1,
  'error' => undef,
  'errornum' => '',
  'errordiags' => '',
  'results' => {
                 'data' => [
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '40000',
                               'we_uGBPpm' => '40000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '0',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '40000',
                               'we_short_s' => '0',
                               'service' => 'nts',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             }
                           ],
                 'number_on_account' => 0
               }
};

Example 2

Perl example request:

POST https://live.apicontrol.co.uk/1/json
my $res = $api->telecoms_rates_ingress(number=>'08447400000', ingress_type=>'pstn', service=>'nts');
print Dumper($res);

Example 2 response

Note that the number queried here has several sets of rates that could apply, depending on volume. This is indicated by the trigger_minutes field.

Perl example response:

{
  'success' => 1,
  'error' => undef,
  'errornum' => '',
  'errordiags' => '',
  'results' => {
                 'data' => [
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-20000',
                               'we_uGBPpm' => '-20000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '0',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-20000',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             },
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-22500',
                               'we_uGBPpm' => '-22500',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '10000',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-22500',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             },
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-25000',
                               'we_uGBPpm' => '-25000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '50000',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-25000',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             },
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-27500',
                               'we_uGBPpm' => '-27500',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '100000',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-27500',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             },
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-30000',
                               'we_uGBPpm' => '-30000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '250000',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-30000',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             },
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-35000',
                               'we_uGBPpm' => '-35000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '500000',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-35000',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             },
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '-40000',
                               'we_uGBPpm' => '-40000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '1000000',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '-40000',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             }
                           ],
                 'number_on_account' => 0
               }
}

Example 3

Query rates that I charge for numbers in ranges whose typeID=59, owned by telco whose telcoID=4:

Perl example request:

POST https://live.apicontrol.co.uk/1/json
my $res = $api->telecoms_rates_ingress
  (
    default => 1,
    range_typeID => 59,
    service => 'nts',
    telcoID => 4,
    ingress_type => 'pstn',
    svcchg_keyword => 'standard',
  );
print Dumper($res);

Example 3 response

There are no rates defined for that set of criteria:

Perl example response:

{
  'success' => 1,
  'error' => undef,
  'errornum' => '',
  'errordiags' => '',
  'results' => {
                 'data' => []
               }
}

Example 4

As the above example but defining a service charge against the numbers (as this is a range where we usually levy a monthly service charge):

Perl example request:

POST https://live.apicontrol.co.uk/1/json
my $res = $api->telecoms_rates_ingress
  (
    default => 1,
    range_typeID => 59,
    service => 'nts',
    telcoID => 4,
    ingress_type => 'pstn',
    svcchg_keyword => 'standard',
  );
print Dumper($res);

Example 4 response

Perl example response:

{
  'success' => 1,
  'error' => undef,
  'errornum' => '',
  'errordiags' => '',
  'results' => {
                 'data' => [
                             {
                               'pk_uGBPconn' => '0',
                               'freeseconds' => '0',
                               'minchg_uGBP' => undef,
                               'number' => '',
                               'offpk_uGBPpm' => '8000',
                               'we_uGBPpm' => '8000',
                               'we_uGBPpms' => '0',
                               'offpk_uGBPpms' => '0',
                               'ingress_type' => 'pstn',
                               'trigger_minutes' => '0',
                               'pk_uGBPpms' => '0',
                               'we_uGBPconn' => '0',
                               'pk_uGBPpm' => '8000',
                               'we_short_s' => '0',
                               'service' => '',
                               'offpk_short_s' => '0',
                               'offpk_uGBPconn' => '0',
                               'pk_short_s' => '0',
                               'custID' => '0',
                               'minseconds' => '0'
                             }
                           ]
               }
}