Introduction

This document is a guide to the web services made available to Bullseye clients. Our web services are implemented as REST services, written in C# under .Net. They are easily accessed via .Net/C#, PHP, or any other language/platform that supports REST web services.

All methods accept a client ID and API key. They will be assigned to you. The methods will return status code 401, unauthorized, if the ID and/or API key are incorrect. In addition, as an alternative, the Location and Lead Web Service methods will allow you to first authenticate the client ID and API key, then pass the authetication key to any of the available methods in either service.

There are two types of default API keys: SEARCH keys and ADMIN keys. A search key can only be used with the search service. An admin key can be used with the search service as well as the user and location services. The purpose of this distinction is for security. The search service cannot be used to alter data, only retrieve it. The additional user and location services available to the admin key can be used to alter data, so the ADMIN API key should be guarded more closely.

The default keys cannot be edited, however, additional API keys can be created and secured with restrictions to HTTP referrers and/or IP addresses, and Bullseye services. To support Map Broker and the Map Requests report, keys MUST be restricted to the URL or IP address making the call, and assigned to the RestSearch service.

All methods also accept a UserIPAddress. We recommend that you include this parameter. If you specify a user IP address, then this will be checked against the list of blocked IP addresses for this client. If the address is on the block list, the search will not be performed, and a 403 (forbidden) response code will be returned. Passing this argument also causes the given IP address to be logged, if search logging is enabled for this client. (If the user IP is not passed in, then the IP of the machine calling the web service will be logged.)

The REST services return JSON, and accept their parameters on the query string (or via JSON).

We also have a number of SOAP web services available, though we are in the process of deprecating our SOAP API.