MLS Grid API

https://docs.mlsgrid.com/api-documentation
Admin
MLS Grid API is an OData-based web API that provides access to real estate listing data, member...
Tokens:16,307
Snippets:124
Trust Score:7.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example Property Data from Actris

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This snippet shows an example of a single property record as returned by the Actris system. It includes various details about the property, its features, and listing information.

```javascript
{
    "@odata.id": "https://api-demo.mlsgrid.com/v2/Property('ACT107472571')",
    "AccessibilityFeatures": [
        "Customized Wheelchair Accessible"
    ],
    "ACT_ActiveOpenHouseCount": "0",
    "AdditionalParcelsYN": false,
    "Appliances": [
        "Built-In Gas Oven",
        "Built-In Gas Range",
        "Dishwasher",
        "Microwave"
    ],
    "AssociationYN": false,
    "BathroomsFull": 3,
    "BathroomsHalf": 0,
    "BathroomsTotalInteger": 3,
    "BedroomsTotal": 4,
    "BuyerAgencyCompensation": "3.000",
    "BuyerAgencyCompensationType": "%",
    "BuyerOfficeKey": "ACT1513635",
    "CoBuyerOfficeKey": "ACT1513635",
    "CommunityFeatures": [
        "None"
    ],
    "ConstructionMaterials": [
        "HardiPlank Type"
    ],
    "Cooling": [
        "Ceiling Fan(s)",
        "Central Air"
    ],
    "CountyOrParish": "Williamson",
    "CoveredSpaces": 0,
    "DirectionFaces": "East",
    "Disclosures": [
        "Owner/Agent"
    ],
    "ACT_ElementaryOther": "Gateway College Prep",
    "ElementarySchool": "Jo Ann Ford",
    "ACT_EstimatedTaxes": "4934.00",
    "ACT_ETJExtraTerritorialJurdn": "No",
    "ExteriorFeatures": [
        "None"
    ],
    "ACT_FEMAFloodPlain": "No",
    "Fencing": [
        "Back Yard",
        "Front Yard"
    ],
    "FireplacesTotal": 0,
    "Flooring": [
        "Vinyl"
    ],
    "FoundationDetails": [
        "Slab"
    ],
    "GarageSpaces": 0,
    "GreenEnergyEfficient": [
        "None"
    ],
    "GreenSustainability": [
        "None"
    ],
    "ACT_GuestAccommodatonDesc": "None",
    "Heating": [
        "Central"
    ],
    "HighSchool": "East View",
    "HorseAmenities": [
        "None"
    ],
    "HorseYN": false,
    "ACT_IDXOptInYN": "1",
    "InteriorFeatures": [
        "Ceiling Fan(s)",
        "Beamed Ceilings",
        "Gas Dryer Hookup",
        "Kitchen Island",
        "Multiple Dining Areas",
        "No Interior Steps",
        "Open Floorplan",
        "Primary Bedroom on Main",
        "Washer Hookup"
    ],
    "InternetAddressDisplayYN": true,
    "InternetAutomatedValuationDisplayYN": false,
    "InternetConsumerCommentYN": false,
    "InternetEntireListingDisplayYN": true,
    "ACT_LastChangeTimestamp": "2020-12-05T15:32:42.710",
    "ACT_LastChangeType": "Price Decrease",
    "ACT_LastHumanModificationTimestamp": "2020-12-05T15:41:31.400",
    "ACT_LaundryLocation": "Main Level",
    "Levels": [
        "One"
    ],
    "ListAgentAOR": "Austin Board Of Realtors",
    "ListAgentDirectPhone": "(512) 400-0188",
    "ListAgentEmail": "michael.villanueva@cbunited.com",
    "ListAgentFullName": "Michael Villanueva",
    "ListAgentKey": "ACT31371801",
    "ListAgentMlsId": "ACT717866",
    "ListAOR": "Austin Board Of Realtors",
    "ListingContractDate": "2020-10-10",
    "ListingId": "ACT1475089",
    "ListingKey": "ACT107472571",
    "ListOfficeKey": "ACT1513635",
    "ListOfficeMlsId": "ACT024R11",
    "ListOfficeName": "Coldwell Banker Realty",
    "ListOfficePhone": "(512) 233-4868",
    "ListPrice": 474800,
    "LivingArea": 2400,
    "LivingAreaSource": "Public Records",
    "LotFeatures": [
        "Back Yard",
        "Trees-Moderate"
    ],
    "LotSizeAcres": 0.223,
    "LotSizeSquareFeet": 9713.88,
    "MainLevelBedrooms": 4,
    "MajorChangeTimestamp": "2020-12-05T21:32:42.000Z",
    "MajorChangeType": "Price Decrease",
    "MiddleOrJuniorSchool": "James Tippit",
    "MLSAreaMajor": "GTE",
    "MlsStatus": "Active",
    "NewConstructionYN": false,
    "ACT_NumDining": "1",
    "ACT_NumLiving": "1",
    "ACT_OpenHouseCount": "2",
    "ACT_OpenHousePublicCount": "0",
    "OriginalEntryTimestamp": "2020-10-10T16:11:01.000Z",
    "OriginalListPrice": 490000,
    "OriginatingSystemName": "actris",
    "OtherStructures": [
        "See Remarks"
    ],
    "ParcelNumber": "20956500000001",
    "ParkingFeatures": [
        "Carport"
    ],
    "ParkingTotal": 4,
    "PatioAndPorchFeatures": [
        "Front Porch"
    ],
    "PoolFeatures": [
        "None"
    ],
    "PoolPrivateYN": false,
    "PreviousListPrice": 479800,
    "PropertyCondition": [
        "Resale",
        "Updated/Remodeled"
    ],
    "PropertySubType": "Single Family Residence",
    "PropertyType": "Residential"
}
```

--------------------------------

### Query Documentation with AI Agent

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this GET request to ask questions about the documentation. Include your specific question in the `ask` parameter and an optional broader goal in the `goal` parameter to get tailored answers and relevant excerpts.

```http
GET https://docs.mlsgrid.com/api-documentation/api-version-2.0.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### Replication Query Example

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

After the initial import, use replication queries without the 'MlgCanView' filter to capture all changes, including deletions. This example filters for records modified after a specific timestamp.

```http
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20ModificationTimestamp%20gt%202019-02-04T23:59:59.99Z&$expand=Media,Rooms,UnitTypes
```

--------------------------------

### Example Property Expand Request

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Demonstrates how to request expanded Rooms, UnitTypes, and Media for a Property resource, filtered by OriginatingSystemName.

```http
https://api-demo.mlsgrid.com/v2/Property?$expand=Rooms,UnitTypes,Media&$filter=OriginatingSystemName eq 'actris'
```

--------------------------------

### Example MlgCanUse Field Metadata

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the metadata for the MlgCanUse field, indicating its type and purpose. It specifies that the field is a collection of strings representing allowed use case groups.

```xml
<Property Name="MlgCanUse" Type="Collection(Edm.String)" >
     <Annotation Term="MLS.OData.Metadata.MLSGRID" String="Allowed use case groups"/>
     <Annotation String="https://docs.mlsgrid.com/api-documentation/api-version-2.0#mlgcanuse-field" Term="MLSGRID.Docs"/>
 </Property>
```

--------------------------------

### Get StandardStatus Lookups

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Retrieve a list of StandardStatus lookup values from the Lookups resource. This example filters by LookupName and OriginatingSystemName.

```http
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'StandardStatus' and OriginatingSystemName eq 'actris'
```

```json
{
    "@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
    "value": [
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679024b9e68b94c17bf8')",
            "LookupKey": "ACT61bb679024b9e68b94c17bf8",
            "LookupName": "StandardStatus",
            "LookupValue": "Canceled",
            "ModificationTimestamp": "2021-12-16T16:21:36.393Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Canceled",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c180c1')",
            "LookupKey": "ACT61bb679124b9e68b94c180c1",
            "LookupName": "StandardStatus",
            "LookupValue": "Expired",
            "ModificationTimestamp": "2021-12-16T16:21:37.056Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Expired",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c181b8')",
            "LookupKey": "ACT61bb679124b9e68b94c181b8",
            "LookupName": "StandardStatus",
            "LookupValue": "Delete",
            "ModificationTimestamp": "2021-12-16T16:21:37.135Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Delete",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c181bf')",
            "LookupKey": "ACT61bb679124b9e68b94c181bf",
            "LookupName": "StandardStatus",
            "LookupValue": "Withdrawn",
            "ModificationTimestamp": "2021-12-16T16:21:37.135Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Withdrawn",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c18331')",
            "LookupKey": "ACT61bb679124b9e68b94c18331",
            "LookupName": "StandardStatus",
            "LookupValue": "Pending",
            "ModificationTimestamp": "2021-12-16T16:21:37.286Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Pending",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c1869e')",
            "LookupKey": "ACT61bb679124b9e68b94c1869e",
            "LookupName": "StandardStatus",
            "LookupValue": "Incomplete",
            "ModificationTimestamp": "2021-12-16T16:21:37.588Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Incomplete",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c187ef')",
            "LookupKey": "ACT61bb679124b9e68b94c187ef",
            "LookupName": "StandardStatus",
            "LookupValue": "Active",
            "ModificationTimestamp": "2021-12-16T16:21:37.738Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Active",
            "MlgCanView": true
        }
    ]
}
```

--------------------------------

### Example MlgCanUse Field Output for IDX

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for IDX data subscriptions. This indicates the record can be used for the Internet Data Exchange Program.

```json
"MlgCanUse": [
    "IDX"
]
```

--------------------------------

### Get BodyType Lookups

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Retrieve a list of BodyType lookup values from the Lookups resource. This example filters by LookupName and OriginatingSystemName.

```http
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'BodyType' and OriginatingSystemName eq 'mfrmls'
```

```json
{
    "@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
    "value": [
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb678f24b9e68b94c1768e')",
            "LookupKey": "MFR61bb678f24b9e68b94c1768e",
            "LookupName": "BodyType",
            "LookupValue": "Double Wide",
            "ModificationTimestamp": "2021-12-16T16:21:35.843Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Double Wide",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb679024b9e68b94c178dd')",
            "LookupKey": "MFR61bb679024b9e68b94c178dd",
            "LookupName": "BodyType",
            "LookupValue": "Single Wide",
            "ModificationTimestamp": "2021-12-16T16:21:36.083Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Single Wide",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb679024b9e68b94c179c3')",
            "LookupKey": "MFR61bb679024b9e68b94c179c3",
            "LookupName": "BodyType",
            "LookupValue": "Triple Wide",
            "ModificationTimestamp": "2021-12-16T16:21:36.163Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Triple Wide",
            "MlgCanView": true
        }
    ]
}
```

--------------------------------

### Example MlgCanUse Field Output for VOW

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for VOW data subscriptions. This indicates the record can be used for the Virtual Office Website Program.

```json
"MlgCanUse": [
    "VOW"
]
```

--------------------------------

### Example MlgCanUse Field Output for Back Office (BO)

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for Back Office (BO) data subscriptions. This indicates the record can be used for Agent Production Analytics, Comparative Market Analysis, and other back-office functions.

```json
"MlgCanUse": [
    "BO"
]
```

--------------------------------

### Initial Import Request

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This is an example of the initial import request to fetch the first page of property data, filtering for active listings and excluding deleted records.

```APIDOC
## GET /v2/Property

### Description
Fetches the initial page of property data, filtering for active listings and excluding deleted records.

### Method
GET

### Endpoint
https://api.mlsgrid.com/v2/Property

### Query Parameters
- **$filter** (string) - Required - Filters the results. Example: "OriginatingSystemName eq 'actris' and MlgCanView eq true"

### Response
#### Success Response (200)
- **@odata.nextLink** (string) - URL to fetch the next page of data if available.
```

--------------------------------

### Property Search with Filters

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example demonstrates how to search for properties using filters for StandardStatus and OriginatingSystemName. The OriginatingSystemName is case-sensitive and typically in lowercase.

```APIDOC
## GET /v2/Property

### Description
Allows searching for properties with various filter criteria. This example shows filtering by StandardStatus and OriginatingSystemName.

### Method
GET

### Endpoint
/v2/Property

### Parameters
#### Query Parameters
- **$filter** (string) - Required - OData filter expression. Example: "StandardStatus eq 'Active Under Contract' and OriginatingSystemName eq 'actris'"

### Request Example
```
https://api-demo.mlsgrid.com/v2/Property?$filter=StandardStatus eq 'Active Under Contract' and OriginatingSystemName eq 'actris'
```

### Response
#### Success Response (200)
- **value** (array) - An array of property objects matching the filter criteria.

#### Response Example
```json
{
  "value": [
    {
      "StandardStatus": "Active Under Contract",
      "OriginatingSystemName": "actris",
      "PropertyType": "Single Family Residential",
      "ListingId": "12345"
      // ... other property fields
    }
    // ... more property objects
  ]
}
```
```

--------------------------------

### Querying by StandardStatus

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example demonstrates how to filter properties by a specific StandardStatus value. You must use the 'Standard Name' as provided in the documentation.

```APIDOC
## Querying by StandardStatus

### Description
This endpoint allows you to filter property records based on their StandardStatus. You need to use the exact 'Standard Name' for the status you are querying.

### Method
GET

### Endpoint
https://api.mlsgrid.com/v2/Property

### Parameters
#### Query Parameters
- **$filter** (string) - Required - OData filter expression. Example: "OriginatingSystemName eq 'actris' and StandardStatus eq 'Active Under Contract'"

### Request Example
```
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20StandardStatus+eq+%27Active%20Under%20Contract%27
```

### Response
#### Success Response (200)
Returns a list of property records matching the specified StandardStatus.

#### Response Example
(Response body will contain a JSON array of property objects)
```

--------------------------------

### Example MlgCanUse Field Output for IDX, VOW, and Back Office (BO)

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for IDX, VOW, and Back Office (BO) data subscriptions. Records with these values can be used for all three types of programs.

```json
"MlgCanUse": [
    "IDX",
    "VOW",
    "BO"
]
```

--------------------------------

### Query Documentation with GET Request

Source: https://docs.mlsgrid.com/api-documentation

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections. The `ask` parameter is the immediate question, and `goal` is optional and describes the broader end goal.

```http
GET https://docs.mlsgrid.com/api-documentation.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### API Access URL Example

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this URL to retrieve property data with filters and expansions. Ensure you include the 'Authorization' header with your bearer token.

```http
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20ModificationTimestamp%20gt%202020-12-30T23:59:59.99Z&$expand=Media,Rooms,UnitTypes
```

--------------------------------

### Querying by PropertyType

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows how to filter properties by a specific PropertyType. Similar to StandardStatus, use the 'Standard Name' for the property type.

```APIDOC
## Querying by PropertyType

### Description
This endpoint allows you to filter property records based on their PropertyType. You need to use the exact 'Standard Name' for the property type you are querying.

### Method
GET

### Endpoint
https://api.mlsgrid.com/v2/Property

### Parameters
#### Query Parameters
- **$filter** (string) - Required - OData filter expression. Example: "OriginatingSystemName eq 'actris' and PropertyType eq 'Commercial Sale'"

### Request Example
```
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20PropertyType+eq+%27Commercial%20Sale%27
```

### Response
#### Success Response (200)
Returns a list of property records matching the specified PropertyType.

#### Response Example
(Response body will contain a JSON array of property objects)
```

--------------------------------

### Example MlgCanUse Field Output for IDX and VOW

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for both IDX and VOW data subscriptions. Records with both values can be used for both Internet Data Exchange and Virtual Office Website programs.

```json
"MlgCanUse": [
    "IDX",
    "VOW"
]
```

--------------------------------

### Example MlgCanUse Field Output for VOW and Back Office (BO)

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for both VOW and Back Office (BO) data subscriptions. Records with these values can be used for Virtual Office Website and back-office functions.

```json
"MlgCanUse": [
    "VOW",
    "BO"
]
```

--------------------------------

### Example MlgCanUse Field Output for Broker Only / Participant Data Access (PT)

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example shows the MlgCanUse field output when a record is marked for Broker Only / Participant Data Access (PT). This indicates the record can be used solely for Participant Listings Use.

```json
"MlgCanUse": [
    "PT"
]
```

--------------------------------

### Example UnitTypes Expanded Data

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Illustrates the structure of the expanded 'UnitTypes' data within a Property resource, detailing rent, type, bath/bed counts, and key.

```json
"UnitTypes": [
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 1",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_1"
                },
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 2",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_2"
                }
            ]
```

--------------------------------

### Example Rooms Expanded Data

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Shows the structure of the expanded 'Rooms' data within a Property resource, including dimensions, type, features, and key.

```json
"Rooms": [
        {
            "RoomDimensions": "13X14",
            "RoomType": "Bedroom 1",
            "RoomFeatures": "Full Bath",
            "RoomKey": "RTC1733786Group_1"
        },
        {
            "RoomDimensions": "12X11",
            "RoomType": "Bedroom 2",
            "RoomKey": "RTC1733786Group_2"
        }        
    ],
```

--------------------------------

### Filter Property Search by StandardStatus and OriginatingSystemName

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This example demonstrates how to filter property search results using the StandardStatus and OriginatingSystemName fields. Ensure the values used in the filter are valid and match the expected case sensitivity.

```HTTP
https://api-demo.mlsgrid.com/v2/Property?$filter=StandardStatus eq 'Active Under Contract' and OriginatingSystemName eq 'actris'
```

--------------------------------

### Retrieve API Metadata

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this endpoint to access the metadata for the API. Filter by OriginatingSystemName to get specific system metadata.

```http
https://api.mlsgrid.com/v2/$metadata?$filter=OriginatingSystemName%20eq%20%27actris%27
```

--------------------------------

### Next Link Example in JSON Response

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This JSON snippet illustrates the structure of a response, highlighting the '@odata.nextLink' field used for paginating through data.

```json
{
            "MlgCanView": true,
            "ModificationTimestamp": "2019-02-01T00:55:41.516Z",
            "OriginatingSystemName": "actris"
        }
    ],
    "@odata.nextLink": "https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20MlgCanView%20eq%20true&$expand=Media%2CRooms%2CUnitTypes&$top=1000&$skip=4000"
}
```

--------------------------------

### Example Lookup Record

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This JSON object represents a single lookup record, including its unique key, name, value, modification timestamp, originating system, and viewability flag.

```json
{
    "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb678f24b9e68b94c1734e')",
    "LookupKey": "ACT61bb678f24b9e68b94c1734e",
    "LookupName": "AreaUnits",
    "LookupValue": "Square Meters",
    "ModificationTimestamp": "2021-12-16T16:21:35.529Z",
    "OriginatingSystemName": "actris",
    "StandardLookupValue": "Square Meters",
    "MlgCanView": true
}
```

--------------------------------

### Get BodyType Lookups

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Retrieves a list of 'BodyType' lookup values from the MLSGrid API v2, filtered by originating system.

```APIDOC
## GET /v2/Lookup

### Description
Retrieves lookup data based on specified filter criteria.

### Method
GET

### Endpoint
/v2/Lookup

### Parameters
#### Query Parameters
- **$filter** (string) - Required - OData filter expression. Example: "LookupName eq 'BodyType' and OriginatingSystemName eq 'mfrmls'"

### Request Example
```
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'BodyType' and OriginatingSystemName eq 'mfrmls'
```

### Response
#### Success Response (200)
- **@odata.context** (string) - Metadata context URL.
- **value** (array) - An array of lookup objects.
  - **@odata.id** (string) - The resource identifier for the lookup item.
  - **LookupKey** (string) - The unique key for the lookup.
  - **LookupName** (string) - The name of the lookup category.
  - **LookupValue** (string) - The specific value of the lookup.
  - **ModificationTimestamp** (string) - The timestamp of the last modification.
  - **OriginatingSystemName** (string) - The name of the originating system.
  - **StandardLookupValue** (string) - The standardized lookup value.
  - **MlgCanView** (boolean) - Indicates if the item is viewable.

#### Response Example
```json
{
    "@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
    "value": [
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb678f24b9e68b94c1768e')",
            "LookupKey": "MFR61bb678f24b9e68b94c1768e",
            "LookupName": "BodyType",
            "LookupValue": "Double Wide",
            "ModificationTimestamp": "2021-12-16T16:21:35.843Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Double Wide",
            "MlgCanView": true
        }
    ]
}
```
```

--------------------------------

### Get StandardStatus Lookups

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Retrieves a list of 'StandardStatus' lookup values from the MLSGrid API v2, filtered by originating system.

```APIDOC
## GET /v2/Lookup

### Description
Retrieves lookup data based on specified filter criteria.

### Method
GET

### Endpoint
/v2/Lookup

### Parameters
#### Query Parameters
- **$filter** (string) - Required - OData filter expression. Example: "LookupName eq 'StandardStatus' and OriginatingSystemName eq 'actris'"

### Request Example
```
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'StandardStatus' and OriginatingSystemName eq 'actris'
```

### Response
#### Success Response (200)
- **@odata.context** (string) - Metadata context URL.
- **value** (array) - An array of lookup objects.
  - **@odata.id** (string) - The resource identifier for the lookup item.
  - **LookupKey** (string) - The unique key for the lookup.
  - **LookupName** (string) - The name of the lookup category.
  - **LookupValue** (string) - The specific value of the lookup.
  - **ModificationTimestamp** (string) - The timestamp of the last modification.
  - **OriginatingSystemName** (string) - The name of the originating system.
  - **StandardLookupValue** (string) - The standardized lookup value.
  - **MlgCanView** (boolean) - Indicates if the item is viewable.

#### Response Example
```json
{
    "@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
    "value": [
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679024b9e68b94c17bf8')",
            "LookupKey": "ACT61bb679024b9e68b94c17bf8",
            "LookupName": "StandardStatus",
            "LookupValue": "Canceled",
            "ModificationTimestamp": "2021-12-16T16:21:36.393Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Canceled",
            "MlgCanView": true
        }
    ]
}
```
```

--------------------------------

### Array of Strings Field Output

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

RESO expects fields defined as 'String List, Multi' to be returned as an array of strings. This example shows the expected output format for such fields.

```json
"Appliances": [
                "Washer Dryer Hookup",
                "Dishwasher",
                "Oven",
                "Refrigerator"
            ],
```

--------------------------------

### Example Field Metadata with Lookup Annotation

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This XML snippet shows how a property field in the metadata can be associated with a lookup name using an OData metadata annotation. This indicates that the field's possible values are defined in the Lookups resource.

```xml
<Property Name="BodyType" Type="Collection(Edm.String)">
    <Annotation Term="MLS.OData.Metadata.LookupName" String="BodyType"/>
</Property>
...
<Property Name="StandardStatus" Type="Edm.String">
    <Annotation Term="MLS.OData.Metadata.LookupName" String="StandardStatus"/>

```

--------------------------------

### Import with Modification Timestamp Filter

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

To resume an interrupted import, add the last received 'ModificationTimestamp' to the query to avoid re-downloading records. This example filters for records modified after a specific date.

```http
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20MlgCanView%20eq%20true%20and%20ModificationTimestamp%20gt%202020-12-12T00:00:00.000Z&$expand=Media,Rooms,UnitTypes
```

--------------------------------

### Initial Data Import Query

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this URL to perform the initial import of property data. It filters for properties visible to MLSGrid and originating from 'actris'.

```http
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20MlgCanView%20eq%20true
```

--------------------------------

### Initial Data Import Request for Lookups

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this query to retrieve all lookup values for an MLS during an initial data import. It filters by originating system and ensures the lookups are viewable.

```http
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and MlgCanView eq true
```

--------------------------------

### Replication Query After Initial Import

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

After the initial import, switch to replication queries that do not filter by `MlgCanView`. This ensures you capture all changes, including deletions, and use the greatest `ModificationTimestamp` received to avoid redundant data pulls.

```APIDOC
## GET /v2/Property for Replication

### Description
Fetches all changes to property data since the last update, including deletions. This query is used after the initial import is complete.

### Method
GET

### Endpoint
https://api.mlsgrid.com/v2/Property

### Query Parameters
- **$filter** (string) - Required - Filters results by `ModificationTimestamp` greater than the last received timestamp. Example: "OriginatingSystemName eq 'actris' and ModificationTimestamp gt 2019-02-04T23:59:59.99Z"
- **$expand** (string) - Optional - Specifies related resources to include. Example: "Media,Rooms,UnitTypes"

### Notes
This query is designed to replicate changes and should include the greatest `ModificationTimestamp` received to ensure data integrity and efficiency.
```

--------------------------------

### Resource Naming and Expandable Resources

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This section outlines the primary resource endpoints and the sub-resources that can be expanded within them. It covers how to structure requests to retrieve related data.

```APIDOC
## Resource Naming

The following is a list of the resource names (or entity sets) to use in the request URL.

| Resource Endpoint | Expandable Resources                       | Description                                                               |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
| Property          | Media, Rooms, UnitTypes                    | Property Resource. This resource contains all listings for sale or lease. |
| Member            | Media                                      | Member Resource                                                           |
| Office            | Media                                      | Office Resource                                                           |
| OpenHouse         | -                                          | OpenHouse Resource                                                        |
| Lookup            | -                                          | Lookup Resource                                                           |

## Expanded Resources

The expanded resources are a sub document of the resource that they belong to. For example the Media records exist as an array of records called Media on the Property Record and are given through the api as part of the Property record. If the ModificationTimestamp of the Property record changes, the contents of the Media sub document should be replaced by whatever is returned in the updated record.

The following is a list of the expandable resources and their corresponding [Resource Names] that have the ability to expand them. This is basically the same list as above but inverted:

| Expanded Resource Name | Resources that can expand this resource     | Description                                                                                                |
| ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Media                  | Property, Member, Office                    | Media expandable resource. These are the media files associated with a Property, Member, or Office record. |
| Rooms                  | Property                                    | Rooms expandable resource. These are the Room records associated with a Property record.                   |
| UnitTypes              | Property                                    | UnitTypes expandable resource. These are the UnitType records associated with a Property record.           |

## Rooms and UnitTypes

RESO expects these expanded collections to be named differently on the records they are expanded onto. These collections are referenced in the nav links in the resource metadata.

### Metadata

The field name of the data in the Property or other resource record will match the name in the nav link located in the resource it expands from. The Type of the nav link will indicate what EntityType that field name corresponds to so that you can find the definition for that expanded type in the metadata.

Example Metadata Nav Links:
```
<NavigationProperty Name="Rooms" Type="Collection(org.reso.metadata.PropertyRooms)"/>
<NavigationProperty Name="UnitTypes" Type="Collection(org.reso.metadata.PropertyUnitTypes)"/>
```

### Example Expand Request:
```
https://api-demo.mlsgrid.com/v2/Property?$expand=Rooms,UnitTypes,Media&$filter=OriginatingSystemName eq 'actris'
```

### Example Rooms Expanded Data:
```
"Rooms": [
        {
            "RoomDimensions": "13X14",
            "RoomType": "Bedroom 1",
            "RoomFeatures": "Full Bath",
            "RoomKey": "RTC1733786Group_1"
        },
        {
            "RoomDimensions": "12X11",
            "RoomType": "Bedroom 2",
            "RoomKey": "RTC1733786Group_2"
        }
    ],
```

### Example UnitTypes Expanded Data:
```
"UnitTypes": [
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 1",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_1"
                },
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 2",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_2"
                }
            ]
```
```

--------------------------------

### Lookup Resource

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This resource contains all of the lookup values for an mls. It is recommended to use the provided queries to replicate and keep your Lookup data up to date.

```APIDOC
## Lookups Resource

### Description
This resource contains all of the lookup values for an mls. We recommend using the following queries to replicate and keep your Lookup data up to date:

### Initial Data Import Request
```
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and MlgCanView eq true
```

### Regular Replication Requests
```
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and ModificationTimestamp gt [GREATEST ModificationTimestamp FROM YOUR DATABASE FOR THIS RESOURCE]
```

Replicate from this resource the same way you would replicate from any of the resources using the Greatest ModificationTimestamp from the records you've received so far when querying for the latest changes.

Please do not pull from this resource more frequently than once a day as this resource will not likely change more than once a day. Pulling this resource with the same frequency as the rest of the resources may result in interruption of service for inefficient usage practices.

If you receive an update to MlgCanView: false on any of your lookup records, you should remove it from the list of possible values for that LookupName for the OriginatingSystemName on the record.

### Example Lookup Record
The LookupKey is the primary identifier for this resource. Each record indicates that a lookup exists and is being used or not used by a particular mls depending on the value of the MlgCanView flag. The ModificationTimestamp will update whenever the Lookup record has changed.

```json
{
    "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb678f24b9e68b94c1734e')",
    "LookupKey": "ACT61bb678f24b9e68b94c1734e",
    "LookupName": "AreaUnits",
    "LookupValue": "Square Meters",
    "ModificationTimestamp": "2021-12-16T16:21:35.529Z",
    "OriginatingSystemName": "actris",
    "StandardLookupValue": "Square Meters",
    "MlgCanView": true
}
```

### Example Field Metadata with a Lookup:
Fields that have a lookup collection associated to it will appear like this in the metadata. In these 2 cases, the BodyType field uses a Lookup with the LookupName of BodyType in the Lookups collection. Possible values for this field can be found by looking in your local copy of the Lookups data for values assocated to the BodyType lookup. Same For StandardStatus.  Lookup values for StandardStatus have a LookupName of StandardStatus in the lookups collection and you can search your local copy of the lookups collection for values associated with the StandardStatus Lookup.

```xml
<Property Name="BodyType" Type="Collection(Edm.String)">
    <Annotation Term="MLS.OData.Metadata.LookupName" String="BodyType"/>
</Property>
...
<Property Name="StandardStatus" Type="Edm.String">
    <Annotation Term="MLS.OData.Metadata.LookupName" String="StandardStatus"/>
```

### Example of These 2 Lookups from the Lookups Resource:
BodyType
```

--------------------------------

### Handling Pagination with @odata.nextLink

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

The '@odata.nextLink' field in the response contains a URL to retrieve the subsequent page of data. Continue requesting pages using this URL until it is no longer present in the response.

```APIDOC
## Using @odata.nextLink for Pagination

### Description
After an initial request, the response may contain an `@odata.nextLink` field. Use this URL in subsequent GET requests to retrieve the next set of data. Repeat this process until the `@odata.nextLink` field is absent from the response, indicating all data has been fetched.

### Example Response Snippet
```json
{
    "value": [
        {
            "MlgCanView": true,
            "ModificationTimestamp": "2019-02-01T00:55:41.516Z",
            "OriginatingSystemName": "actris"
        }
    ],
    "@odata.nextLink": "https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20'actris'%20and%20MlgCanView%20eq%20true&$expand=Media%2CRooms%2CUnitTypes&$top=1000&$skip=4000"
}
```
```

--------------------------------

### Query by PropertyType Name

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this syntax to filter records by a specific PropertyType name, such as 'Commercial Sale'. Ensure the name matches the enumeration metadata.

```http
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20PropertyType+eq+%27Commercial%20Sale%27
```

--------------------------------

### Query by StandardStatus Name

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

Use this syntax to filter records by a specific StandardStatus name, such as 'Active Under Contract'. Ensure the name matches the enumeration metadata.

```http
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20StandardStatus+eq+%27Active%20Under%20Contract%27
```

--------------------------------

### Regular Replication Request for Lookups

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This query is used for regular replication of lookup data. It filters by originating system and modification timestamp to fetch only updated records since the last replication.

```http
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and ModificationTimestamp gt [GREATEST ModificationTimestamp FROM YOUR DATABASE FOR THIS RESOURCE]
```

--------------------------------

### Property Data Access

Source: https://docs.mlsgrid.com/api-documentation/api-version-2.0.md

This endpoint allows retrieval of property data using OData queries. It supports filtering based on various criteria and expanding related resources like Media, Rooms, and UnitTypes. Authentication is required via a Bearer token.

```APIDOC
## GET /v2/Property

### Description
Retrieves property data with support for OData filtering and expansion. Requires an Authorization header.

### Method
GET

### Endpoint
https://api.mlsgrid.com/v2/Property

### Parameters
#### Query Parameters
- **$filter** (string) - Optional - OData query to filter the results. Example: "OriginatingSystemName eq 'actris' and ModificationTimestamp gt '2020-12-30T23:59:59.99Z'"
- **$expand** (string) - Optional - Comma-separated list of related resources to expand. Example: "Media,Rooms,UnitTypes"

### Request Example
```
https://api.mlsgrid.com/v2/Property?$filter=OriginatingSystemName%20eq%20%27actris%27%20and%20ModificationTimestamp%20gt%202020-12-30T23:59:59.99Z&$expand=Media,Rooms,UnitTypes
```

### Headers
- **Authorization** (string) - Required - Bearer access_token

### Response
#### Success Response (200)
- **Data** (object) - The retrieved property data, compressed using gzip.

#### Response Example
(Response body will be gzipped JSON containing property data)
```
Tokens:
Raw