Contacts

Supported Roles
Available Services
Contact Description
Expansions

Supported Roles

Role	Reads	Writes
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:

Parameter	Required
Standard search and paging syntax	Yes
Standard selection parameters	No
Standard expansion parameters	No

{
    "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:

Parameter	Required
Standard selection parameters	No
Standard expansion parameters	No

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:

None

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:

AdditionalNotificationEmails
FamilyName
GivenName
HomeLocality
HomePhoneNumber
HomePostalCode
HomeRegion
HomeStreetAddress
MiddleName
MobilePhoneCountryCode
MobilePhoneNumber
OtherPhoneNumber
PagerPhoneNumber
PrimaryEmail
PrimaryPhoneNumber
SecondaryEmails
WorkPhoneNumber

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.