API Request Information

In this section, you will find general information on API requests including: empty XML elements, error codes, page, results per page, total results, match confidence, and XML schemas.

Empty XML Elements

Empty XML elements are almost always omitted from the output. However a few empty XML elements are output. For example, Match requests will return an empty personMatch or companyMatch XML element in the case where a particular input record results in no matches being returned.

Expected Error Responses

See the expected error responses below. For Person Match and Company Match, you will see an additional error code with each error message.


Error Response
Error Code
Causes
Invalid input parameter '<name of invalid input parameter>'

Occurs when you include an invalid parameter in a request. The error message will include the name of the invalid parameter.
Authentication failed
1002
Occurs when authentication fails due to an invalid key.
Authorization Failed
1006
Occurs due to one of the following:
·         Query Type Authorization - The partner code provided does not have permission to use the given query or match request type
·         Search Field Authorization - The partner code provided does not have permission to use one or more search parameters provided
Could not load partner '<partner code provided>'
1011
Occurs when the partner code provided is not valid.
No valid search parameters specified
1023
Occurs when you do not provide any valid search parameters in a search request. This error message occurs only for Person Detail and Company Detail queries.
No valid match parameters specified
1024
Occurs when you do not provide any valid match parameters for a match request. This error message occurs only for person match and company match requests.
Zero results returned

Occurs when you do not provide valid search parameters for a Person search or Company Search. This does not result in an actual error message, rather the resulting XML will simply contain no results.
Paging Error: Query Timeout!

Occurs when the complexity of the search query is such that we do not complete processing the query in a reasonable amount of time and therefore abort processing the query. Please try again, or simplify the search query. This error message does not occur for person match and company match requests.
The value entered for the numMatches parameter exceeds the limit on the number of match results. The limit is '<maximum number of matches per input record>'
1015
Occurs when the numMatches value which was input exceeds the maximum number of matches per input record - which is currently 10.
The number of match input records entered exceeds the limit on the number of match input records. The limit is '<maximum number of input records>'
1016
Occurs when the number of input records exceeds the maximum number of input records - which is currently 25.
You have exceeded your overall API query request limit. Please contact Zoom Information, Inc.
1013
Occurs when the query usage exceeds the overall query limit and the limit type is a hard limit.
You have exceeded your <query type> API query type request limit. Please contact Zoom Information, Inc.
1043
Occurs when the query usage exceeds the API query type query limit and the limit type is a hard limit.


Total Results

For Person Search and Company Search, the response returns a TotalResult element. The following explains how we determine this value. TotalResults is the lesser of:

  • Max API Results (5000)
  • Total number of results available
  • Results per query limit configured for the given query type based on your partner agreement

Max Results

For Person search and Company Search, the response returns a MaxResults element. This elements contains how many results we have available in Solr for the query being performed.

Results Per Page and Page Parameter Usage

Person Search and Company Search API requests both accept input parameters rpp and page. These parameters allow callers to page through the results of a search, having a subset of the results displayed with each response. The rpp and page parameters are intended to be used in conjunction with one another and must both be values greater than zero if specified. Your partner agreement governs the usage of these parameters and may restrict the valid values.

Page defaults to page 1 and rpp (results per page) defaults to 500. Thus, by changing only the page parameter, you can page through up to the 10th page at 500 results per page in order to get the full 5000 possible results. Additional pages are specified as follows:

&page=2, &page=3, &page=4,

For another example, if you requested rpp=25 and page=2, you would get the second page of 25 results. This would result in a response containing results 26-50 of your query.

Match Confidence

For Person Match and Company Match requests, the response returns a matchConfidence element. This value is a floating point number between 0 and 100 which represents the relative confidence in the match being returned for that input record. Generally, the more data that matched between the input record and the person or company being returned as a match, the higher the match confidence value will be.


Was this article helpful?

Can’t find what you’re looking for?

Contact our award-winning customer care team.