Developer Documentation
Platform Overview
Spark API FAQ Advantages of Spark/RESO Web APIs Over RETS How to Set Up API Access Which API is Right for You? Flexmls WordPress Plugin and Smartframe
Authentication
Overview OpenID Connect Access Token SAML Spark API Auth Supplemental Authentication Services
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: Required Documents 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: Hot Sheet Parameters Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Required Documents 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: Groups News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Notifications Open Houses Overlays Overlays: Geometries Portals Portals: Listing Categories Portals: Metadata 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
Attribute Selection App Submission Process Conditional Requests Error Codes Escaping Parameters Expansions Listing Display Rules Location Proximity RESO Dictionary Versions RESO Web API Replication Roles Spark Replication Spark API Parameters SparkQL Grammar Standard Response Format Timespan Tile Information Service
Examples
Displaying Standard Field Labels Location Searches Making Fast API Requests Searching Listings Setting Up Portal/VOW Accounts
RESO Web API
Overview Request Parameters Lookup Green Verification Media Member Office OpenHouse Power Production Property Room Unit
RETS
Overview Contact RETS Support Help for MLSs Programs & Tools RETS Listing Activity API Troubleshooting Examples: DMQL Examples: HiRes Photos Examples: Photo Downloads Examples: Photo & Doc names Examples: Replicate Examples: Session Examples: Supplements
FloPlan
Overview Spark API RESO Web API RETS Standalone FloPlan API
Terms of Use
MLS Platform License Agreement Developer Agreement and Terms of Use MLS Member Terms of Use Consumer Terms of Use Spark Store Terms of Use Privacy Policy

Privileged API Keys Only

Special permission is required to access this service. Please contact api-support@sparkplatform.com or your API key provider to request access to this data.

News Feed: Events

News feed events are a stream (most recent first) of interesting events to subscribed data points. For instance, a saved search subscription will track listing change events for listings that match that search.

 

Multiple RESO Dictionary Support
This service supports multiple RESO Data Dictionary versions.

 

Event Expiration

Events will eventually expire based on set rules in the prospecting system. Please read the Newfeed Expiration guidelines for more information.

 
  1. Supported Roles
  2. Available Services
    1. All Events
    2. All Approved Events
    3. All Unapproved Events
    4. All Unviewed Events
    5. All Contacts with Unviewed Events
    6. Filtering All News Feeds by Event
    7. Marking News Feed Events as Viewed
    8. Marking All News Feed Events In A Single Feed as Viewed
    9. Marking All News Feed Events as Viewed
    10. Marking News Feed Events as Approved
    11. All Events in a News Feed
    12. All Approved Events in a News Feed
    13. All Unapproved Events in a News Feed
    14. All Unviewed Events in a News Feed
    15. Filtering a News Feed by Event
    16. Removing an Event from a News Feed
  3. Events Description
  4. Expansions
 

Supported Roles

Role Reads Writes Notes
IDX No No
Public Yes Yes Reads are limited to approved events and all approved events. Writes are limited to marking events as viewed, marking all events in a feed as viewed, and marking all events as viewed.
VOW Yes Yes Writes are limited to marking events as viewed, marking all events in a single feed as viewed, and marking all events as viewed.
Portal Yes Yes
Private Yes Yes

More information about roles may be found here.

 

Available Services

All Events

/<API Version>/newsfeeds/events
/<API Version>/contacts/<Contact.Id>/newsfeeds/events

Events are across all news feeds, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns events in the news feed. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listings/20060412165917817933000000",
                "Id": "20060412165917817933000000",
                "StandardFields": {
                    "ListingKey": "20060412165917817933000000",
                    "ListingId": "10-1796",
                    "PropertyType": "A",
                    "PropertySubType": "SF",
                    "ListPrice": 1079900,
                    "StreetNumber": "611",
                    "Photos": [
                        {
                            "ResourceUri": "/vX/listings/20060412165917817933000000/photos/20080917142739989238000000",
                            "Id": "20080917142739989238000000",
                            "Name": "Listing Photo",
                            "Caption": "",
                            "UriThumb": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-t.jpg",
                            "Uri300": "http://photos.sparkplatform.com/demomls/20080917142739989238000000.jpg",
                            "Uri640": "http://resize.sparkplatform.com/demomls/640x480/true/20080917142739989238000000-o.jpg",
                            "Uri800": "http://resize.sparkplatform.com/demomls/800x600/true/20080917142739989238000000-o.jpg",
                            "Uri1024": "http://resize.sparkplatform.com/demomls/1024x768/true/20080917142739989238000000-o.jpg",
                            "Uri1280": "http://resize.sparkplatform.com/demomls/1280x1024/true/20080917142739989238000000-o.jpg",
                            "Uri1600": "http://resize.sparkplatform.com/demomls/1600x1200/true/20080917142739989238000000-o.jpg",
                            "Uri2048": "http://resize.sparkplatform.com/demomls/2048x1600/true/20080917142739989238000000-o.jpg",
                            "UriLarge": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-o.jpg",
                            "Primary": true
                        }
                    ]
                },
                "NewsFeed": {
                    "Type": "Listing",
                    "Events": ["New", "PriceChange"],
                    "LastEventTimestamp": "2013-06-28T20:09:37Z",
                    "Approved": true,
                    "Viewed": false,
                    "Restricted": false
                }
            },
            {
                "ResourceUri": "/vX/listings/20141231185022829466000000",
                "Id": "20141231185022829466000000",
                "StandardFields": {},
                "NewsFeed": {
                    "Type": "Listing",
                    "Events": [],
                    "LastEventTimestamp": "2013-06-28T20:09:37Z",
                    "Approved": true,
                    "Viewed": false,
                    "Restricted": true
                }
            }
        ]
    }
}
 
 

All Approved Events

/<API Version>/contacts/<Contact.Id>/newsfeeds/events/approved

All approved events for the contact across all news feeds, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns all approved events. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

All Unapproved Events

/<API Version>/contacts/<Contact.Id>/newsfeeds/events/unapproved

Private Role Only. All unapproved events for the contact across all news feeds, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns all unapproved events. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

All Unviewed Events

/<API Version>/newsfeeds/events/unviewed
/<API Version>/contacts/<Contact.Id>/newsfeeds/events/unviewed

All unviewed events for the contact across all news feeds, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns all unviewed events. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

All Contacts with Unviewed Events

/<API Version>/newsfeeds/events/unviewed/contacts

Returns pagination information for all contacts with unviewed events. (e.g. only supports _pagination=count)

HTTP Method Description Conditional Notes
GET Returns a count of all contacts with unviewed events. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

{
    "D": {
        "Success": true,
        "Results": [],
        "Pagination": {
            "TotalRows": 78
        }
    }
}
 
 

Filtering All News Feeds by Event

/<API Version>/newsfeeds/events/<Event>
/<API Version>/contacts/<Contact.Id>/newsfeeds/events/<Event>

Filters events across all news feeds to those of the specified Event type.

HTTP Method Description Conditional Notes
GET Filters data from all news feed by event No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

Marking News Feed Events as Viewed

/<API Version>/newsfeeds/events/<Id>
/<API Version>/contacts/<Contact.Id>/newsfeeds/events/<Id>

When marking a listing, or other data, as Viewed, the action will be performed for all existing events for the same data across all news feeds. Subsequent listing events will have a Viewed attribute of false.

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Flags as viewed No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body: 

{
   "D":{
     "NewsFeed": {
       "Viewed": true
     }
   }
}
 

PUT Response

The standard success/fail response is returned.

 
 

Marking All News Feed Events as Viewed

/<API Version>/newsfeeds/<NewsFeed.Id>/events
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events
/<API Version>/newsfeeds/<NewsFeed.Id>/events/before/<Datetime>
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events/before/<Datetime>

Listings present in the specified feed will be marked as Viewed across all feeds. If the before resource is used, all events last updated prior to a given date are marked as Viewed.

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Flags as viewed No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body: 

{
   "D":{
     "NewsFeed": {
       "Viewed": true
     }
   }
}
 

PUT Response

The standard 'accepted for processing' response is returned.

 
 

Marking All News Feed Events as Viewed

/<API Version>/newsfeeds/events
/<API Version>/contacts/<Contact.Id>/newsfeeds/events
/<API Version>/newsfeeds/events/before/<Datetime>
/<API Version>/contacts/<Contact.Id>/newsfeeds/events/before/<Datetime>

Marks all events across all news feeds as Viewed. If the before resource is used, all events last updated prior to a given date are marked as Viewed.

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Flags as viewed No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body: 

{
   "D":{
     "NewsFeed": {
       "Viewed": true
     }
   }
}
 

PUT Response

The standard 'accepted for processing' response is returned.

 
 

Marking News Feed Events as Approved

/<API Version>/contacts/<Contact.Id>/newsfeeds/events/<Id>

When marking a listing, or other data, as Approved, the action will be performed for all existing events for the same data across all news feeds. Subsequent listing events will have a Approved attribute of true.

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Flags as approved No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body: 

{
   "D":{
     "NewsFeed": {
       "Approved": true
     }
   }
}
 

PUT Response

The standard success/fail response is returned.

 
 

All Events in a News Feed

/<API Version>/newsfeeds/<NewsFeed.Id>/events
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events

HTTP Method Description Conditional Notes
GET Returns events in the news feed. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed events service.

 

All Approved Events in a News Feed

/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events/approved

All approved events for a contact in a given news feed, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns approved events in the news feed. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

All Unapproved Events in a News Feed

/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events/unapproved

Private Role Only. All unapproved events for a contact in a given news feed, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns unapproved events in the news feed. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

All Unviewed Events in a News Feed

/<API Version>/newsfeeds/<NewsFeed.Id>/events/unviewed
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events/unviewed

All unviewed events for a contact in a given news feed, ordered by most recent event timestamp.

HTTP Method Description Conditional Notes
GET Returns unviewed events in the news feed. No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the news feed service.

 

Filtering a News Feed by Event

/<API Version>/newsfeeds/<NewsFeed.Id>/events/<Event>
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events/<Event>

Filters events in a news feed to those of the specified Event type.

HTTP Method Description Conditional Notes
GET Filters a news feed by event No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

Parameter Required Notes
Standard search and paging syntax No
 
 

GET Response

See the GET request section for for the events service.

 

Removing an Event from a News Feed

/<API Version>/newsfeeds/<NewsFeed.Id>/events/<Id>
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/events/<Id>

Private Role Only. Only agents may remove an event from a news feed.

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Removes an event from a specified news feed. No

DELETE Request

Parameters:

 

DELETE Response

The standard success/fail response is returned.

 
 

Events Description

Attribute Data Type Searchable Description
NewsFeedId Character Yes (Search Field Only) Restricts events to those present in news feeds with the provided Id. Only supports the Eq operator.
SubscriptionId Character Yes (Search Field Only) Restricts events to those present in news feeds with subscriptions to searches with the provided Id. Only supports the Eq operator.
StandardFields Various types All viewable standard listing field attributes are returned with this response, for listing data. Note that the primary photo is also included for listings.
NewsFeed JSON Object Information about the event that occurred for the corresponding data point.
Events Character List Yes A list of Events that occurred since the listing was last viewed. If a specific event occurred more than once since last viewed, it will still only occur in the array once.
LastEventTimestamp Timestamp No The time when the last event present in Events occurred.
Type Character No The type of news feed data the event occurred for. Currently, only Listing data is delivered from the news feed service.
Approved Boolean Yes true if the record has been flagged as 'approved' for viewal by the agent. Read more about curated news feeds here.
Restricted Boolean No true if the event records an action that is no longer viewable for the current user or at the current role.
Viewed Boolean Yes true if the record has been flagged as 'viewed' by the user.
 

Below are the existing Event types.

Event Data Types News Feed Types Description
New Listing SavedSearch A property is initially listed.
OpenHouse Listing SavedSearch An open house is added to the listing. This event corresponds to the date the open house was added, not the date when the open house occurs.
Pending Listing SavedSearch A property's status changes to Pending.
PriceChange Listing SavedSearch A property has its list price changed.
Sold Listing SavedSearch A property's status changes to Sold.
BackOnMarket Listing SavedSearch A previously off-market property becomes Active again.
Extension Listing SavedSearch An Active property's ExpirationDate is extended.
StatusChange Listing SavedSearch A status change event occurred not covered by another event.
Recommended Listing RecommendedCart The listing was recommended by an agent (by being placed in the Recommended cart).
Seeded Listing SavedSearch Uncurated saved search subscriptions created through Spark® are seeded with the 100 most recent results. Listings added through this process have the event Seeded.
 

Expansions

Expansion Roles Single Record Only? Selection Support? Description
NewsFeeds All No No A list of news feeds the data has events in.
OpenHouses All No No Returns the OpenHouses expansion with all listing events.
PortalCarts Portal, VOW No No A list portal carts the listing is in.
TourOfHomes Private No No Returns the TourOfHomes expansion with all listing events.