Developer Documentation
Platform Overview
Authentication
API Services
Overview Accounts Accounts: Associations Accounts: Metadata Accounts: Profile Appstore: Users Broker Distributions Broker Tours Consumers Consumers: Linked Agents Contacts Contacts: Activity Contacts: Export Contacts: Tags Contacts: Portal Accounts Developers: Identities Developers: Keys Developers: Authorizations Developers: Billing Summary Developers: Change History Developers: Domains Developers: News Feed Webhooks Developers: Roles Developers: Syndications Developers: Templates Developers: Usage Detail Developers: Usage Summary Devices Flexmls: Email Links Flexmls: Listing Meta Origins Flexmls: Listing Meta Translations Flexmls: Listing Meta Field List Translations Flexmls: Listing Reports Flexmls: Mapping Layers Flexmls: Mapping Shapegen IDX IDX Links Listing Carts Listing Carts: Portal/VOW Carts Incomplete Listings Incomplete Listings: Documents Incomplete Listings: Documents Metadata Incomplete Listings: Document Uploads Incomplete Listings: Floor Plans Incomplete Listings: FloPlans Incomplete Listings: Photos Incomplete Listings: Photos Metadata Incomplete Listings: Photo Uploads Incomplete Listings: Rooms Incomplete Listings: Tickets Incomplete Listings: Units Incomplete Listings: Videos Incomplete Listings: Videos Metadata Incomplete Listings: Virtual Tours Incomplete Listings: Virtual Tours Metadata Listings Listings: Clusters Listings: Documents Listings: Documents Metadata Listings: Floor Plans Listings: FloPlans Listings: Historical Listings: History Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Rooms Listings: Rules Listings: Tour of Homes Listings: Tickets Listings: Units Listings: Validation Listings: Videos Listings: Videos Metadata Listings: Virtual Tours Listings: Virtual Tours Metadata Listing Meta: Custom Fields Listing Meta: Custom Field Groups Listing Meta: Field Order Listing Meta: Field Relations Listing Meta: Property Types Listing Meta: Rooms Listing Meta: Standard Fields Listing Meta: Units Registered Listings Market Statistics News Feed News Feed: Curation News Feed: Events News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Open Houses Overlays Overlays: Geometries Portals Preferences Saved Searches Saved Searches: Provided Saved Searches: Restrictions Saved Searches: Tags Search Templates: Quick Searches Search Templates: Views Search Templates: Sorts Shared Links System Info System Info: Languages System Info: Search Templates
Supporting Documentation
Examples
RESO Web API
RETS
FloPlan
Terms of Use

Contacts

  1. Supported Roles
  2. Available Services
    1. Contacts
    2. Unconnected Contacts
    3. Individual Contacts
    4. Contact Transfer
    5. Current User's Account
  3. Contact Description
  4. Expansions
 

Supported Roles

Role Reads Writes Notes
IDX Yes Yes
Public Yes No
VOW Yes No
Portal Yes No
Private Yes Yes

More information about roles may be found here.

 

VOW/Portal Role Support

Please note that VOW and Portal role reads are limited solely to the /my/contact resource (GET and PUT).

 

Available Services

Additional Sub-Resources

Under a private role, you can manage a VOW/Portal user's saved searches and listing carts. See the corresponding documentation pages for additional resource information.

 

Contacts

/<API Version>/contacts

HTTP Method Description Notes
GET Returns a list of all items for the current user
POST Creates a new contact along with an auto-generated portal account.
PUT, DELETE Returns HTTP 405 (Method Not Allowed) Not Implemented

GET Request

Parameters:

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/contacts/201010122342756895000000",
                "Id": "201010122342756895000000",
                "DisplayName": "Some Person",
                "PrimaryEmail": "test@test.com",
                "Tags": [
                    "IDX Lead"
                ]
            }
        ]
    }
}
 

POST Request

Request body:

{
    "D": {
        "DisplayName": "My Contact",
        "PrimaryEmail": "mycontact@sparkplatform.com"
    }
}
 

POST Response

The standard success/fail response is returned.

 

Unconnected Contacts

/<API Version>/contacts/unconnected

Unconnected contacts are created when consumers are linked to the MLS account directly via the Linked Agents service, or when consumers create an account at the VOW OAuth2 endpoint and the unconnected parameter is provided. These contacts are not present in the normal contacts payload, but become connected to an agent by transferring them.

HTTP Method Description Conditional Notes
GET Returns all unconnected contacts for the current user. No RecordStatus: "Unconnected"
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 search and paging syntax No
 
 

GET Response

See the GET request section for for the contacts service.

 

Individual Contact

/<API Version>/contacts/<Id>

HTTP Method Description Notes
GET Retrieve contact information for a single contact
POST Returns HTTP 405 (Method Not Allowed) Not Implemented
PUT Updates the specified contact
DELETE Deletes the specified contact

GET Request

Parameters:

GET Response

See the GET response section above for the data format.

PUT Request

Request body:

{
    "D": {
        "PrimaryPhoneNumber": "555-555-5555",
        "ReferredBy": "Mr. Crowley"
    }
}
 

PUT Response

The standard success/fail response is returned.

DELETE Request

Parameters:

 

DELETE Response

The standard success/fail response is returned.

 

Contact Transfer

/<API Version>/contacts/<Contact.Id>

Contacts can be transferred from one agent to another, with restrictions based on user level. For instance, an agent may only transfer a contact within their own office or company, while an MLS admin may transfer contacts from one agent to another within the MLS. When a contact is transferred, their RecordStatus flag will be set to Connected.

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 Transfers the contact to another owner in the MLS. No No attribute other than OwnerId can be specified.
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body:

{
    "D": {
      "OwnerId": "20090815223215294334000000"
    }
}
 

PUT Response

The standard success/fail response is returned.

 
 
 

Current User's Account

/<API Version>/my/contact

HTTP Method Description Notes
GET Retrieve contact information for current contact
PUT Update the allowed attribute for the current contact
POST, DELETE Returns HTTP 405 (Method Not Allowed) Not Implemented

GET Request

Parameters:

Parameter Required
Standard expansion parameters No

GET Response

See the GET response section above for the data format.

PUT Request

The following attributes described below are permitted as part of a PUT request:

 

Example:

{
    "D": {
        "PrimaryEmail": "new-contact-email@example.org",
        "HomeStreetAddress": "1405 Main Street\nApt 112"
    }
}

PUT Response

The standard success/fail response format is returned.

 

Contacts Description

Attribute Data Type Writeable Required Searchable Description
ResourceUri Character No No No The URI to the particular contact.
Id Character No No Yes The unique id for the contact.
DisplayName Character Yes Yes Yes Maximum of 75 characters.
OwnerId Character Only when transferring contacts. No No See notes on transferring contacts.
RecordStatus Character Yes No No Either Connected or Unconnected. See the unconnected contacts service for more details. Once this attribute is set to Connected, it can no longer be changed to Unconnected.
PrimaryEmail Character Yes Yes Yes Maximum of 75 characters.
SecondaryEmails Character List Yes No No
AdditionalNotificationEmails Character List Yes No No If not empty, will contain a subset of SecondaryEmails that notifications for features such as news feeds will be sent to.
InvalidEmails Character List No No Yes Contains emails associated with this contact that emails will not be sent to because the address is invalid.
GivenName Character Yes No Yes Maximum of 300 characters.
MiddleName Character Yes No Yes Maximum of 300 characters.
FamilyName Character Yes No Yes Maximum of 300 characters.
SpouseGivenName Character Yes No Yes Maximum of 300 characters.
SpouseMiddleName Character Yes No Yes Maximum of 300 characters.
SpouseFamilyName Character Yes No Yes Maximum of 300 characters.
PrimaryPhoneNumber Character Yes No Yes Maximum of 300 characters.
HomePhoneNumber Character Yes No Yes Maximum of 300 characters.
WorkPhoneNumber Character Yes No Yes Maximum of 300 characters.
FaxPhoneNumber Character Yes No Yes Maximum of 300 characters.
MobilePhoneCountryCode Character Yes No Yes Maximum of 2 characters.
MobilePhoneNumber Character Yes No Yes Maximum of 300 characters.
PagerPhoneNumber Character Yes No Yes Maximum of 300 characters.
OtherPhoneNumber Character Yes No Yes Maximum of 300 characters.
HomeStreetAddress Character Yes No Yes Maximum of 300 characters.
HomeLocality Character Yes No Yes Maximum of 300 characters.
HomeRegion Character Yes No Yes Maximum of 300 characters.
HomePostalCode Character Yes No Yes Maximum of 300 characters.
WorkStreetAddress Character Yes No Yes Maximum of 300 characters.
WorkLocality Character Yes No Yes Maximum of 300 characters.
WorkRegion Character Yes No Yes Maximum of 300 characters.
WorkPostalCode Character Yes No Yes Maximum of 300 characters.
Organization Character Yes No Yes Maximum of 300 characters.
Position Character Yes No Yes Maximum of 300 characters.
Birthday Character Yes No Yes Maximum of 300 characters.
Anniversary Character Yes No Yes Maximum of 300 characters.
Assistant Character Yes No Yes Maximum of 300 characters.
Children Character Yes No Yes Maximum of 300 characters.
Status Character Yes No Yes Maximum of 300 characters.
Other Character Yes No Yes Maximum of 300 characters.
Pets Character Yes No Yes Maximum of 300 characters.
ReferredBy Character Yes No Yes Maximum of 300 characters.
Salutation Character Yes No Yes Maximum of 300 characters.
ModificationTimestamp Timestamp No No Yes The time the contact record was last updated.
CreatedTimestamp Timestamp No No Yes The time the contact record was created.
Tags Character List Yes No Yes An array of tags associated with the contact. Each tag can be no longer than 75 characters.
NewsFeedNotificationUI Character No No No The contact-specific setting for NotificationUI. Defaults to the NotificationUI setting for the agent.
PortalInvitationTimestamp Datetime No No No The contact-specific time indicating the last time a portal invitation was sent.
Notify Boolean No No No Defaults to false. If present on a POST request, a message will be generated for the current user notifying them that a lead has been generated.
Settings.ReverseProspecting Boolean Yes No No Defaults to false. If true, the contact will be present in reverse prospecting reports (support restricted to MLSs using flexmls Web).
Note Character Yes No No Maximum of 10,000 characters
VowActive Boolean No No Yes Included as the VowActive expansion. true if the contact has a VOW/Portal Account and has logged in within the past 30 days.
VowExists Boolean No No No Included with the VowEnabled expansion. Indicates whether or not a VOW/Portal Account exists
PortalLoginName Character No No Yes VOW/Portal login name associated with the contact. This information is available with the Portal expansion this attribute is for searching only. Does not support wildcards.
UniquePrimaryEmail Boolean No No No Included with the UniquePrimaryEmailCheck expansion. Indicates whether or not multiple contacts use the same email address or not.
NewsFeedSummary Expansion See the NewsFeedSummary expansion below.
LastListingEventTimestamp Datetime No No No The timestamp of the last listing change event across all of this contact's news feeds.
UnapprovedListingEventCount Integer No No No The total number of unapproved listing events across all the contact's news feeds.
UnreadListingEventCount Integer No No No The total number of unread and approved listing events across all the contact's news feeds.
NewsFeedNotificationSummary Expansion See this expansion below.
LastListingNotificationEventTimestamp Datetime No No No The timestamp of the latest notification sent across all of this contact's news feeds.
UnapprovedListingNotificationEventCount Integer No No No The total number of unapproved listing events across all the contact's news feeds that a notification will be sent for when approved.
UnreadListingNotificationEventCount Integer No No No The total number of unread and approved listing events that have notifications sent across all the contact's news feeds.
 

Searching by DisplayName

When a wildcard is used on the account DisplayName attribute and no whitespace is present in the search string, the string will be applied to all words in the name, case-insensitive. Thus, if a contact's DisplayName is 'Neddy Nederlander', both _filter=DisplayName Eq 'Neddy*' and _filter=DisplayName Eq 'Neder*' will retrieve the contact.

 

Expansions

Expansion Roles Single Record Only? Description
Activity Private No Data about the contact's activity, calculate by actions such as viewing sent emails and saving listings. Has the following attributes:
  • Score: The overall score for the contact. Contacts can be ordered by Score (e.g. _orderby=-Score).
  • RelativeScore: The contact's score relative to the highest contact score under the current agent in the past 7 days.
{
  "Activity": {
    "Score": 150,
    "RelativeScore": 0.25
  }
}
 
When viewing an individual contact, another attribute, DailyActivity, will also be present. This attribute is an array of Score/RelativeScore fields for the last 30 days.
NewsFeedSummary All No Provides a brief overview of the news feed subscriptions for this contact.
NewsFeedNotificationSummary All No Provides a brief overview of the news feed subscriptions for this contact.
Notes All No Notes associated with the current contact.
Portal Private, Portal, VOW No The portal account for the contact. For VOW and Portal roles, available only for the Current User's Account service.
VowActive All No true if the contact has a Portal/VOW account and has logged in within the past 30 days.
VowEnabled All No true if the contact has a Portal/VOW account that is also enabled.
UniquePrimaryEmail All No true if the contact's primary email address is unique amongst all contacts.