GetSpares

Description

Spare Number Forecast is a feature that uses the SMS/800 History database to determine what numbers will be coming spare in the near future.

GetSpares retrieves a list of toll-free numbers that will be coming spare in the near future. The search may be restricted to specific NPAs or toll-free numbers. SMS/800 wildcard patterns (* and &) may be used in the toll-free number field. Start and end dates may be used to restrict the search even more. The following are the allowed fields in reqparams:

npalist A comma separated list of NPAs to be searched.

dn A single toll-free number or a number pattern. A number pattern contains alphanumerics plus the standard SMS/800 wildcard characters, * and &, plus two additional pattern match characters, ^ and $.
This parameter takes up to seven characters. Note that the NPA is not included in this parameter. If less than seven characters are provided the search function will assume the pattern may appear anywhere in the number. Putting a ^ at the start of the pattern indicates that the pattern must appear at the start of the number. Putting a $ at the end of the pattern indicates that the pattern must appear at the end of the number.

startdate The earliest expected spare date. The format of this value is:
mm/dd/yy

enddate The latest expected spare date. The format of this value is:
mm/dd/yy

order The ordering of the list of numbers. Valid values are telnumber, resporg, sparedate.

trailingdigits The number of digits (0-2) that may be added on to the number to allow longer spelled words. Words may then be up to 9 letters long excluding the NPA. This parameter is optional.

resporg A full or partially specified resporg. This limits the search to numbers whose current resporg matches this resporg. This parameter is optional.

retrievelimit The maximum amount of numbers to retrieve. If the value specified exceeds the system limit, the system limit is used. This parameter is optional.

Results

A GetSpares response is an XML document embedded within the normal API response. A typical XML response will have the following fields.

<msgparams>
<getspares>
<count>amount found</count>
<numberdata>
<dn>first toll-free number</dn>
<resporg>resp org</resporg>
<sparedate>date to go spare</sparedate>
</numberdata>
<numberdata>
<dn>second toll-free number</dn>
<resporg>resp org</resporg>
<sparedate>date to go spare</sparedate>
</numberdata>
</getspares>
</msgparams>

Example

The following request parameters will retrieve a list of all 877 numbers coming spare between May 1 and May 7, 2007.

npalist~877;startdate~05/01/07;enddate~05/07/07;

	npalist	A comma separated list of NPAs to be searched.
	dn	A single toll-free number or a number pattern. A number pattern contains alphanumerics plus the standard SMS/800 wildcard characters, * and &, plus two additional pattern match characters, ^ and $. This parameter takes up to seven characters. Note that the NPA is not included in this parameter. If less than seven characters are provided the search function will assume the pattern may appear anywhere in the number. Putting a ^ at the start of the pattern indicates that the pattern must appear at the start of the number. Putting a $ at the end of the pattern indicates that the pattern must appear at the end of the number.
	startdate	The earliest expected spare date. The format of this value is: mm/dd/yy
	enddate	The latest expected spare date. The format of this value is: mm/dd/yy
	order	The ordering of the list of numbers. Valid values are telnumber, resporg, sparedate.
	trailingdigits	The number of digits (0-2) that may be added on to the number to allow longer spelled words. Words may then be up to 9 letters long excluding the NPA. This parameter is optional.
	resporg	A full or partially specified resporg. This limits the search to numbers whose current resporg matches this resporg. This parameter is optional.
	retrievelimit	The maximum amount of numbers to retrieve. If the value specified exceeds the system limit, the system limit is used. This parameter is optional.