Listings: History

Supported Roles
Available Services
1. Listing History
Listing History Description
Expansions

Supported Roles

Role	Reads	Writes	Notes
IDX	Yes	No
Public	Yes	No
VOW	Yes	No
Portal	Yes	No
Private	Yes	No	Only private roles see full listing history information. All other roles access a condensed set of data, and may be completely restricted from access by the MLS.

More information about roles may be found here.

Available Services

Listing History

`/<API Version>/listings/<Listing.Id>/history`

HTTP Method	Description	Conditional	Notes
GET	Returns the full history for the listing.	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
Pagination	No

GET Response

{
    "D": {
        "Results": [
            {
                "ChangedBy": {
                    "Id": "20110112234857732941000000",
                    "ResourceUri": "/v1/accounts/20110112234857732941000000",
                    "UserType": "Member",
                    "Name": "Joe Realtor",
                    "OfficeId": "20100113238853732842000000",
                    "Office": "Joe's Realty",
                    "CompanyId": null,
                    "Company": null,
                    "FbsIdxCustomer": false,
                    "MlsId": "20100127075503180752000000"
                    "PrimaryEmail": {
                      "Id": "20120424173947957808000000",
                      "Name": "Office E-Mail",
                      "Primary": true,
                      "Type": "Office",
                      "Address": "myoffice@example.com"
                    },
                    "PrimaryPhone": {
                      "Id": "20120424173948048729000000",
                      "Name": "Office Phone",
                      "Primary": true,
                      "Type": "Office",
                      "Number": "555-555-555",
                      "InternationalCode": nil,
                      "AreaCode": "555",
                      "Prefix": "555",
                      "LineNumber": "5555",
                      "Extension": nil
                    },
                    "PrimaryWebsite": {
                      "Id": "20120424173948178569000000",
                      "Name": "Office Web Site",
                      "Primary": true,
                      "Uri": "http://example.org",
                      "Type": "Office"
                    },
                    "Images": [
                        {
                            "Id": "20110426173018175220000000",
                            "Type": "Photo",
                            "Name": "My Photo",
                            "Uri": "http://photos.sparkplatform.com/az/...."
                        },
                        {
                            "Id": "20080426173011752890000000",
                            "Type": "Logo",
                            "Name": "My Logo",
                            "Uri": "http://photos.sparkplatform.com/az/...."
                        }
                    ]
                },
                "Group": null,
                "Domain": null,
                "NewValue": "Main List #1",
                "Event": "Photo",
                "Action":"Added",
                "Field": null,
                "PreviousValue": null,
                "PriceAtEvent": 100000.0,
                "PriceChange": null,
                "Listing": {
                  "Id": "20160225211938590559000000",
                  "StandardFields": {
                    "ListingId": "16-1"
                  }
                },
                "ModificationTimestamp": "2012-03-06T16:28:42Z"
            },
            {
                "ChangedBy": {
                    "Id": "20110112234857732941000000",
                    "ResourceUri": "/v1/accounts/20110112234857732941000000",
                    "UserType": "Member",
                    "Name": "Joe Realtor",
                    "OfficeId": "20100113238853732842000000",
                    "Office": "Joe's Realty",
                    "CompanyId": null,
                    "Company": null,
                    "FbsIdxCustomer": false,
                    "MlsId": "20100127075503180752000000"
                    "PrimaryEmail": {
                      "Id": "20120424173947957808000000",
                      "Name": "Office E-Mail",
                      "Primary": true,
                      "Type": "Office",
                      "Address": "myoffice@example.com"
                    },
                    "PrimaryPhone": {
                      "Id": "20120424173948048729000000",
                      "Name": "Office Phone",
                      "Primary": true,
                      "Type": "Office",
                      "Number": "555-555-555",
                      "InternationalCode": nil,
                      "AreaCode": "555",
                      "Prefix": "555",
                      "LineNumber": "5555",
                      "Extension": nil
                    },
                    "PrimaryWebsite": {
                      "Id": "20120424173948178569000000",
                      "Name": "Office Web Site",
                      "Primary": true,
                      "Uri": "http://example.org",
                      "Type": "Office"
                    },
                    "Images": [
                        {
                            "Id": "20110426173018175220000000",
                            "Type": "Photo",
                            "Name": "My Photo",
                            "Uri": "http://photos.sparkplatform.com/az/...."
                        },
                        {
                            "Id": "20080426173011752890000000",
                            "Type": "Logo",
                            "Name": "My Logo",
                            "Uri": "http://photos.sparkplatform.com/az/...."
                        }
                    ]
                },
                "Group": null,
                "Domain": null,
                "NewValue": null,
                "Event": "NewListing",
                "Action": null,
                "Field": null,
                "PreviousValue": null,
                "PriceAtEvent": 100000.0,
                "PriceChange": null,
                "Listing": {
                  "Id": "20150125213438589559000000",
                  "StandardFields": {
                    "ListingId": "15-100"
                  }
                },
                "ModificationTimestamp": "2007-06-26T15:55:50Z"
            }
        ],
        "Success": true
    }
}

Listing History Description

Attribute	Data Type	Description
`Event`	Character	The history event type. See the table below for a description of the various event types.
`Action`	Character	The type of action that took place for the `Event's`. See the table below for a description of the various action types. Not all events will have a corresponding action.
`Domain`	Character	The type of listing field. Either `StandardFields` or `CustomFields`.
`Group`	Character	The unique group field identifier for the custom field. `null` if the history event was not an operation on a standard or custom field.
`Field`	Character	The standard or custom field that was changed, if any.
`Listing.Id`	Character	The Id of the listing the history event is for.
`Listing.StandardFields.ListingId`	Character	The ListingId (MLS #) of the listing the history event is for.
`PreviousValue`	Character	The original data value, before the change occurred.
`NewValue`	Character	The new data value.
`PriceAtEvent`	Decimal	The listing price at the time the history event occurred.
`PriceChange`	Decimal	The decimal percentage the listing price changed, if the price was modified.
`ModificationTimestamp`	Timestamp	The date and time when the history event occurred.
`MlsId`	Character	The user's MLS Id
`ChangedBy`	Accounts	A list of user accounts linked to each user.

Event Types

Type	Description
`BackOnMarket`	A special status change event where a listing goes from an off market status to 'Active'.
`CopyListing`	Records when a new listing is copied from another existing listing.
`Document`	Tracks when a document was uploaded, modified, or removed.
`Extension`	A special date-change event where the `ExpirationDate` is pushed out into the future.
`FieldChange`	A generic event referencing any time a standard or custom field was modified.
`Geocode`	Geocode events track when a listing's lat/lon coordinates are updated with a geocoder.
`ListingApproval`	History events that center around submitting a listing for approval, rejecting a listing, and approving a listing.
`NewListing`	Records when a listing is first entered into the system.
`OpenHouse`	Tracks when an open house event was added or modified.
`Photo`	Tracks when a photo was uploaded, modified, or removed.
`Supplement`	Tracks when a supplement was added or modified.
`TextChange`	A generic event that occurs any time a feature field is updated in flexmls. These rarely have associated field data.
`TourOfHomes`	Tracks when an tour of homes event was added or modified.
`VirtualTour`	Tracks when a virtual tour was uploaded, modified, or removed.

Action Types

Type	Description	Example
`Added`	A new record was added to the system.	A listing photo was uploaded.
`Approved`	A record in moderation was approved.	An unapproved listing was approved by MLS staff.
`Copied`	A record was copied from another piece of data. Identifying information will often be present in `PreviousValue`.	Photos were copied from another listing.
`Edited`	An existing record was modified.	A document associated with a listing was modified.
`Manual`	When the option for automation is available, an end user opted instead to manually enter data.	A listing was manually geocoded when an end user explicitly referenced its location on a map.
`Pended`	A record entered moderation, or is pending some other action.	A listing is awaiting approval.
`Primary`	Another record is now considered "primary" in a collection of data.	The listing's primary photo now references a new photo.
`Rejected`	A record in moderation was rejected.	A listing awaiting review was rejected.
`Reset`	Data was reset to default values.	A listing's geocode data was reset.
`Removed`	A record was deleted.	A virtual tour was removed from a listing.
`Resubmitted`	A record previously in moderation has re-entered moderation.	A rejected listing was modified and resubmitted for review.
`Rotated`	A photo was rotated.
`Watermarked`	A photo was watermarked.

History Restrictions

Some events are restricted depending on MLS settings, the current user viewing the listing, and the data role of the API key accessing the history data. However, non-private role keys (as well as private role keys for certain MLSs) only see a limited set of the above events.

These events are:

NewListing
BackOnMarket
FieldChange for the following fields:
- ListPrice
- MlsStatus
- MlsStatusInformation
- Contingency
- RentOrLeasePrice

Expansions

None.