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.
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:
|
Uri |
Character | No | No | The path to the document file. |
Expansions
None.