Accounts

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

Supported Roles
Available Services
Accounts Description
Expansions

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:

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

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",
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile E-mail",
            "Address":"mobile@test.com"
         }
      ],
      "Phones":[
         {
            "Type":"Work",
            "Name":"My Work Phone",
            "AreaCode":"701",
            "Prefix":"555",
            "LineNumber":"1212",
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile Phone",
            "AreaCode":"702",
            "Prefix":"555",
            "LineNumber":"1313"
         }
      ],
      "Websites":[
         {
            "Type":"Work",
            "Name":"My Work Website",
            "Uri":"http://iamthebestagent.com",
            "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",
            "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:

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

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:

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

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",
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile E-mail",
            "Address":"mobile@test.com"
         }
      ],
      "Phones":[
         {
            "Type":"Work",
            "Name":"My Work Phone",
            "AreaCode":"701",
            "Prefix":"555",
            "LineNumber":"1212",
            "Primary":true
         },
         {
            "Type":"Mobile",
            "Name":"My Mobile Phone",
            "AreaCode":"702",
            "Prefix":"555",
            "LineNumber":"1313"
         }
      ],
      "Websites":[
         {
            "Type":"Work",
            "Name":"My Work Website",
            "Uri":"http://iamthebestagent.com",
            "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"],
                "Tags": ["Agent"],
                "Designations": {
                  "Accredited Buyer Rep" => true
                },
                "Emails": [
                    {
                        "Id": "20030426173014239760000000",
                        "Type": "Work",
                        "Name": "My Work E-mail",
                        "Address": "work@test.com",
                        "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",
                        "InternationalCode":null,
                        "AreaCode":"701",
                        "Prefix":"555",
                        "LineNumber":"1212",
                        "Extension":null,
                        "Primary":true
                    },
                    {
                        "Id": "20030426173017935470000000",
                        "Type": "Mobile",
                        "Name": "My Mobile Phone",
                        "Number": "702-555-1313",
                        "InternationalCode":null,
                        "AreaCode":"702",
                        "Prefix":"555",
                        "LineNumber":"1313",
                        "Extension":null,
                        "Primary":false
                    }
                ],
                "Websites": [
                    {
                        "Id": "20080111173011632650000000",
                        "Type": "Work",
                        "Name": "My Work Website",
                        "Uri": "http://iamthebestagent.com",
                        "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",
                        "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": {
                    "ExternalProducts": [],
                    "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.

All Teams

`/<API Version>/accounts/teams`

Returns all teams for the current user's MLS

HTTP Method	Description	Conditional	Notes
GET	Returns account info for teams	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:

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

GET Response

See the GET request section for for the accounts service.

Accounts on a Team

`/<API Version>/accounts/teams/<Id>`

Returns all user accounts belonging to a team, including the team record itself

HTTP Method	Description	Conditional	Notes
GET	Returns account info for team members	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:

Parameter	Required	Notes
Standard expansion parameters	No
Standard selection parameters	No

GET Response

See the GET request section for for the accounts service.

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	MLS-level users only	The identifier for this user to NRDS.
`ShortId`	Character	Yes	No	Yes	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	Yes	No	Yes, `Eq` only. No `_orderby` support	The tags associated with the account record. Consult accounts meta data for possible values.
`Designations`	JSON Object	No	No	Yes, `Eq` only. No `_orderby` support	A hash with the names of the designations associated with the account record as the keys. Consult accounts meta data for possible designations.
`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.
`"Phones"."Number"`		No	No	Yes	Searches for any matching phone number associated with the user record. Phone numbers must be in one of the following formats, with a line number and prefix always required: 1 555-555-5555 x555 1 5555555555 x555 Example: `_filter="Phones"."Number" Eq '555-5555'`.
`"PrimaryAddress"."City"`		No	No	Yes	Example: `_filter="PrimaryAddress"."City" Eq 'Fargo'`
`"Team"."Owner"`		No	No	Yes	Example: `_filter="Team"."Owner" Eq false`
`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.
`ExternalProducts`	Character List	Yes	No	No	An MLS managed list of non-flexmls products the user is associated with.
`FlexmlsProducts`	Character List	Yes	No	No	Privileged API Keys Only. A list of flexmls products the user has purchased. Values include: `DesktopIdx`, `MobileIdx`, `WordpressIdx`, and `FloPlan`.
`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	Privileged and Replication roles only	If `false`, the user cannot be retrieved in accounts search results without a Privileged or Replication role. If trying to search all Members 'Visible Eq true Or Visible Eq false' filter string should be used to prevent the default of false.
`Active`	Boolean	Member/Office UserTypes Only	No	MLS-level users only	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	MLS-level users only	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	MLS-level users only	Indicates whether the user has access granted to flexmls. Privileged Private roles only. Contact support to request this capability.
`FbsBillable`	Boolean	Member/Office UserTypes Only	No	No	Indicates whether the user is billable in the flexmls system. Will default to false if not populated. Privileged Private roles only. Contact support to request this capability.
`Brokerload.Level`	Character	Member/Office UserTypes Only	No	No	Allows the broker load level to be set. Will default to the UserLevel if not populated. Privileged Private roles only. Contact support to request this capability. See Broker Load for a more detailed explanation.
`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.
`SuperUser.Users`	Array of JSON Objects	Yes	No	No	Privileged Private roles only. An array containing superuser information for a set of accounts. Individual JSON Objects have the following writable attributes: Id: The `Id` of the MLS, Association, Office or Member that you would like to grant this account superuser access to. Contact support to request this capability. AllUsers: If `true`, this account will have superuser access to all members within the MLS or Association specified in the `Id` attribute. Contact support to request this capability. AsUser: If `true`, this account will be able to superuse as the MLS, Office or Member user specified in the `Id` attribute. Contact support to request this capability. BrokerloadOverride: If `true`, this account will be able to override the office or member user's brokerload specified in the `Id` attribute when superusing. Contact support to request this capability.

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.

Updating Broker Load

Broker Load is a group of settings which indicate at what level a user can interact with listings. The Level attribute indicates at what level the user can edit listings. There are finer grained settings within flexmls which can be used.

For a Member UserType, the possible values are:

None - the user cannot edit any listings
Member - the user can edit their own listings
Office - the user can edit any listing in the office they belong to
Company - the user can edit any listing in the company they belong to
Association - the user can edit any listing in one or more associations
Mls - the user can edit any listing in the MLS

For an Office UserType, the values vary by UserLevel.

An Office UserLevel has the following possible values:

None - the user cannot edit any listings
Office - the user can edit any listing in their office

A Company UserLevel has the following possible values:

None - the user cannot edit any listings
Company - the user can edit any listing in any of the offices under their control

Expansions

Expansion	Roles	Single Record Only?	Selection Support?	Description
`Biography`	All	No	No	Text that provides a brief biographical background for the user.
`LastStatusChangeTimestamp`	Private	Yes	No	MLS-level users only. A timestamp logging the last time the user's `Active`, `Enabled`, or `MlsSystemAccess` flags changed.
`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.
`Team`	All	Yes	No	A hash detailing information about the team the user belongs to, if the user does belong to a team. `{ "Team": { "Id": "20000426143505724621000000", "ResourceUri": "/v1/accounts/teams/20000426143505724621000000", "Owner": false, "LeaderId": "20000426143505724621000000" } }` `Id`: The team's `Id` will be the ID of the account record that represents the team. This will always be a `Member`. `Owner`: If the user record being viewed is the team account itself, this will be `true`. `LeaderId`: If the team has a leader specified, this will be the ID of that account record.
`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.