Developer Documentation
Platform Overview
Authentication
API Services
Overview Accounts Accounts: Associations Accounts: Metadata Accounts: Profile Appstore: Users Broker Distributions Broker Tours Consumers Consumers: Linked Agents Contacts Contacts: Activity Contacts: Export Contacts: Tags Contacts: Portal Accounts Developers: Identities Developers: Keys Developers: Authorizations Developers: Billing Summary Developers: Change History Developers: Domains Developers: News Feed Webhooks Developers: Roles Developers: Syndications Developers: Templates Developers: Usage Detail Developers: Usage Summary Devices Flexmls: Email Links Flexmls: Listing Meta Origins Flexmls: Listing Meta Translations Flexmls: Listing Meta Field List Translations Flexmls: Listing Reports Flexmls: Mapping Layers Flexmls: Mapping Shapegen IDX IDX Links Listing Carts Listing Carts: Portal/VOW Carts Incomplete Listings Incomplete Listings: Documents Incomplete Listings: Documents Metadata Incomplete Listings: Document Uploads Incomplete Listings: Floor Plans Incomplete Listings: FloPlans Incomplete Listings: Photos Incomplete Listings: Photos Metadata Incomplete Listings: Photo Uploads Incomplete Listings: Rooms Incomplete Listings: Tickets Incomplete Listings: Units Incomplete Listings: Videos Incomplete Listings: Videos Metadata Incomplete Listings: Virtual Tours Incomplete Listings: Virtual Tours Metadata Listings Listings: Clusters Listings: Documents Listings: Documents Metadata Listings: Floor Plans Listings: FloPlans Listings: Historical Listings: History Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Rooms Listings: Rules Listings: Tour of Homes Listings: Tickets Listings: Units Listings: Validation Listings: Videos Listings: Videos Metadata Listings: Virtual Tours Listings: Virtual Tours Metadata Listing Meta: Custom Fields Listing Meta: Custom Field Groups Listing Meta: Field Order Listing Meta: Field Relations Listing Meta: Property Types Listing Meta: Rooms Listing Meta: Standard Fields Listing Meta: Units Registered Listings Market Statistics News Feed News Feed: Curation News Feed: Events News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Open Houses Overlays Overlays: Geometries Portals Preferences Saved Searches Saved Searches: Provided Saved Searches: Restrictions Saved Searches: Tags Search Templates: Quick Searches Search Templates: Views Search Templates: Sorts Shared Links System Info System Info: Languages System Info: Search Templates
Supporting Documentation
Examples
RESO Web API
RETS
FloPlan
Terms of Use

Spark® API Authentication

If you are not sure which authentication method to use, please read the Overview page.

The Spark API authentication procedure is as follows:

  1. The developer API key is signed and sent to the authentication service over SSL.
  2. The authentication service responds with a session token.
  3. Each subsequent request to the API must include a token and be properly signed.

Session tokens are good for a maximum of 24 hours, and have an idle timeout of 1 hour. After the session token has expired, authentication must occur again. Only one session token may be active for any single API key at one time. Authentication is designed to require the use of a proxy service to avoid exposing the shared secret in a user’s browser.

 
Notes
  • Requests to the /session service must be made using HTTPS, but requests to other services may be made with HTTP or HTTPS.
  • Only one session token may be active for an API key at any time.
 

Session management (Spark API auth only)

URI: /<API Version>/session

Verb Outcome Notes
GET Returns HTTP 405 (Method Not Allowed)
Extends the session for another timeout period
Not implemented
The GET response is the same as the POST response
POST Create a new session See parameters below
PUT Returns HTTP 405 (Method Not Allowed) Not implemented
DELETE Returns HTTP 405 (Method Not Allowed)
Terminates the current session immediately
Not implemented
Returns the Standard Response Format

Parameters for all requests

Parameter Required Notes
ApiKey Yes Your API key
ApiSig Yes Signature for this request, generated as described below

POST Request

To create a new session, POST to the following URI with an empty POST body, substituting the proper ApiKey and ApiSig parameters:

https://sparkapi.com/v1/session?ApiKey=12345&ApiSig=2fde9e59147081ad4e39382e1f809710
 

Signature Generation

ApiSig, the signature for this request, is generated by creating an MD5 hexadecimal representation of the following string:

[secret]ApiKey[key]
 

Example: Assume [secret] is 1234 and [key] is abcd . The string to be processed with MD5 would then be:

1234ApiKeyabcd
 

The above string, when processed with MD5 will be: 2fde9e59147081ad4e39382e1f809710

POST Response

If a new session is successfully created, the response payload will look like the following:

{
  Success: true,
  Results: [ {
    AuthToken: "xxxxx",
    Expires: "2010-10-30T15:49:01-05:00"
  }]
}
 

Authenticated Requests (Spark API auth only)

Subsequent calls to the API after a session is created may be made with either HTTP or HTTPS and have a similar format:

https://sparkapi.com/v1/contacts?AuthToken=1234&ApiSig=3ebbd149f28c69c19fa0f38d5bb4d14
 

In all authenticated calls to the system, AuthToken and ApiSig are required.

Signatures for authenticated calls are generated by creating an MD5 hexadecimal representation of the following string:

[secret]ApiKey[key]ServicePath[service_path]param1[param1]...paramN[paramN][POST data]
 

Example: assume [secret] is 1234, [key] is abcd and full request is http://sparkapi.com/v1/contacts?AuthToken=9876&name=John+Contact&email=contact@fbsdata.com&phone=555-5555&group=IDX+Lead. The string to be processed with MD5 would be as follows:

1234ApiKeyabcdServicePath/v1/contactsAuthToken9876emailcontact@fbsdata.comgroupIDX LeadnameJohn Contactphone555-5555
 

Where <Signature> is replaced with the signature you generated above, your final request would look like:


http://sparkapi.com/v1/contacts?AuthToken=9876&name=John+Contact&email=contact@fbsdata.com&phone=555-5555&group=IDX+Lead&ApiSig=<Signature>
 

Expiration of tokens (Spark API auth only)

Tokens have a maximum life of 1 day (24 hours). The token will also expire if more than 60 minutes pass since the last request. When a session expires, an HTTP 401 status code will be returned on any request to the API with the following payload:

{
  "D": {
    "Success": false,
    "Message": "Session token has expired",
    "Code": 1020
  }
}
 

When the token expires, an authentication call must be made to retrieve a new token. The original request must then be subsequently repeated.