Alpha Only: This service is subject to change

This service is a work in progress. It is currently subject to change or removal without notice.

Listings: Rules

Rulesets can be defined for each property type in an MLS that govern how listing data is entered into the system. Examples of listing rules are 'required fields' and 'conditionally required fields'.

Supported Roles
Available Services
Listings: Rules Description
Expansions

Supported Roles

Role	Reads	Writes	Notes
IDX	No	No
Public	No	No
VOW	No	No
Portal	No	No
Private	Yes	Yes	Special permission is required to modify rules for an MLS.

More information about roles may be found here.

Available Services

Listing Rules Metadata

`/<API Version>/listings/rules/meta`

HTTP Method	Description	Conditional	Notes
GET	Gets rules metadata.	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:

None

GET Response

{
        "D": {
                "Success": true,
                "Results": [
                        {
                                "Action": ["ACCEPT", "REJECT", "SET", "SET_DEFAULT", "SET_DISPLAY", "SET_PICKLIST", "RESTRICT_PICKLIST", "SET_READ_ONLY", "SET_REQUIRED", "WARNING"],
                                "ApprovalStatus": ["In Review", "Published", "Deactivated"],
                                "Domain": ["StandardFields", "CustomFields"]
                        }
                ]
        }
}

Listing Rules

`/<API Version>/listings/rules`

HTTP Method	Description	Conditional	Notes
GET	Returns HTTP 405 (Method Not Allowed)	No	Not implemented
POST	Creates a new listing rule or set of rules for the same `PropertyType`.	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":{
     "PropertyType": "A",
     "Group": null,
     "Domain": null,
     "Field": "BathsTotal",
     "Action": "SET_REQUIRED",
     "Expression": "StandardStatus = 'Active'",
     "Summary": "FBS-123, part 1",
     "Description": "We require total baths for active listings because xyz..."
   }
}

POST Response

The standard success/fail response with additional error information is returned.

Individual Listing Rule

`/<API Version>/listings/rules/<Rule.Id>`

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	Updates an existing rule.	No
DELETE	Deletes a rule	No

PUT Request

Request body:

{
   "D":{
      "Action": "SET_REQUIRED",
      "Order": 1
   }
}

PUT Response

The standard success/fail response with additional error information is returned.

DELETE Request

Parameters:

None

DELETE Response

The standard success/fail response is returned.

Listing Rules for a Property Type

`/<API Version>/listings/rules/propertytypes/<PropertyType.MlsCode>`

HTTP Method	Description	Conditional	Notes
GET	Returns all rules for a property type	No
POST	Adds a new rule to a property type	No
PUT	Replaces all rules for a property type	No
DELETE	Returns HTTP 405 (Method Not Allowed)	No	Not implemented

GET Request

Parameters:

Parameter	Required	Notes
Pagination	No	`_limit` can be set to `all` to return all records.

GET Response

{
        "D": {
                "Success": true,
                "Results": [{
                                "Id": 1,
                                "ResourceUri": "/vX/listings/rules/1",
                                "Group": null,
                                "Domain": null,
                                "Field": "BathsTotal",
                                "Action": "SET_REQUIRED",
                                "Expression": "StandardStatus = 'Active'",
                                "ApprovalStatus": "Published",
                                "Editable": false,
                                "ModificationTimestamp": "2012-03-06T16:28:42Z",
                                "CreatedTimestamp": "2012-03-06T16:28:42Z"
                        },
                        {
                                "Id": 2,
                                "ResourceUri": "/vX/listings/rules/2",
                                "Group": null,
                                "Domain": null,
                                "Field": "ListPrice",
                                "Action": "SET_REQUIRED",
                                "Expression": null,
                                "ApprovalStatus": "In Review",
                                "Editable": true,
                                "ModificationTimestamp": "2012-03-06T16:29:21Z",
                                "CreatedTimestamp": "2012-03-06T16:29:21Z"
                        }
                ]
        }
}

POST Request

Request body:

{
   "D": {
     "Group": null,
     "Domain": null,
     "Field": "BathsTotal",
     "Action": "SET_REQUIRED",
     "Expression": "StandardStatus = 'Active'"
   }
}

POST Response

The standard success/fail response with additional error information is returned.

PUT Request

Request body:

{
   "D": [
      {
         "Group": null,
         "Domain": null,
         "Field": "BathsTotal",
         "Action": "SET_REQUIRED",
         "ApprovalStatus": "Published",
         "Expression": "StandardStatus = 'Active'"
      },
      {
         "Group": null,
         "Domain": null,
         "Field": "ListPrice",
         "Action": "SET_REQUIRED",
         "Expression": null
      }
   ]
   
}

PUT Response

The standard success/fail response with additional error information is returned.

Listing Rules for an Action

`/<API Version>/listings/rules/propertytypes/<PropertyType.MlsCode>/actions/<Rule.Action>`

HTTP Method	Description	Conditional	Notes
GET	Returns all rules for a specific action and property type	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	`_limit` can be set to `all` to return all records.

GET Response

See the GET request section for for the Listing Rules for a Property Type service.

Listing Rules for a Field

`/<API Version>/listings/rules/propertytypes/<PropertyType.MlsCode>/fields/<Rule.FieldName>`

HTTP Method	Description	Conditional	Notes
GET	Returns all rules for a specific field and property type	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	`_limit` can be set to `all` to return all records.

GET Response

See the GET request section for for the Listing Rules for a Property Type service.

Listing: Rules Description

Attribute	Data Type	Writeable	Required	Description
`Id`	Character	No	No	The unique id for the rule.
`ResourceUri`	Character	No	No	The URI to the individual rule.
`Order`	Integer	Yes	No	The position of the rule in the full result set for a property type. The value must be greater than 0, and any number higher than the total number of rules will position the rule at the default location: the last position in the list.
`Domain`	Character	Creation only	Yes	May be one of the following: `StandardFields` or `CustomFields`.
`Group`	Character	Creation only	If `Domain` is `CustomFields`	The custom fields group for the field.
`FieldName`	Character	Creation only	Yes	The standard or custom field name the `Action` applies to.
`Action`	Character	Yes	Yes	May be one of the following: `ACCEPT`, `REJECT`, `SET`, `SET_DEFAULT`, or `SET_REQUIRED`.
`Expression`	Character	Yes	No	A validation `Expression` for setting field values or conditionally applying a rule `Action`.
`ApprovalStatus`	Character	Yes	No	May be one of the following: `In Review`, `Published`, or `Deactivated`. New rules are `In Review` by default and only `Published` rules are active during validation processing.
`Editable`	Boolean	No	No	Indicates whether the current user may edit this rule.
`ModificationTimestamp`	Timestamp	No	No	The date and time when the history event occurred.
`CreatedTimestamp`	Timestamp	No	No	The date and time when the history event occurred.
`Status`	Character	No	No	`Fatal`, `Warn` or `Dropped`. This attribute is only present in the `Errors` attribute when validating requests.
`Summary`	Character	Yes	No	A brief note about the origins of or reasoning behind a rule, for example a reference to related issues in an issue or project tracker. Available via `Summary` expansion.
`Description`	Character	Yes	No	A potentially detailed note about the origins of or reasoning behind a rule. Available via `Description` expansion.
`Source`	Character	No	No	An indication of where the rule came from, for example whether it was manually entered into the API or populated via an automated process. Available via `Source` expansion.
`Display.Message`	Character	Yes	No	An error message suitable for display to users explaining why the rule failed to pass. The `Message` is returned with the rule during listing validation. Available via the `Display` expansion.
`Display.Documentation`	Character	Yes	No	Detailed information about the rule and error message, which may provide additional tips for resolving problems than the `Message` may allow. Available via the `Display` expansion.
`Display.DocumentationUri`	Character	Yes	No	An optional link to external information about a rule. When present, this URI may be used by an MLS to direct the user to documentation not available from the application directly. Available via the `Display` expansion.

Actions

Name	Expression example	Description
`ACCEPT`	`StandardStatus = 'Active'`	When true, the field is accepted a valid and all subsequent validation rules for this field will be skipped. However, any `SET` actions will still be enforced.
`REJECT`	`ListPrice < 0`	When true, the field is rejected and all subsequent validation rules for this field including `SET` actions will be skipped.
`RESTRICT_PICKLIST`	`('Fargo','Moorhead')`	This is the counterpart to `SET_PICKLIST`, but validates to support all values in the `PICKLIST` except for what's in the expression list.
`SET`	`Acres / 43560`	Set a value to be saved. This overrides any value specified by a previous rule.
`SET_DEFAULT`	`'Active'`	Prefill the value on a new listing.
`SET_DISPLAY`	`.TRUE.`	Indicator that this field should display to the user on the client. The API does not validate this expression.
`SET_PICKLIST`	`('Fargo','Moorhead')`	On a field that has a `PICKLIST`, this action will fail validation if the field value is not a part of the subset provided. The values in the expression must be members of the field's `PICKLIST`.
`SET_READ_ONLY`	`.TRUE.`	Indicator that this field is not allowed to change by the user. The field will fail validation if the user has updated the value.
`SET_REQUIRED`	`.TRUE.`	The `FieldName` must have a value.
`WARNING`	`.ENTRY. < 0`	When true, a warning message will be included in the response for `FieldName`, but validation will still succeed.

Expansions

Expansion	Roles	Single Record Only?	Selection Support?	Description
`Summary`	Private	No	No	Include the `Summary` attribute in results.
`Description`	Private	No	No	Include the `Description` attribute in results.
`Source`	Private	No	No	Include the `Source` attribute in results.
`Display`	Private	Yes	No	Include the `Display` expansion for an individual rule.