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: Schedule
The Schedule sub-service manages the notifications delivered to news feed subscribers when listings are updated.
There are two types of schedules: default schedules and per-news feed schedules.
A default schedule applies to all Active news feeds that do not have a specific
schedule. Accordingly, default schedules are ignored when a news feed has a custom schedule created
for it.
Supported Roles
| Role | Reads | Writes | Notes |
|---|---|---|---|
| IDX | No | No | |
| Public | No | No | |
| VOW | Yes | Yes | |
| Portal | Yes | Yes | |
| Private | Yes | Yes |
More information about roles may be found here.
Available Services
Default Notifications
/<API Version>/newsfeeds/schedule
/<API Version>/contacts/<Contact.Id>/newsfeeds/schedule
Default notifications apply to news feeds that do not have a custom schedule.
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Retrieve all scheduled events for the current user's default schedule. Note that, currently, only a single default schedule entry can exist for a user. | No | |
| POST | Creates a new default notification | No | |
| PUT | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| DELETE | Deletes all default notifications for a news feed | No |
GET Request
Parameters:
- None
GET Response
{
"D": {
"Success": true,
"Results": [
{
"Id": "20100000000000000000000000",
"ResourceUri": "/vX/newsfeeds/schedule/20100000000000000000000000",
"NewsfeedId": null,
"Frequency": "Scheduled",
"HoursOfDay": [1],
"DaysOfWeek": ["Sunday", "Monday", "Tuesday"],
"DaysOfMonth": [1,2],
"CreatedTimestamp": "2013-07-07T12:12:06-05:00"
}
]
}
}
POST Request
Request body:
{
"D": {
"Frequency": "Instant"
}
}
POST Response
The standard success/fail response is returned.
DELETE Request
Parameters:
- None
DELETE Response
The standard success/fail response is returned.
Individual Default Schedule
/<API Version>/newsfeeds/schedule/<Id>
/<API Version>/contacts/<Contact.Id>/newsfeeds/schedule/<Id>
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns an individual default notification | No | |
| POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| PUT | Updates a default notification schedule. | No | |
| DELETE | Deletes a default newsfeed notification | No |
GET Request
Parameters:
- None
GET Response
See the GET request section for for the news feed schedule service..
PUT Request
Request body:
{
"D": {
"Frequency": "Scheduled",
"DaysOfWeek": ["Monday", "Tuesday", "Wednesday"]
}
}
PUT Response
The standard success/fail response is returned.
DELETE Request
Parameters:
- None
DELETE Response
The standard success/fail response is returned.
All Scheduled Notifications
/<API Version>/newsfeeds/<NewsFeed.Id>/schedule
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/schedule
Currently, only one schedule may exist for each news feed.
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns schedule information for a news feed. | No | |
| POST | Schedules a new news feed notification. | No | |
| PUT | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| DELETE | Deletes all scheduled notifications for a news feed | No |
GET Request
Parameters:
- None
GET Response
{
"D": {
"Success": true,
"Results": [
{
"Id": "20100000000000000000000000",
"ResourceUri": "/vX/newsfeeds/20100000000000000000000001/schedule/20100000000000000000000000",
"NewsfeedId": "20100000000000000000000001",
"Frequency": "Scheduled",
"HoursOfDay": [1],
"DaysOfWeek": ["Sunday", "Monday", "Tuesday"],
"DaysOfMonth": [1,2],
"CreatedTimestamp": "2013-07-07T12:12:06-05:00"
}
]
}
}
POST Request
Request body:
{
"D": {
"Frequency": "Instant"
}
}
POST Response
The standard success/fail response is returned.
DELETE Request
Parameters:
- None
DELETE Response
The standard success/fail response is returned.
Individual Notification Schedule
/<API Version>/newsfeeds/<NewsFeed.Id>/schedule/<Id>
/<API Version>/contacts/<Contact.Id>/newsfeeds/<NewsFeed.Id>/schedule/<Id>
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns an individual notification schedule. | No | |
| POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| PUT | Updates a newsfeed notification schedule. | No | |
| DELETE | Deletes a scheduled newsfeed notification | No |
GET Request
Parameters:
- None
GET Response
See the GET request section for for the news feed schedule service..
PUT Request
Request body:
{
"D": {
"Frequency": "Scheduled",
"DaysOfWeek": ["Monday", "Tuesday", "Wednesday"]
}
}
PUT Response
The standard success/fail response is returned.
DELETE Request
Parameters:
- None
DELETE Response
The standard success/fail response is returned.
Schedule Description
| Attribute | Data Type | Writeable | Required | Description |
|---|---|---|---|---|
ResourceUri |
Character | No | No | The URI to a scheduled notification. |
Id |
Character | No | No | The unique id for the scheduled notification. |
Frequency |
Character | Yes | No | 'Scheduled' or 'Instant'. If unspecified, will be detected by the absense (Instant) or presence (Scheduled) of the HoursOfDay, DaysOfWeek and DaysOfMonth fields. Read more about Instant notifications below. |
HoursOfDay |
Integer List | Yes | No | The hours of the day (0-23) the notification should be delivered on. A null value implies that the default hour for the MLS should be used, which may vary and can change. |
DaysOfWeek |
Character List | Yes | No | The days of the week (Sunday-Saturday) to deliver notifications on. A null value means every day, unless DaysOfMonth is specified. |
DaysOfMonth |
Integer List | Yes | No | The days of the month (1-31) to deliver notifications on. A null value means every day, unless DaysOfWeek is set. |
WebhookId |
Character | Yes | No | The webhooks to send the notifications
for this news feed to. The following restrictions apply:
See the webhooks documentation for more information on these types of notifications. |
CreatedTimestamp |
Timestamp | No | No | The date and time when the scheduled notification was last created. |
Instant Notifications Explained
For certain news feed events, the Instant frequency is treated
specially. The table below details the algorithm for Instant
schedules for these types of events.
| Event | Instant schedule |
|---|---|
New |
New events are delayed by roughly 10 minutes. This is done to allow the person
entering the listing data time to make initial corrections before users are notified. |
Expired |
Expired events are consolidated together into bulk
notifications instead of being sent out individually. They will be sent out en mass roughly
one hour after the first event. |
Closed |
Some MLSs auto-close listings overnight. When this process is running, Closed
events are consolidated into bulk notifications, just like Expired events. |
Recommended |
The notification for the first listing with a Recommended event is immediate
For the next hour, subsequent Recommended listings are queued to be delivered
in a single notification once the hour has passed. |
Expansions
None.