SearchLocalNum

Description

SearchLocalNum provides the ability to retrieve status information about one or more numbers based on search parameters. The search is limited to numbers owned by the api user's company. In addition to information about individual numbers, a count of numbers by status is also provided. Any status with a count of zero numbers will not be shown. The following are the allowed fields in reqparams:

dn A specific toll-free number. Setting this parameter limits the search to just this number.

resporg The controlling RespOrg. Setting this parameter limits the search to numbers controlled by this RespOrg.

resporgisnot When resporg is set, setting resporgisnot to 1 limits the search to numbers not controlled by the specified RespOrg (but still within the api user's company). Setting resporgisnot to 0 is equivalent to not providing it. resporg then behaves as described above.

statuslist A comma separated list of 8MS number status values. Setting this parameter limits the search to numbers in the one or more specified status values. Values should match the status words (case insensitive) shown on the Search Local Number user interface screen. The values include: Assigned, Disconnected, Reserved, Spare, Suspended, Transitional, Unavailable, Working. A default status of Working is set if no statuslist is specified.

statusisnot When statuslist is set, setting statusisnot to 1 limits the search to numbers not in the specific list of status values. Setting statusisnot to 0 is equivalent to not providing it. statuslist then behaves as described above.

maxnumbers The maximum amount of numbers to return. Setting this parameter restricts the amount of numbers to return, even if more numbers match. The first set of matching numbers found will be returned. The resulting XML contains two fields related to this. NumberTotal shows the total amount of numbers that matched the query. If maxnumbers has been specified and is less than NumberTotal then NumbersReturned will equal maxnumbers. Otherwise NumbersReturned will equal NumberTotal.

showcounts Setting this parameter causes the data returned to include only the count of numbers, by status. The actual numbers and related data are not returned.

The timeout parameter, available to all API calls, should not be set to less than 30 seconds for this call since this call does not support retrieving data after a timeout occurs.

Note that while none of the parameters are required for this call, at least one parameter must be specified. This does not include maxnumbers; if maxnumbers is specified another parameter must be specified.

Results

The result of a SearchLocalNum request is represented as an XML document. This XML document will be contained within the <msgparams> tag of the normal 8MS API return structure. For example, the following might be returned from a request:

<msgparams>
<SearchLocalNum>
<ShowCounts>
<Reserved>1</Reserved>
<Working>1</Working>
</ShowCounts>
<NumberTotal>2</NumberTotal>
<NumbersReturned>2</NumbersReturned>
<LocalNumbers>
<Numbers dn="800-555-1212">
<Status>Working>/Status>
<StatusDate>01/03/96</StatusDate>
<Resporg>ART01</Resporg>
<LastActive></LastActive>
<EndDate></EndDate>
</Numbers>
<Numbers dn="866-555-1212">
<Status>Reserved</Status>
<StatusDate>01/13/10</StatusDate>
<Resporg>ART01</Resporg>
<LastActive>02/10/05</LastActive>
<EndDate>02/27/10</EndDate>
</Numbers>
</LocalNumbers>
</SearchLocalNum>
</msgparams>

Each <Numbers> tag within the <LocalNumbers> tag consists of the following fields:

Numbers dn=tfn	The dn attribute of the Numbers tag contains the actual toll-free number.
Status	The status of the number.
StatusDate	The date and time the number attained the given status.
Resporg	The controlling RespOrg of this number.
LastActive	The date and time this number was last active.
EndDate	The date when this number will be returned to the Spare status. End dates may only be set for Reserved and Transitional numbers.

Example

The following request parameter will request all numbers in the Reserved status:

statuslist~reserved

	dn	A specific toll-free number. Setting this parameter limits the search to just this number.
	resporg	The controlling RespOrg. Setting this parameter limits the search to numbers controlled by this RespOrg.
	resporgisnot	When resporg is set, setting resporgisnot to 1 limits the search to numbers not controlled by the specified RespOrg (but still within the api user's company). Setting resporgisnot to 0 is equivalent to not providing it. resporg then behaves as described above.
	statuslist	A comma separated list of 8MS number status values. Setting this parameter limits the search to numbers in the one or more specified status values. Values should match the status words (case insensitive) shown on the Search Local Number user interface screen. The values include: Assigned, Disconnected, Reserved, Spare, Suspended, Transitional, Unavailable, Working. A default status of Working is set if no statuslist is specified.
	statusisnot	When statuslist is set, setting statusisnot to 1 limits the search to numbers not in the specific list of status values. Setting statusisnot to 0 is equivalent to not providing it. statuslist then behaves as described above.
	maxnumbers	The maximum amount of numbers to return. Setting this parameter restricts the amount of numbers to return, even if more numbers match. The first set of matching numbers found will be returned. The resulting XML contains two fields related to this. NumberTotal shows the total amount of numbers that matched the query. If maxnumbers has been specified and is less than NumberTotal then NumbersReturned will equal maxnumbers. Otherwise NumbersReturned will equal NumberTotal.
	showcounts	Setting this parameter causes the data returned to include only the count of numbers, by status. The actual numbers and related data are not returned.