Skip to content

NorthstarMLS RESO Web API Documentation

Authentication

Reso Web API uses Auth0 machine-to-machine (M2M) tokens for authentication. To obtain a token, follow these steps:

  1. Obtain a client ID and client secret (Provided by NorthstarMLS).
  2. Use these credentials to make a POST request to https://reso-auth.northstarmls.com/oauth/token. Provide the client ID as the username and the client secret as the password in a basic authentication header. For example:

1 POST https://reso-auth.northstarmls.com/connect/token HTTP/1.1
2 Authorization: Basic 
3 Content-Type: application/x-www-form-urlencoded
4 {
5   "scope": "read:reso-resources read:reso-metadata",
6   "grant_type": "client_credentials"
7 }

The scope field is the identifier of the permissions needed, and grant_type should always be set to client_credentials.

  1. If the credentials are valid, the response will contain an access token, which should be included in subsequent requests to protected endpoints. The response will also include the token type, scope, and expiration time in seconds. Here’s an example response:

1 HTTP/1.1 200 OK
2 Content-Type: application/x-www-form-urlencoded
3 {
4   "access_token": "access_token>",
5   "scope": "read:reso-resources read:reso-metadata",
6   "expires_in": 86400,
7   "token_type": "Bearer"
8 }
  1. Include the access token in subsequent requests by adding it to the Authorization header in the format Authorization: Bearer <access_token>.

Note that the token is valid for a limited time only. Once it expires, you will need to obtain a new token using the same process.

Base URL

This base URL is the first part of the rest of the requests

1 https://reso.northstarmls.com/reso-web-api

Metadata

To retrieve the metadata of the API, you can make a GET request to the following URL.

Metadata URL

1 /$metadata?$format=application/xml

The metadata will return all entities, their properties, and relationships that your user has access to in xml format. Using that data, queries can be formed following the odata spec to query for any data. View the odata spec here: https://www.odata.org/getting-started/basic-tutorial/

In addition, a few examples are proved below.

Example Requests

To retrieve specific property details, you can make a GET request with the desired property ID and select specific fields.

Example GET Request for Property

1 /Property('7145271')?$select=ListingID,Township,City

This request will fetch the property with ListingID 7143896 and return only the fields ListingID, Township, and City.

Example Response

1 {
2   "@odata.context": "$metadata#Property(ListingID,Township,ListingKey,City)/$entity",
3   "@odata.id": "Property('7145271')",
4   "ListingID": "6341178",
5   "Township": "Edina",
6   "ListingKey": "7145271",
7   "City": "Edina"
8 }

Example GET Request for Media

To retrieve media details, you can make a GET request with the media ID.

Example GET Request

1 /Media('100016401')?$select=LongDescription,MediaURL

This request will fetch the media with ID 100016401 and return only the fields LongDescription and MediaURL.

Example Response

1 {
2   "@odata.context": "$metadata#Media(MediaKey,MediaURL,LongDescription)/$entity",
3   "@odata.id": "Media('100016401')",
4   "MediaKey": "100016401",
5   "MediaURL": "https://mediadev.northstarmls.com/mediadisplay/v2/6212685-166992997132747.jpg",
6   "LongDescription": "test-image.jpg"
7 }

Example GET Request for Member

To retrieve member details, you can make a GET request with the member ID.

Example GET Request

1 /Media('100016401')?$select=LongDescription,MediaURL

This request will fetch the member with ID 123 and return only the fields MemberMlsId, MemberFirstName, and MemberLastName.

Example Response

1 {
2   "@odata.context": "$metadata#Member(MemberFirstName,MemberKey,MemberMlsId,MemberLastName)/$entity",
3   "@odata.id": "Member('123')",
4   "MemberFirstName": "John",
5   "MemberKey": "123",
6   "MemberMlsId": "012300987",
7   "MemberLastName": "Doe"
8 }

Filtering and Pagination 

You can apply filters and pagination to your requests using $filter and $top respectively.

Example GET Request with Filter and Top

1 /Property?$filter=ListingID gt '8000000'&$top=5

This request will fetch up to 5 properties with the ListingID greater than 8000000.

Example Response


1 {
2   "@odata.context": "$metadata#Property/$entity",
3   "value": [
4     {
5       "ListingID": "8000123",
6       "Township": "Sample Township",
7       "City": "Sample City",
8       // Additional Fields
9     },
10    {
11      "ListingID": "8000124",
12      "Township": "Another Township",
13      "City": "Another City"
14      // Additional Fields
15    },
16    // Additional Properties
17  ]
18 }

Example GET Request with ModificationTimestamp

1 /Property?$top=2&$filter=ModificationTimestamp gt 2024-04-01T12:00:00.000Z

This request will fetch up to 2 properties modified after 12:00 on 2024-04-01.

Example Response

1 {
2   "@odata.context": "$metadata#Property/$entity",
3   "value": [
4     {
5       "ListingID": "8000123",
6       "Township": "Sample Township",
7       "City": "Sample City",
8       // Additional Fields
9     },
10    {
11      "ListingID": "8000124",
12      "Township": "Another Township",
13      "City": "Another City"
14      // Additional Fields
15    },
16      // Additional Properties
17  ]
18 }

Expand Example

You can expand related entities using the $expand query option.

Example GET Request with Expand

1 /Property('7145271')?$select=ListingID&$expand=OpenHouse

This request will fetch the property with ListingID 7147499 and expand the related OpenHouse entity.

Example Response

1 {
2     "@odata.context": "$metadata#Property(ListingID,ListingKey,OpenHouse())/$entity",
3     "@odata.id": "Property('7145271')",
4     "ListingID": "6341178",
5     "ListingKey": "7145271",
6     "OpenHouse": [
7         {
8             "OriginalEntryUserName": "armls",
9             "Series_Nbr": null,
10            "SeriesEnd_DT": "2024-02-09",
11            "OpenHouseEndTime": "2024-02-09T12:00:00Z",
12            "OpenHouseKey": "10010850",
13            "OpenHouseRemarks": null,
14            "ListingKey": 7145271,
15            "LivestreamOpenHouseURL": "",
16            "ShowingAgentKey": 143884,
17            "Delete_DTTM": null,
18            "SeriesStart_DT": "2024-02-09",
19            "OpenHouseStartTime": "2024-02-09T11:00:00Z",
20            "Refreshments": "None",
21            "SeriesDayOccurrence": null,
22            "ModificationTimestamp": "2024-02-09T16:34:33.43Z",
23            "VirtualURLNotes": "",
24            "OriginalEntryTimestamp": "2024-02-09T16:34:33.43Z",
25            "ModificationUserName": "armls",
26            "OpenHouseType": "Public"
27        },
28        {
29            "OriginalEntryUserName": "armls",
30            "Series_Nbr": null,
31            "SeriesEnd_DT": "2024-02-09",
32            "OpenHouseEndTime": "2024-02-09T12:00:00Z",
33            "OpenHouseKey": "10010851",
34            "OpenHouseRemarks": null,
35            "ListingKey": 7145271,
36            "LivestreamOpenHouseURL": "",
37            "ShowingAgentKey": 143884,
38            "Delete_DTTM": null,
39            "SeriesStart_DT": "2024-02-09",
40            "OpenHouseStartTime": "2024-02-09T11:00:00Z",
41            "Refreshments": "None",
42            "SeriesDayOccurrence": null,
43            "ModificationTimestamp": "2024-02-09T16:34:40.727Z",
44            "VirtualURLNotes": "",
45            "OriginalEntryTimestamp": "2024-02-09T16:34:40.727Z",
46            "ModificationUserName": "armls",
47            "OpenHouseType": "Public"
48        }
49    ]
50 }

Authentication Reminder

Remember to include the access token obtained from the authentication step in the Authorization header of your requests:

1 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...