Spectate provides an HTTP-based RESTful API. The resources match up exactly with the URLs of the objects in the web interface.

Authentication

All API requests require authentication via a valid API key. An API key is tied to specific user in a specific account. To find your API key:

  1. Login to Spectate.
  2. Go to My Settings at the top right.
  3. Locate your API Key in the My Information data table.

Accessing Resources

Just append the format of the data you desire (.json, .xml) and your API key as a api_key parameter to the URL of the request in the web interface.

XML: https://my.spectate.com/path/to/resource/1.xml?api_key=<your_api_key>
JSON: https://my.spectate.com/path/to/resource/1.json?api_key=<your_api_key>

Leads API:

Base resource URL: https://my.spectate.com/leads_visitors/leads

List all your leads

GET /leads_visitors/leads

Params and Options

  • extension - Append the extension for your desired data format
  • per_page  - The number of results per page. Default: 5. We recommend at most 100 for fast responses.
  • page  - The desired page
  • sort_by  - last_name , created_at , last_activity_at , updated_at . Default: created_at .The Lead field to sort the results by updated_at  is when the Lead object in Spectate last changed (has any one modified the Lead). last_activity_at is when the Lead was last active (e.g. last visited your site, filled out a form)
  • order_dir  - DESC  (descending) or ASC  (ascending). Default: DESC 
  • timeframe  - 24_hours , today , yesterday , 7_days , 14_days , 30_days , this_month , last_month , all_time  or custom . Default: all_time Time since the Lead was created. Use custom  if you intend to also pass a start_date  and end_date 
  • custom_start  - Format: MM/DD/YYYY. Only Leads created after 12am on the start_date  will be returned. Must use custom value for timeframe  param and must also specify a custom_end .
  • custom_end  - Format: MM/DD/YYYY. Only Leads created before 12am on the end_date  will be returned. Must use custom value for timeframe  param and must also specify a custom_start .

Examples:

Reading a Lead's data as XML or JSON with CURL.

To read the Lead data for the Lead with id=1(https://my.spectate.com/leads_visitors/leads/1), add:

  1. the format you want the data in as the extension
  2. a request parameter 'api_key' containing your API key

Request:

curl https://my.spectate.com/leads_visitors/leads/1.xml?api_key=<your_api_key>

Response:

<?xml version="1.0" encoding="UTF-8"?> 
<lead>
  <on-aws-blacklist type="boolean">false</on-aws-blacklist>
  <has-invalid-email type="boolean">false</has-invalid-email>
  <user-id type="integer" nil="true"></user-id>
  <address-two></address-two>
  <created-at type="datetime">2011-08-19T22:52:19Z</created-at>
  <crm-is-sale-won type="integer" nil="true"></crm-is-sale-won>
  <score type="integer" nil="true"></score>
  <crm-object-type nil="true"></crm-object-type>
  <last-campaign-id type="integer">4</last-campaign-id>
  <crm-last-sync type="datetime" nil="true"></crm-last-sync>
  <crm-lead-fid type="integer" nil="true"></crm-lead-fid>
  <crm-opportunity-fid type="integer" nil="true"></crm-opportunity-fid>
  <has-spam-report type="boolean">false</has-spam-report>
  <connector-id type="integer" nil="true"></connector-id>
  <crm-opportunity-created-at type="datetime" nil="true"></crm-opportunity-created-at>
  <company>Hannon Hill</company>
  <email>bradley.wagner@hannonhill.com</email>
  <department></department>
  <employees></employees>
  <phone></phone>
  <page-views-count type="integer">179</page-views-count>
  <crm-contact-fid type="integer" nil="true"></crm-contact-fid>
  <zip></zip>
  <territory></territory>
  <imported-prospect-id type="integer" nil="true"></imported-prospect-id>
  <is-do-not-call type="boolean">false</is-do-not-call>
  <city></city>
  <crm-account-fid type="integer" nil="true"></crm-account-fid>
  <last-activity-at type="datetime">2011-08-22T21:40:58Z</last-activity-at>
  <notes></notes>
  <twitter-username></twitter-username>
  <last-name>Wagner</last-name>
  <account-id type="integer">1</account-id>
  <crm-url nil="true"></crm-url>
  <updated-at type="datetime">2011-08-22T22:06:29Z</updated-at>
  <website></website>
  <is-reviewed type="boolean" nil="true"></is-reviewed>
  <opted-out type="boolean" nil="true"></opted-out>
  <country></country>
  <is-do-not-email type="boolean">false</is-do-not-email>
  <job-title></job-title>
  <annual-revenue></annual-revenue>
  <crm-opportunity-value type="datetime" nil="true"></crm-opportunity-value>
  <salutation></salutation>
  <is-starred type="boolean" nil="true"></is-starred>
  <source></source>
  <source-type>direct_traffic</source-type>
  <crm-opportunity-status nil="true"></crm-opportunity-status>
  <has-bounced-email type="boolean">false</has-bounced-email>
  <industry></industry>
  <first-name>Bradley</first-name>
  <years-in-business></years-in-business>
  <fax></fax>
  <first-campaign-id type="integer">4</first-campaign-id>
  <exported-prospect-id type="integer" nil="true"></exported-prospect-id>
  <crm-owner-fid type="integer" nil="true"></crm-owner-fid>
  <password nil="true"></password>
  <address-one></address-one>
  <crm-opportunity-updated-at type="datetime" nil="true"></crm-opportunity-updated-at>
  <grade nil="true"></grade>
  <crm-id nil="true"></crm-id>
  <state></state>
  <recent-interaction nil="true"></recent-interaction>
  <id type="integer">777</id>
  <campaign-id type="integer" nil="true"></campaign-id>
  <comments></comments>
  <custom-fields-count type="integer">0</custom-fields-count>
</lead>

Request:

curl https://my.spectate.com/leads_visitors/leads.json?api_key=<API_KEY>

Response:

{
    "current_page": 1,
    "per_page": 2,
    "total_entries": 11,
    "leads": [{
        "lead": {
            "account_id": 2,
            "id": 1,
            "created_at": "2012-03-30T15:20:08-04:00",
            ... see "Get a Lead" section for more lead fields ...
        }
    }, {
        "lead": {
            "account_id": 2,
            "id": 2,
            "created_at": "2012-03-15T17:00:07-04:00",
            ...
        }
    }]
}
Did this answer your question?