Accounts

The Accounts service provides access to user settings and profile information.

  1. Supported Roles
  2. Available Services
    1. All Accounts
    2. All Accounts for Reports
    3. All Accounts for Rosters
    4. Individual Account
    5. Individual Account for Reports
    6. Individual Account for Rosters
    7. Accounts for Office Members
    8. Current User's Account
  3. Accounts Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads Writes Notes
IDX Yes No
Public Yes No
VOW Yes Yes
Portal Yes Yes
Private Yes Yes Writes exclusively granted, see notes below
More information about roles may be found here.
User Administration Permissions
Private roles may be given write access when granted exclusive permissions to create and update Member/Office information. This access also enhances read access by granting expansions and data visibility not available for general users.

Available Services

All Accounts

/<API Version>/accounts

HTTP Method Description Conditional Notes
GET Returns account info for the matching user(s) No
POST Creates a new account No
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:

GET Response

See the GET request section for for the accounts service.

POST Request

Request body:
{
   "D":{
      "Name":"Sample Office Inc",
      "UserType":"Office",
      "UserLevel":"Office",
      "Emails":[
         {
            "Type":"Work",
            "Name":"My Work E-mail",
            "Address":"work@test.com",
            "ProfileDisplay":true,
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile E-mail",
            "Address":"mobile@test.com"
         }
      ],
      "Phones":[
         {
            "Type":"Work",
            "Name":"My Work Phone",
            "Number":"701-555-1212",
            "ProfileDisplay":true,
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile Phone",
            "Number":"702-555-1313",
            "ProfileDisplay":true
         }
      ],
      "Websites":[
         {
            "Type":"Work",
            "Name":"My Work Website",
            "Uri":"http://iamthebestagent.com",
            "ProfileDisplay":true,
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile Website",
            "Uri":"http://m.iamthebestagent.com"
         }
      ],
      "Addresses":[
         {
            "Type":"Work",
            "Name":"My Work Address",
            "Address":"101 Main Ave, Phoenix, AZ 12345",
            "ProfileDisplay":true,
            "Primary":true
         }
      ]
   }
}

POST Response

The standard success/fail response is returned.

All Accounts for Reports

/<API Version>/accounts/report

Similar to the All Accounts service, the report subservice provides a consistent presentation of data for all records, fit for display specifically on a listing report or a business card.

HTTP Method Description Conditional Notes
GET Returns account info for the matching user(s) 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:

GET Response

See the GET request section for for the accounts service.

All Accounts for Rosters

/<API Version>/accounts/roster

Similar to the All Accounts service, the roster subservice provides a consistent presentation of data for all records, fit for display specifically on a member roster.

HTTP Method Description Conditional Notes
GET Returns account info for the matching user(s) 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:

GET Response

See the GET request section for for the accounts service.

Individual Account

/<API Version>/accounts/<Id>

HTTP Method Description Conditional Notes
GET Returns account info for the matching user No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Updates account information for the matching user No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
  • None

GET Response

See the GET request section for for the accounts service.

PUT Request

Request body:
{
   "D":{
      "Name":"Sample Office Inc",
      "Emails":[
         {
            "Type":"Work",
            "Name":"My Work E-mail",
            "Address":"work@test.com",
            "ProfileDisplay":true,
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile E-mail",
            "Address":"mobile@test.com"
         }
      ],
      "Phones":[
         {
            "Type":"Work",
            "Name":"My Work Phone",
            "Number":"701-555-1212",
            "ProfileDisplay":true,
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile Phone",
            "Number":"702-555-1313",
            "ProfileDisplay":true
         }
      ],
      "Websites":[
         {
            "Type":"Work",
            "Name":"My Work Website",
            "Uri":"http://iamthebestagent.com",
            "ProfileDisplay":true,
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile Website",
            "Uri":"http://m.iamthebestagent.com"
         }
      ]
   }
}

PUT Response

The standard success/fail response is returned.

Individual Account for Reports

/<API Version>/accounts/<Id>/report

Similar to the All Accounts service, the report subservice provides a consistent presentation of data for all records, fit for display specifically on a listing report or a business card.

HTTP Method Description Conditional Notes
GET Returns account info for the matching user 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

See the GET request section for for the accounts service.

Individual Account for Rosters

/<API Version>/accounts/<Id>/roster

Similar to the All Accounts service, the roster subservice provides a consistent presentation of data for all records, fit for display specifically on a member roster.

HTTP Method Description Conditional Notes
GET Returns account info for the matching user 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

See the GET request section for for the accounts service.

Accounts for Office Members

/<API Version>/accounts/by/office/<Id>

HTTP Method Description Conditional Notes
GET Returns all users in the matching officers 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

See the GET request section for for the accounts service.

Current User's Account

/<API Version>/my/account

HTTP Method Description Conditional Notes
GET Returns account info for the current user No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Modifies user settings No VOW and Portal roles only
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
Parameter Required Notes
Standard expansion parameters No

GET Response

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/v1/accounts/20000426143505724621000000",
                "Id": "20000426143505724621000000",
                "UserType": "Office",
                "UserLevel": "Office",
                "Name": "Sample Office Inc",
                "FirstName": null,
                "MiddleName": null,
                "LastName": null,
                "Office": "Sample Office Inc",
                "OfficeId": "20000426143505724621000000",
                "Company": null,
                "CompanyId": null,
                "Mls": "Your Local MLS",
                "MlsId": "20000426143505724628000000",
                "LanguagesSpoken": ["es", "de"],
                "Emails": [
                    {
                        "Id": "20030426173014239760000000",
                        "Type": "Work",
                        "Name": "My Work E-mail",
                        "Address": "work@test.com",
                        "ProfileDisplay":true,
                        "Primary": true
                    },
                    {
                        "Id": "20030521173014276180000000",
                        "Type": "Mobile",
                        "Name": "My Mobile E-mail",
                        "Address": "mobile@test.com"
                    }
                ],
                "Phones": [
                    {
                        "Id": "20040426173010918520000000",
                        "Type": "Work",
                        "Name": "My Work Phone",
                        "Number": "701-555-1212",
                        "ProfileDisplay":true,
                        "Primary": true
                    },
                    {
                        "Id": "20030426173017935470000000",
                        "Type": "Mobile",
                        "Name": "My Mobile Phone",
                        "Number": "702-555-1313",
                        "ProfileDisplay":true,
                    }
                ],
                "Websites": [
                    {
                        "Id": "20080111173011632650000000",
                        "Type": "Work",
                        "Name": "My Work Website",
                        "Uri": "http://iamthebestagent.com",
                        "ProfileDisplay":true,
                        "Primary": true
                    },
                    {
                        "Id": "20060412173019920160000000",
                        "Type": "Mobile",
                        "Name": "My Mobile Website",
                        "Uri": "http://m.iamthebestagent.com"
                    }
                ],
                "Addresses": [
                    {
                        "Id": "20090426173019195810000000",
                        "Type": "Work",
                        "Name": "My Work Address",
                        "Address": "101 Main Ave, Phoenix, AZ 12345",
                        "ProfileDisplay":true,
                        "Primary": true
                    }
                ],
                "Images": [
                    {
                        "Id": "20110426173018175220000000",
                        "Type": "Photo",
                        "Name": "My Photo",
                        "Uri": "http://photos.sparkplatform.com/az/...."
                    },
                    {
                        "Id": "20080426173011752890000000",
                        "Type": "Logo",
                        "Name": "My Logo",
                        "Uri": "http://photos.sparkplatform.com/az/...."
                    }
                ],
                "Locale": {
                  "Language": "en"
                },
                "Permissions": {
                  "Editable": false,
                  "EditableSettings": [] 
                },
                "Settings": {
                    "FlexmlsProducts": ["DesktopIdx", "MobileIdx", "WordPressIdx"],
                    "Visible": true,
                    "SearchRestrictions": {
                        "MlsStatus": [
                            "A",
                            "P"
                        ],
                        "PropertyTypes": [
                            "A",
                            "C"
                        ],
                        "PostalCode": null
                    }
                }
            }
        ]
    }
}

PUT Request

Request body:
{
    "D": {
        "GetEmailUpdates": true
    }
}

PUT Response

The standard success/fail response is returned.

Account Description

Attribute Data Type Writeable Required Searchable Description
ResourceId Character No No No The resource URI to a particular account.
Id Character No No No The unique id for the account.
LoginName Character Member/Office UserTypes Only No No The login name of the user. Will only be returned on creation of a new account. Must be unique in the system. May be manipulated with a prefix to be compliant with the naming convention as put in place by the MLS. Will be defaulted from the ShortId if not populated.
Password Character Member/Office UserTypes Only No No The password of this user. Will only be returned on creation of a new account. One will be defaulted if nothing is passed on create.
See the notes below for details on how to do password assignments and resets.
PasswordValidation Character Member/Office UserTypes Only No No The current password for the user. Will validate the user's current password prior to performing a Password reset. May only be used when updating an individual account via a PUT request.
See the notes below for details on how to do password assignments and resets.
UserType Character Create Only Yes Yes, required The type of account. Possible values are Member, Office and Mls.
UserLevel Character Create Only No Yes The user level of the account. Possible values include all values for UserType as well as Company and Association.
Office Character No No Yes, Eq only The name of the office the user belongs to
OfficeId Character Member Only No Yes, Eq only. No _orderby support The account id of the office the user belongs to. If changed via update, will transfer a user to a new office.
Company Character No No Yes, Eq only The name of the company the user belongs to
CompanyId Character Office Only No Yes, Eq only. No _orderby support The account id of the company the user belongs to.
Mls Character No No No The name of the MLS the user belongs to.
MlsId Character No No Yes The account id of the MLS the user belongs to.
Name Character All UserTypes but Members No Yes, Eq only The full name of the user. See the notes below for more information on searching by name.
MarketingName Character No No No An alternative 'marketing' name.
NamesByLocation JSON Object No No No Attributes in this hash reference the fields to display for various user interfaces and roles as its value. Values are at least one of the following: MarketingName and SystemName. The attributes in this hash are:
  • Footer: The name(s) the agent wishes to show in email and report footers.
  • Listing: The name(s) the agent wishes to be displayed along with listings they have listed or sold.
  • Flyer: The name(s) the agent wishes to be displayed on flyers.
  • PublicView: The name(s) the agent wishes to be displayed in any non-private report.
  • PrivateView: The name(s) the agent wishes to be displayed in private reports.
FirstName Character Member Only No Yes The first name of the user.
MiddleName Character Member Only No Yes The first name of the user.
LastName Character Member Only No Yes The first name of the user.
Email Character No No Yes, no _orderby support For searching only. References Email.Address.
LicenseNumber Character Yes No No The license number of this user. Must be between 1 and 100 characters long.
NrdsId Integer Yes No No The identifier for this user to NRDS.
ShortId Character Yes No No The short identifier for this user in the system. Must be between 1 and 15 characters long. Must be unique by UserType (i.e. Member/Office)
Associations Character List No No Yes, Eq only. No _orderby support The associations the account record belongs to. Consult accounts meta data for possible values. Displayed when not using the Associations expansion.
LanguagesSpoken Character List Yes No Yes, Eq only. No _orderby support The Language codes for the languages the user can speak. See the profile response description for more information.
Tags Character List No No Yes, Eq only. No _orderby support The tags associated with the account record. Consult accounts meta data for possible values.
PostalCode Character No No Yes For searching only. References Address.PostalCode.
FbsIdxCustomer Boolean No No No If true, this user is an IDX customer. Privileged Private roles only. Contact support to request this capability.
Profile Fields Various types Yes No No All account profile fields are also available from this service.
GetEmailUpdates Boolean VOW and Portal only Yes No VOW/Portal roles can only see and modify this field when using the /my/account service.
Permissions Expansion Fields that define per-user permissions for various resources.
Editable Boolean No No No true if the current user may edit the user record being retrieved.
EditableSettings Character List No No No A list of editable actions the current user can take on the account record.Possible values: PasswordChange
Settings Expansion Fields that define per-user settings, such as whether or not the user has access to the system.
FlexmlsProducts Character List Yes No No Privileged API Keys Only. A list of flexmls products the user has purchased. Values include: DesktopIdx, MobileIdx, and WordpressIdx.
OwnerId Character Office Only No No The Id of the designated broker.
IdxParticipant Boolean Office Only No No Indicates whether this office particpates in IDX data sharing.
Visible Boolean No No No If false, the user cannot be retrieved in accounts search results.
Active Boolean Member/Office UserTypes Only No No When false, the user's account is considered inactive, and their profile data should not show on roster reports. This attribute is never false when SystemAccess is true.
SystemAccess Boolean No No No Indicates whether the user has system access to flexmls or Spark API.
MlsSystemAccess Boolean Member/Office UserTypes Only No No Indicates whether the user has access granted to flexmls at the MLS level. Privileged Private roles only. Contact support to request this capability.
Enabled Boolean Member/Office UserTypes Only No No Indicates whether the user has access granted to flexmls. Privileged Private roles only. Contact support to request this capability.
SearchRestrictions. PostalCode Character List No No No An array of PostalCode values the user is limited to when searching listings. If null, the user has no restrictions.
SearchRestrictions. PropertyTypes Character List No No No An array of PropertyType values the user is limited to when searching listings. If null, the user has no restrictions.
SearchRestrictions. MlsStatus Character List No No No An array of MlsStatus values the user is limited to when searching listings. If null, the user has no restrictions.
Searching by Name

When a wildcard is used on the account Name attribute and no white space is present in the search string, the string will be applied to all words in the name, case-insensitive. For example, _filter=UserType Eq 'Member' And (FirstName Eq 'thomas*' Or MiddleName Eq 'thomas*' Or LastName Eq 'thomas*') is (typically) equivalent to _filter=UserType Eq 'Member' And Name Eq 'thomas*'.

When a list of wildcard criteria is provided (e.g. Name Eq 'john*','tim*'), this special searching will only be used if none of the criteria has a white space in it.

Update Passwords

There are two options when updating a password.

The first is a direct update where the Password attribute is passed in and will be assigned to the account.

The second is a password update with validation. In addition to the Password attribute for the new password, you will send an additional attribute of PasswordValidation to validate the old password prior to updating the new password. This is the general usage for a password reset where the end user provides their old password and the new password they wish to acquire.

Expansions

Expansion Roles Single Record Only? Selection Support? Description
Biography All No No Text that provides a brief biographical background for the user.
LoginName Private No No Privileged Private roles only. Contact support to request this capability.
Permissions Private Yes No A hash detailing permissions the current user has on the user record being retrieved.
Settings All No No A hash of additional user settings, detailing restrictions such as searching limitiations.
Associations All No No A hash detailing the associations data, as opposed to the default array of association names. Writing is exclusively granted, see notes below.

API Explorer

Interact with this service using the API Explorer.