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. Adding Events to a News Feed
    3. All Approved Events
    4. All Unapproved Events
    5. All Unviewed Events
    6. All Contacts with Unviewed Events
    7. Filtering All News Feeds by Event
    8. Marking News Feed Events as Viewed
    9. Marking All News Feed Events In A Single Feed as Viewed
    10. Marking All News Feed Events as Viewed
    11. Marking News Feed Events as Approved
    12. All Events in a News Feed
    13. All Approved Events in a News Feed
    14. All Unapproved Events in a News Feed
    15. All Unviewed Events in a News Feed
    16. Filtering a News Feed by Event
    17. Removing an Event from a News Feed
  3. Events Description
  4. Expansions
  5. API Explorer

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 (As Portal Group) 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 (As Portal Group) Yes Yes
Private Yes Yes
More information about roles may be found here.

Available Services

All Events

URI: /<API Version>/newsfeeds/events

URI: /<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/1600x1280/true/20080917142739989238000000-o.jpg",
                            "Uri2048": "http://resize.sparkplatform.com/demomls/2048x1536/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,
                    "NotificationSent": true,
                    "Viewed": false,
                    "Restricted": false
                }
            },
            {
                "ResourceUri": "/vX/listings/20141231185022829466000000",
                "Id": "20141231185022829466000000",
                "StandardFields": {},
                "NewsFeed": {
                    "Type": "Listing",
                    "Events": [],
                    "LastEventTimestamp": "2013-06-28T20:09:37Z",
                    "Approved": true,
                    "NotificationSent": true,
                    "Viewed": false,
                    "Restricted": true
                }
            }
        ]
    }
}

Adding Events to a News Feed

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events

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

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Adds events for a provided data point to a specified news feed. (100 events per request max). No
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

POST Request

Request body:
{
    "D": {
        "Events": [
            {
                "Id": "20100815220615294367000000",
                "NewsFeed": {
                    "Type": "Listing"
                }
            }
        ]
    }
}

POST Response

The standard 'accepted for processing' response is returned.

All Approved Events

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

Private Role Only. 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

URI: /<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

URI: /<API Version>/newsfeeds/events/unviewed

URI: /<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

URI: /<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

URI: /<API Version>/newsfeeds/events/<Event>

URI: /<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

URI: /<API Version>/newsfeeds/events/<Id>

URI: /<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

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events

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

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events/before/<Datetime>

URI: /<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

URI: /<API Version>/newsfeeds/events

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

URI: /<API Version>/newsfeeds/events/before/<Datetime>

URI: /<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

URI: /<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

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events

URI: /<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

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

Private Role Only. 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

URI: /<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

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events/unviewed

URI: /<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

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events/<Event>

URI: /<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

URI: /<API Version>/newsfeeds/<NewsFeed.Id>/events/<Id>

URI: /<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:
  • None

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 No 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.
NotificationSent Boolean Yes true if the event was delivered in an e-mail or push notification to the subscriber.
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.

API Explorer

The API Explorer does not currently support this service.