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

Standard Response Format

  1. Success without resource creation
  2. Success with resource creation
  3. Accepted for future processing
  4. Success with data version
  5. Failure response
  6. Error and warning information
  7. Failure due to SparkQL _filter errors
 

Success without resource creation

The HTTP response status code is in the range of 200-299.

{
    "D": {
        "Success": true
    }
}
 

Success with resource creation

The HTTP response status code is in the range of 200-299. ResourceUri indicates the path to the newly-created resource.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/servicename/XXXXX"
            }
        ]
    }
}
 

Accepted for future processing

The HTTP response status code is always 202 (Accepted). When API resources reply with a 202: Accepted, the requested data creation or update is scheduled for future processing.

{
    "D": {
        "Success": true
    }
}
 

Success with data version

The HTTP response status code is in the range of 200-299. For resources that support it, the Version attribute can used in the versions subresource to return the data to a previous state state. Note that many resources have an expiration after which the version cannot be restored. When deleting data, the version returned points to the data at a state just before deletion, and can be used to restore the data from deletion.

{
    "D": {
        "Success": true,
        "Version": 1
    }
}
 

Failure response

The HTTP response status code is not in the range of 200-299. Available Code and Message values are documented on the Spark® API error code page. Codes are provided so API clients may handle errors more easily than by parsing a message.

{
    "D": {
        "Success": false,
        "Code": 1234,
        "Message": "Spark API message describing the problem"
    }
}
 

Error and warning information

Some services support an additional Errors attribute that further elaborates on why a request was unsuccessful, or to provide warnings about a successful response.

Failure with Errors example

{
    "D": {
        "Success": false,
        "Code": 1234,
        "Message": "Spark API message describing the problem",
        "Errors": [
            {
                "Type": "InvalidRecord",
                "Record": {
                    /* Record or part of recrod POST or PUT to the API */
                },
                "Errors": [
                    {
                        "Type": "InvalidAttribute",
                        "Attribute": "DisplayName",
                        "Message": "The combination of DisplayName and PrimaryEmail must be unique"
                    },
                    {
                        "Type": "InvalidAttribute",
                        "Attribute": "Pets",
                        "Message": "Cannot be null"
                    },
                    {
                        "Type": "RuleViolation",
                        "Attribute": "BathsTotal",
                        "Message": "Field is required",
                        "Status": "Fatal",
                        "Display": {
                          "Message": "Please enter a value",
                          "Documentation": "There are many fields the that require values before a listing may be accepted. This happens to be one of them.",
                          "DocumentationUri": "http://example.com/listingrules/further_reading"
                        },
                        "Rule": {
                            "Id": 1,
                            "ResourceUri": "/v1/listings/rules/1",
                            "Group": null,
                            "Domain": null,
                            "Field": "BathsTotal"
                        }
                    }
                ]
            }
        ]
    }
}

Success with Errors example

{
    "D": {
        "Results": [
            {
                "ResourceUri": "/v1/savedsearches/20200000000000000000000002",
                "Id": "20200000000000000000000002",
                "OwnerId": "20200000000000000000000001",
                "Name": "Saved Search",
                "Description": null,
                "ContactIds": [],
                "UnsubscribedContactIds": [],
                "ModificationTimestamp": "2021-02-08T17:27:04Z",
                "Filter": "MapOverlay Eq '20200000000000000000000003' And City Eq 'Fargo' And ListPrice Ge 10000.00 And MlsStatus Eq 'Active' And PropertyType Eq 'A'",
                "Annotations": [],
                "QuickSearchId": "20200000000000000000000003",
                "Tags": [],
                "Provided": false,
                "CreatedTimestamp": "2020-11-16T17:16:11+00:00",
                "LastRunTimestamp": "2021-01-12T06:00:00Z",
                "BookmarkTimestamp": null,
                "ProtectedFromDeletion": false
            }
        ],
        "Success": true,
        "Errors": [
            {
                "Type": "InvalidRecord",
                "Message": null,
                "Status": "Warn",
                "Record": {
                  "Filter": "ListPrice Gt 100000",
                  "OwnerId": "20000426143505724628000000",
                  "Name": "EE Junk Search",
                  "Annotations": [
                    {
                        "Type": "Shape",
                        "Match": {
                            "Substring" => "MapOverlay Eq '20200000000000000000000007'"
                        },
                        "Attributes": {
                            "Color": "0077D9",
                            "Label": "Dutch Elms Subdivision"
                        }
                    }
                  ]
                },
                "Errors": [
                    {
                        "Type": "SavedSearchAnnotationRejected",
                        "Message": "An Annotation was rejected because its Match is missing or does not match the Filter.",
                        "Status": "Warn",
                        "Record": {
                            "Type": "Shape",
                            "Match": {
                                "Substring" => "MapOverlay Eq '20200000000000000000000007'"
                            },
                            "Attributes": {
                                "Color": "0077D9",
                                "Label": "Dutch Elms Subdivision"
                            }
                        }
                    }
                ]
            }
        ]
    }
}
 
Field Supported Types Description
Type All The error type.
Message All An additional developer-friendly message sometimes provided along with the error data.
Status All Optionally, an indication of the severity of the error, either Fatal or Warn.
Display All Optionally, an additional user-friendly attribute which may include a Message, Documentation, and DocumentationUri.
Attribute InvalidAttribute, RuleViolation The invalid attribute present (or missing) from the POST or PUT data.
Errors InvalidRecord A list of InvalidAttribute or RuleViolation errors for the Record.
Record InvalidRecord The POST or PUT data that failed validation.
Rule RuleViolation The rule that triggered the error.
 
Error Type Description
InvalidAttribute An attribute did not pass validation when creating or updating data.
InvalidRecord The data provided when updating or creating a record did not pass validation. This type of error includes an Errors attribute with a list of InvalidAttribute or RuleViolation errors.
RuleViolation The data provided when updating or creating a record did not pass rules for that data type. This type of error includes a Rule attribute for resource-specific rules, such as Listing Rules.
SavedSearchAnnotationRejected A proposed or existing SavedSearch Annotation is or became invalid, for instance because the Filter substring it is associated with is no longer present in the Filter.
 

Failure due to SparkQL _filter errors

When a request fails due to an invalid _filter parameter or a field is dropped, the additional attribute SparkQLErrors will be present to provided additional detail about the filter problem.

{
    "D": {
        "Message": "The SavedSearch you specified is not available.",
        "Code": 2001,
        "Success": false,
        "SparkQLErrors": [
            {
                "Expression": "SavedSearch Eq '20151441993689437314000000'",
                "Token": "SavedSearch",
                "TokenIndex": 0,
                "Message": "The SavedSearch you specified is not available",
                "Status": "Fatal",
                "SparkQL": null,
                "SparkQLErrors": []
            }
        ]
    }
}
 
Attribute Description
Expression The expression where the error was detected. Some syntax errors will not allow a complete expression to be detected, and in those cases, the value will be null.
Token The offending token.
TokenIndex The starting position of the offending token in the filter string. Begins at 0.
Message An error message further describing the problem, when more detail can be provided.
Status Fatal, Warn, or Dropped.

When Fatal, the request could not be completed due to the error.

When Warn, the field may not have been entirely dropped, but the SparkQL associated with it had dropped fields. This status is most commonly seen when retrieving the results for a saved search.

When Dropped, the specific error resulted in the parser ignoring the expression. Expressions are dropped most often when an MLS disables a field present in existing searches, so sites running pre-existing saved searches to not appear broken to the end user after the setting has changed.

SparkQL Present when the Token references a resource that embeds SparkQL in the search, such as a saved search.
SparkQLErrors Present when the Token references a resource that embeds SparkQL in the search, such as a saved search. TokenIndex, in this case, will reference the position of the token in the SparkQL attribute in the parent SparkQLErrors list.