The Messages service allows messages to be sent between agents and contacts, or agents and other agents. For API keys with an IDX role and IDX permissions, flexmls messages may be sent from a specified contact to the agent who owns the API key, or from the agent who owns the key to another agent or a specified contact. For API keys with an IDX role and Portal permissions, messages may be sent from the authenticated contact to the agent who owns the API key. For API keys with private roles, private users may send messages to other private users or to their contacts.

Messages are sent using the flexmls messaging system, which sends an e-mail and makes the message appear inside of flexmls.

  1. Applicable API Key Roles
  2. Authentication
  3. Available Services
    1. Send a message
    2. Response

Applicable API Key Roles

This service is available to API keys with IDX roles with both IDX and portal permissions. More information about roles may be found here.


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

Available Services

Send Message

URI: /<API Version>/messages

Only the POST HTTP method is implemented at this time.

HTTP Method Description
GET Retrieves carts for the user. Responses are paginated using the standard pagination syntax.
POST Creates a cart, for non-portal carts.
PUT, DELETE Returns HTTP 405 (Method Not Allowed). Not implemented.

POST Requests

A sample request body is below. One message may be sent per service call. A description of each of the attributes is below this sample request body.

    "D": {
        "Messages": [
                "Type": "ShowingRequest",
                "EventDateTime": "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"
Attribute Description
Type One of the following values: General, ShowingRequest . A general message optionally may include a listing ID if the message pertains to a specific listing. A showing request message requires a listing ID as well as a suggested date and time.

Further description of each message types is as follows:

  • General: just a general message. May specify an optional listing ID that the message pertains to.
  • ShowingRequest: a request to see a specific listing on a specific date and time
EventDateTime The requested showing date, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS). Required only if Type=ShowingRequest.
ListingId The ID of the listing for which a showing is requested. Required only if Type=ShowingRequest. Optional on the General message type; if included, links the message to a specific listing.
SenderId This is only needed with IDX roles where the contact has not logged into the portal. The string to send is the ID of the contact who will be noted as the sender. Typically, the contact ID will be obtained from the response to a POST request on the Contacts service. The contact’s ID must match that of a contact that the API key owner has in their contacts list or the message send will fail. If omitted from an IDX role where a user hasn’t logged into the portal, the sender is assumed to be the agent.

For IDX keys with private or portal permissions, the sender is automatically set to be the person who has authenticated via OAuth.

Recipients Required for private messages but is optional for IDX or portal messages since the recipient is then assumed to be the contact’s agent. It is an array of IDs indicating the recipients. Recipients may be either a member or a contact. Example request:

Subject The subject of the message, 500 characters max
Body Message body. This is a text field.


POST Response

The standard success/fail response format is returned.

Comments on this entry are closed.