Privileged API Keys Only
Special permission is required to access this service. Please contact api-support@sparkplatform.com or your API key provider to request access to this data.
Messages
The Messages service allows messages exchanged between consumers and agents.
Supported Roles
| Role | Reads | Writes | Notes |
|---|---|---|---|
| IDX | No | Yes | |
| Public | No | No | |
| VOW | Yes | Yes | |
| Portal | Yes | Yes | |
| Private | Yes | Yes |
More information about roles may be found here.
Available Services
Messages
/<API Version>/messages
/<API Version>/contacts/<Contact.Id>/messages
Messages are ordered by time sent, with the most recent messages first.
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns messages sent or received by the current user | No | |
| POST | Creates a new message | No | Cannot be accessed as a subservice of /v1/contacts |
| PUT | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
GET Request
Parameters:
| Parameter | Required | Notes |
|---|---|---|
| Standard search and paging syntax | No | With an _orderby of LastMessageInThreadTimestamp, messages will be ordered by the most recent timestamp of any reply in the thread. |
| Standard expansion parameters | No |
GET Response
{
"D": {
"Success": true,
"Results": [{
"Id": "20110353423434130982000000",
"ResourceUri": "/v1/messages/20110353423434130982000000",
"Type": "ShowingRequest",
"SenderId": "20110112234857732941000000",
"Sender": {
"Id": "20110112234857732941000000",
"ResourceUri": "/v1/accounts/20110112234857732941000000",
"UserType": "Member",
"Name": "Joe Realtor",
"OfficeId": "20100113238853732842000000",
"Office": "Joe's Realty",
"CompanyId": null,
"Company": null
"FbsIdxCustomer": false,
"MlsId": "20100127075503180752000000"
"PrimaryEmail": {
"Id": "20120424173947957808000000",
"Name": "Office E-Mail",
"Primary": true,
"Type": "Office",
"Address": "myoffice@example.com"
},
"PrimaryPhone": {
"Id": "20120424173948048729000000",
"Name": "Office Phone",
"Primary": true,
"Type": "Office",
"Number": "555-555-555",
"InternationalCode": nil,
"AreaCode": "555",
"Prefix": "555",
"LineNumber": "5555",
"Extension": nil
},
"PrimaryWebsite": {
"Id": "20120424173948178569000000",
"Name": "Office Web Site",
"Primary": true,
"Uri": "http://example.org",
"Type": "Office"
}
},
"RecipientIds": ["20120212334957232744000000"],
"Recipients": [{
"Id": "20120212334957232744000000",
"ResourceUri": "/v1/accounts/20120212334957232744000000",
"UserType": "Member",
"Name": "Sue Realtor",
"OfficeId": "20100113238853732842000000",
"Office": "Joe's Realty",
"CompanyId": null,
"Company": null
"FbsIdxCustomer": false,
"MlsId": "20100127075503180752000000"
"PrimaryEmail": {
"Id": "20120424173947957808000000",
"Name": "Office E-Mail",
"Primary": true,
"Type": "Office",
"Address": "myoffice@example.com"
},
"PrimaryPhone": {
"Id": "20120424173948048729000000",
"Name": "Office Phone",
"Primary": true,
"Type": "Office",
"Number": "555-555-555",
"InternationalCode": nil,
"AreaCode": "555",
"Prefix": "555",
"LineNumber": "5555",
"Extension": nil
},
"PrimaryWebsite": {
"Id": "20120424173948178569000000",
"Name": "Office Web Site",
"Primary": true,
"Uri": "http://example.org",
"Type": "Office"
}
}],
"ThreadInfo": {
"HasReplies": true,
"UnreadInThread": true,
"LastMessageTimestamp": "2013-06-11T11:00:00"
},
"Subject": "Showing Request For 123 Main St, MLS # 12-345",
"Body": "A showing is requested for ...",
"ListingId": "20110112234857732941000000",
"ReplyToId": null,
"RecipientIds": "20130212233857332441000000",
"CreatedTimestamp": "2013-06-11T11:00:00",
"ModificationTimestamp": "2013-06-11T11:00:00"
}]
}
}
POST Request
Request body:
{
"D": {
"Messages": [
{
"Type": "ShowingRequest",
"EventTimestamp": "2011-09-15T14:00:00",
"SenderId": "20110112234857732941000000",
"Subject": "Showing Request For 123 Main St, MLS # 12-345",
"Body": "A showing is requested for ...",
"ListingId": "20110112234857732941000000"
}
]
}
}
POST Response
The standard success/fail response is returned.
Unread Message Count
/<API Version>/messages/unread
/<API Version>/contacts/<Contact.Id>/messages/unread
Returns the unread message count in the Pagination attribute
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns unread message count | No | |
| POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| PUT | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
GET Request
Parameters:
- None
GET Response
{
"D": {
"Success": true,
"Results": [],
"Pagination": {
"TotalRows": 78,
"PageSize": 1,
"TotalPages": 1,
"CurrentPage": 1
}
}
}
Marking All Messages as Read
/<API Version>/messages/before/<Datetime>
Marks all messages as Read if sent prior to a given date.
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| PUT | Flags as read | No | |
| DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
PUT Request
Request body:
{
"D":{
"Read": true
}
}
PUT Response
The standard success/fail response is returned.
Individual Message
/<API Version>/messages/<Message.Id>
/<API Version>/contacts/<Contact.Id>/messages/<Message.Id>
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns an individual message sent or received by the current user | No | |
| POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| PUT | Marks a message as Read | No | Cannot be accessed as a subservice of /v1/contacts |
| DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
GET Request
Parameters:
| Parameter | Required | Notes |
|---|---|---|
| Standard expansion parameters | No |
GET Response
See the GET request section for for the Messages service.
PUT Request
Request body:
{
"D": {
"Read": true
}
}
PUT Response
The standard success/fail response is returned.
Message Replies
/<API Version>/messages/<Message.Id>/replies
/<API Version>/contacts/<Contact.Id>/messages/<Message.Id>/replies
Messages returned by this service are replies to the message identified by Message.Id in the URI. You can only create message replies for top level messages, as only a single level of message threads is supported.
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns direct responses to the message specified by Message.Id |
No | |
| POST | Creates a reply. ReplyTo is detected from Message.Id, and need not be supplied with the POST request. |
No | Cannot be accessed as a subservice of /v1/contacts |
| PUT | Marks all replies as Read. |
No | Cannot be accessed as a subservice of /v1/contacts |
| DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
GET Request
Parameters:
| Parameter | Required | Notes |
|---|---|---|
| Standard search and paging syntax | No | With an _orderby of LastMessageInThreadTimestamp, messages will be ordered by the most recent timestamp of any reply in the thread. |
| Standard expansion parameters | No |
GET Response
See the GET request section for for the Messages service.
POST Request
Request body:
See the POST request section for for the Message service.
POST Response
The standard success/fail response is returned.
PUT Request
Request body:
{
"D": {
"Read": true
}
}
PUT Response
The standard success/fail response is returned.
Individual Message Reply
/<API Version>/messages/<Message.Id>/replies/<Message.Id>
/<API Version>/contacts/<Contact.Id>/messages/<Message.Id>/replies/<Message.Id>
| HTTP Method | Description | Conditional | Notes |
|---|---|---|---|
| GET | Returns an individual reply to the message specified by Message.Id |
No | |
| POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| PUT | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
| DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
GET Request
Parameters:
| Parameter | Required | Notes |
|---|---|---|
| Standard expansion parameters | No |
GET Response
See the GET request section for for the Messages service.
Messages Description
| Attribute | Data Type | Writeable | Required | Searchable | Description |
|---|---|---|---|---|---|
ResourceUri |
Character | No | No | No | The resource URI to the message. |
Id |
Character | No | No | No | The Id for the message. |
Type |
Character | Yes | Yes | No | See the list of available message types below. |
Body |
Character | Yes | No | No | The body of the message. |
CreatedTimestamp |
Timestamp | No | No | Yes | The timestamp when the message was originally sent. |
EventDate |
Date | No | When Type=showingFdbk or Type=ShowingRequest |
No | The requested showing/feedback date. |
EventTimestamp |
Timestamp | Yes | When Type=ShowingRequest |
No | The requested showing date. The provided timestamp is assumed to be the date and time in the MLSs timezone. |
ListingId |
Character | Yes | No | Yes | The Id of the listing related to the message, when applicable. |
Read |
Boolean | Yes | No | No | If false, the message has not been flagged as "read" by the current user.
|
ReadTimestamp |
Timestamp | Yes | No | No | The time when the message was read by the current user. If null,
the message has not been read. Note: If the message is not explicitly read, but instead flagged as read by the service that bulk reads messages, this timestamp will be set to the most recent DateTime
values supplied to that service.
|
RecipientIds |
CharacterList | Yes | No | No | An array of Account or Contact IDs for the recipients of the message. Only populated if the current user is the message sender. |
ReplyToId |
Character | No | No | Yes | The message Id the current message is a response to. If null, the current message is not a reply to another message. Use the Message Replies service to create replies. |
SenderId |
Character | Yes | No | Yes | Used when the sender will not be the current user. Supported only for IDX roles when a contact not logged in to their VOW/Portal account wishes to contact their agent. |
Subject |
Character | Yes | No | No | The subject of the message. 500 characters max. |
Recipients |
Expansion | More detail about users whose Ids are specified in the RecipientIds array. |
|||
Id |
Character | No | No | No | The Id for the user or contact record. |
ResourceUri |
Character | No | No | No | The URI to the user or contact record. |
UserType |
Character | No | No | No | The type of account. Possible values are Contact, Member, Office and Mls.
|
Name |
Character | No | No | No | The recipient's full name. |
OfficeId |
Character | No | No | No | The Id of the office the member belongs to, when applicable. |
Office |
Character | No | No | No | The full name of the office the member belongs to, when applicable. |
CompanyId |
Character | No | No | No | The Id of the company the member belongs to, when applicable. |
Company |
Character | No | No | No | The full name of the office the member belongs to, when applicable. |
Sender |
Expansion | This has the same attributes as the Recipients expansion above. |
|||
ThreadInfo |
Expansion | ||||
HasReplies |
Boolean | No | No | No | true if there are replies to this message that can be viewed. |
LastMessageTimestamp |
DateTime | No | No | No | The timestamp of the most recent message in the thread. |
UnreadInThread |
Boolean | No | No | No | true if any messages in the thread are unread.Note: _orderby=UnreadInThread is supported when retrieving all messages for a user, and will bubble messages with an unread reply for the current user to the top. |
Message Types
| Type | Creation Supported? | Description |
|---|---|---|
ContactMe |
No | A request by a consumer to be contacted by an agent. |
General |
Yes | A basic message between an agent and a client. |
Note |
No | A private note. |
OpenHouseFeedback |
No | Feedback about an open house. |
RemapRecommendation |
No | A recommendation to remap a listing. |
Reply |
Yes | Any message that is a response (e.g. has a ReplyToId value) to another message. |
ShowingConfirmation |
No | Either a confirmation or rejection response to a ShowingRequest. |
ShowingFeedback |
No | Feedback after a showing. |
ShowingRequest |
No | A request for a showing appointment. |
ShowingFeedbackRequest |
No | A request for feedback after a showing appointment. |
Expansions
| Expansion | Roles | Single Record Only? | Selection Support? | Description |
|---|---|---|---|---|
Body |
All | No | No | The full body of the message. |
BodyText |
All | No | No | The full body of the message excluding all html. |
ThreadInfo |
All | No | No | Additional details about the thread of replies to the message. |
ThreadPreview |
All | No | No | Returns the first unread message or if none, the last message, in the thread.This message will include its Body. |
Recipients |
All | No | No | A list of basic recipient data, including name, user type, and office information. |
Sender |
All | No | No | A list of basic sender data, including name, user type, and office information. |
API Explorer
The API Explorer does not currently support this service.