Listing Notes

The Listing Notes service allows notes on a specific listing to be retrieved.

  1. Applicable API Key Roles
  2. Authentication
  3. Available Services
    1. Private listing notes
    2. Shared listing notes
  4. Listing Notes Request Format
  5. Private Listing Notes Response Format
  6. Shared Listing Notes Response Format

Applicable API Key Roles

This service is available to API keys with private roles and IDX roles with portal permissions. IDX roles with IDX permissions may not access this service. Listing data is restricted based on the API key and user’s current permission level. More information about roles may be found here.

Authentication

Requests must be authenticated according to these instructions or HTTP 401 (Unauthorized) will be returned.

Available Services

Private Listing Notes

URI: /<API Version>/listings/XX/my/notes

XX is a listing ID, such as 20100912153422758914000000 .

This service allows private listing notes to be retrieved, set, or deleted on a listing. Only one private note is stored per listing, so updating a note will replace the existing note.

HTTP Method Description
GET Get private notes for a specified listing.
POST Returns HTTP 405 (Method Not Allowed). This method is not implemented.
PUT Replaces the private notes on a listing.
DELETE Removes the private notes on a listing.

GET Request and Response

To retrieve the notes on a listing, issue a GET request on the URI noted above. It returns the private listing notes response format. There are no parameters.

PUT Request and Response

To add or replace private notes on a listing, issue a PUT to this service with Content-Type: application/json . The PUT body must be set to the listing notes request format.

This returns the standard success/fail response format with resource creation. There are no parameters.

DELETE Request and Response

To delete private notes on a listing, issue a PUT to this service with Content-Type: application/json . The PUT body must be set to the listing notes request format.

This returns the standard success/fail response format. There are no parameters.

Shared Listing Notes

URI: /<API Version>/listings/XX/shared/notes

This URI is used for making requests on behalf of a consumer logged into an agent portal. There is no contact or agent ID necessary because both are derived from the current session.

URI: /<API Version>/listings/XX/shared/notes/contacts/CC

This URI is used for making requests on behalf of an agent, who could be working with any contact, so the contact ID must be supplied. Contact IDs may be retrieved from the Contacts service.

For both URIs:
XX is a listing ID, such as 20100912153422758914000000 .

CC is a contact ID, such as 20110301125434789184000000 .

This service allows shared listing notes to be retrieved, set, or deleted on a listing. Only one shared note is stored per listing per contact/agent relationship, so updating a note will replace the existing note. In other words, an agent can have one shared note with contact ABC regarding listing XYZ, and can have another shared note with contact DEF regarding listing XYZ, but cannot have two separate notes with contact ABC about listing XYZ.

HTTP Method Description
GET Get agent/contact shared notes for a specified listing.
POST Returns HTTP 405 (Method Not Allowed). This method is not implemented.
PUT Replaces the agent/contact shared notes on a listing.
DELETE Removes the agent/contact shared notes on a listing.

GET Request and Response

To retrieve the notes on a listing, issue a GET request on one of the URIs noted above, depending on the current API key. It returns the shared listing notes response format. There are no parameters.

PUT Request and Response

To add or replace shared notes on a listing, issue a PUT to this service with Content-Type: application/json . The PUT body must be set to the listing notes request format.

This returns the standard success/fail response format with resource creation. There are no parameters.

DELETE Request and Response

To delete shared notes on a listing, issue a DELETE to one of the service URIs noted in the Available Services section above.

This returns the standard success/fail response format. There are no parameters.

Listing Notes Request Format

Used for adding and updating notes on a listing.

{
    "D": {
        "Note": "Great home, wondering if seller is willing to include hot tub and washer/dryer."
    }
}

Private Listing Notes Response Format

The following response format is returned by the Private Listing Notes service.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/v1/listings/20100815153524571646000000/my/notes/",
                "Note": "Great home, wondering if seller is willing to include hot tub."
            }
        ]
    }
}

Shared Listing Notes Response Format

The following response format is returned by the Shared Listing Notes service.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/v1/listings/20100815153524571646000000/shared/notes/contacts/20100912536192756362000000/",
                "Note": "Great home, wondering if seller is willing to include hot tub."
            }
        ]
    }
}

Comments on this entry are closed.