Registrant Search API Documentation
Version 1
View Example PHP Implementation
QUERY FORMAT:
	http://www.domaintools.com/api.xml?
		appname=registrant_search 					&
		partner=partnername 						&
		key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX 				&
		mode=preview - OR - mode=order - OR - mode=count_price_only	& <---	"preview" will hide full domain and prevent historical WHOIS lookups
		 									"order" will show full domain and show crypt for performing historical WHOIS lookups
		 									"count_price_only" will return count and price but no results
		
		Append your query to the URL:
		
		(multiple terms)
		and[]=Term1&and[]=Term2&and[]=Term3 ...
		not[]=Term4&not[]=Term5&not[]=Term6 ...
		
		- OR -
		
		(multiple terms)
		includes[]=Term1&includes[]=Term2&includes[]=Term3 ...
		excludes[]=Term4&excludes[]=Term5&excludes[]=Term6 ...
		
		- OR -
		
		(single term)
		and=Term1&not=Term2
		
		- OR -
		
		(single term)
		includes=Term1&excludes=Term2
Notes:
  1. At least one and/includes term must be passed.
  2. The not/excludes term is optional.
  3. Mode will default to preview if it is not specified explicitly
  4. You can mix & match singular vs. plural terms
    • i.e. and[]=Term1&not=Term2 , includes=Term1&not[]=Term2
    • BUT NOT and[]=Term1&includes=Term2 or includes[]=Term1&and[]=Term2
  5. You can search for the following terms (includes) without being charged to test your API implementation:
    • "Tim Curry" "Amy Winehouse" "Tom Clancy"

EXAMPLE PREVIEW RESPONSE
The following queries will all have a similar response, you may see some difference in the <request> section of the XML response depending on the terms you choose. 
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=preview&and=Tim%20Curry
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=preview&includes=Tim%20Curry
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=preview&and[]=Tim%20Curry
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=preview&includes[]=Tim%20Curry


	<?xml version="1.0"?>
	<whoisapi>
		<application>
			<engine>dev</engine>
			<appname>registrant_search</appname>
			<version>1</version>
			<partner>partnername</partner>
			<key>XXXXX-XXXXX-XXXXX-XXXXX-XXXXX</key>
			<token/>
		</application>
		<request>
			<mode>preview</mode>
			<and>Tim Curry</and>
		</request>
		<response>
			<hits_today>2</hits_today>
			<querytime>0.558</querytime>
			<price>74.00</price>
			<count>25</count>
			<results>
				<result>
					<id>W~~~~~~.~~~</id>
					<version>
			  			<date>20050201</date>
					</version>
					<version>
						<date>20051105</date>
					</version>
					<version>
						<date>20070811</date>
					</version>
		  		</result>
			</results>
		</response>
	</whoisapi>

EXAMPLE ORDER RESPONSE
Using the same query as above, specifying the order mode, our results have a slightly different format. We can use the crypt key from each unique WHOIS version against the Historical WHOIS XML API to view the domain's WHOIS record at that specific date in the historical archive.

Note: You may need to url-encode the crypt key for the Historical WHOIS XML API request before sending it so that special characters are not passed as URL parameters or converted to their respective HTML special characters (i.e. convert "+" to "  .

http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=order&and=Tim%20Curry
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=order&includes=Tim%20Curry
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=order&and[]=Tim%20Curry
http://www.domaintools.com/api.xml?appname=registrant_search&partner=partnername&key=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX&mode=order&includes[]=Tim%20Curry


	<?xml version="1.0"?>
	<whoisapi>
		<application>
			<engine>dev</engine>
			<appname>registrant_search</appname>
			<version>1</version>
			<partner>partnername</partner>
			<key>XXXXX-XXXXX-XXXXX-XXXXX-XXXXX</key>
			<token/>
		</application>
		<request>
			<mode>order</mode>
			<includes>a:1:{i:0;s:9:"Tim Curry";}</includes>
		</request>
		<response>
			<hits_today>30</hits_today>
			<querytime>0.041</querytime>
			<price>74.00</price>
			<count>25</count>
			<results>
				<result>
					<id>wetdogs.com</id>
					<version hash="14a3ccb7" crypt="1J45b8H+QBahLZvXxA0hcN9jF8Rz05u8">
						<date>20050201</date>
					</version>
					<version hash="57b80c84" crypt="1J45b8H+QBahLZvXxA0hcLF1NxyK+BFR">
						<date>20051105</date>
					</version>
					<version hash="b3ac9344" crypt="1J45b8H+QBY0/uoYMtA6tF8lkbr29+3/">
						<date>20070811</date>
					</version>
				</result>
			</results>
		</response>
	</whoisapi>

ERROR RESPONSES
	<?xml version="1.0"?>
	<whoisapi>
		<application>
			<engine>dev</engine>
			<appname>registrant_search</appname>
			<version>1</version>
			<partner>partnername</partner>
			<key>XXXXX-XXXXX-XXXXX-XXXXX-XXXXX</key>
			
			<token/>
		</application>
		<request>
			<includes>Bob</includes>
			<mode>order</mode>
		</request>
		<errors>
			<msg>		
				<errid>1</errid>
				<desc>Too many results, please make your search more specific.</desc>
				<errorcode>402</errorcode>
			</msg>
		</errors>
		<response>
			<hits_today>13</hits_today>		
			<querytime>0.008</querytime>
		</response>
	</whoisapi>
Error CodeDescription
401Partner/Key pair is invalid
402Too many results, please make your search more specific.
482Insufficient arguments provided in request.