Contacts
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:
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:
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. |