Listings: Listing Documents

The Listing Documents service allows management and retrieval for listing documents.

Document Uploads
See the Document Uploads documentation to see how to upload, and attach, a new document to a listing.
  1. Supported Roles
  2. Available Services
    1. Listing Documents
    2. Individual Listing Document
  3. Response Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads Writes Notes
IDX Yes No
Public Yes No
VOW Yes No
Portal Yes No
Private Yes Yes
More information about roles may be found here.

Available Services

Listing Documents

/<API Version>/listings/<Listing.Id>/documents
/<API Version>/listings/incomplete/<IncompleteListing.Id>/documents

HTTP Method Description Notes
GET Returns a list of all documents for the current user
PUT Allows the reordering of documents for a given listing
POST,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:
  • None

GET Response

Example:
{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/v1/listings/20100815153524571646000000/documents/20101125153422574618000000",
                "Id": "20101125153422574618000000",
                "Name": "Document name",
                "Uri": "http://documents.sparkplatform.com/abc.pdf",
                "Privacy": "Public"
            }
        ]
    }
}

PUT Request

Request body:
{
    "D": {
        "Documents": [
            {"Id": "20111213041526458274000000"},
            {"Id": "20121214041526458275000000"},
            {"Id": "20130415041526458276000000"},
            {"Id": "20130516041526458277000000"}
        ]
    }
}
For the global PUT to the listing, currently only the Id attribute is accepted and is currently intended to be used for reordering documents for a listing.

PUT Response

The standard success/fail response is returned.

Individual Listing Document

/<API Version>/listings/<Listing.Id>/documents/<Document.Id>
/<API Version>/listings/incomplete/<IncompleteListing.Id>/documents/<Document.Id>

HTTP Method Description Notes
GET Returns a list of all documents for the current user
POST Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Updates an existing document
DELETE Deletes a document

GET Request

Parameters:
  • None

GET Response

See the GET response section above for the data format.

PUT Request

The PUT request supports the following operations for manipulating a document each of these operations must be performed independently in separate requests.
Order:
You can reorder a single document in the overall document set by passing the Order attribute. The value must be greater than 0, and any number higher than the size of the document set will bump the document to the last position. Below is a sample PUT request to move a document to the beginning:
{
    "D": {
        "Documents": [
            {"Order": 1}
        ]
    }
}
Update:
{
    "D": {
      "Name": "My Document"
    }
}

PUT Response

The standard success/fail response is returned.

DELETE Request

Parameters:
  • None

DELETE Response

The standard success/fail response is returned.

Response Description

Attribute Data Type Writeable Required Description
Name Character Yes Yes The name of the document.
Uri Character No No The URI to the document file.

Listing: Documents Description

Attribute Data Type Writeable Required Description
Id Character No No The unique ID for the document.
ResourceUri Character No No The URI to the document.
Name Character Yes Yes The name of the document. The MLS may define a set of names that must always have a Privacy value of Private. See the Documents: Metadata service for more information.
Privacy Character Yes See Description This field is conditionally writable and conditionally required. See the Documents: Metadata service for more information.

Possible values are:
  • Public: The document can be publicly viewed.
  • DataShare: The document cannot be viewed publicly, but can be viewed by agents in other MLSs.
  • Private: The document can only be viewed by agents of the MLS the listing was listed under.
  • HasEdit: The document can only be viewed by users that can edit the listing.
Uri Character No No The path to the document file.

Expansions

None.

API Explorer

The API Explorer does not currently support this service.