Accounts

This documentation has moved to the Spark Platform website. Please click here to view.

The Accounts services allow information about the all users and the current user’s account, respectively, to be retrieved. Examples of the information include name, contact information, and logos and photos.

  1. Applicable API Key Roles
  2. Authentication
  3. Available Services
    1. Retrieve account info for user(s)
    2. Retrieve account info by ID
    3. Retrieve qualifications for an account
    4. Retrieve qualifications for an account by qualification type
    5. Retrieve qualifications for an account by qualification ID
    6. Retrieve users in an office
    7. Retrieve account info for the current user
    8. Retrieve account info for the current user

Applicable API Key Roles

This service is available to API keys with IDX roles. Within the IDX role, both IDX and Portal permissions may access this service, but the data returned for the IDX permission is always in regards to the agent. Portal permissions returns a limited response only for the My Account service; other services are not allowed. More information about roles may be found here.

Authentication

Requests must be authenticated according to these instructions or HTTP 401 (Unauthorized) will be returned.

Available Services

Retrieve account info for user(s)

URI: /<API Version>/accounts/

HTTP Method Description Notes
GET Returns account info for matching user(s)
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Use the standard search syntax to limit the response. The following fields are supported; please note which fields are required.

  • UserType (required): One of the following values: Member, Office, Company, Mls
  • Name
  • Office
  • Email
  • PostalCode

GET Response

See the GET response section below for the data format. The results are paginated using the standard paging syntax.

Retrieve account info by ID

URI: /<API Version>/accounts/XX

XX is the ID of the user to retrieve.

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

GET Request

No parameters.

GET Response

See the GET response section below for the data format.

Retrieve users in an office

URI: /<API Version>/accounts/by/office/XX

XX is the ID of an office.

HTTP Method Description Notes
GET Returns all users in the matching office
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

No parameters.

GET Response

See the GET response section below for the data format. The results are paginated using the standard paging syntax.

Retrieve qualifications for an account

URI: /<API Version>/accounts/XX/qualifications

XX is the ID of the user to retrieve.

HTTP Method Description Notes
GET Returns qualification info for the matching user
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

  • None.

GET Response

See the GET response section below for the data format.

 

Retrieve qualifications for an account by qualification type

URI: /<API Version>/accounts/XX/qualifications/QQ

XX is the ID of the user to retrieve.

QQ is the qualification type, which is one of the following: designations, expertise, experience, languages, awards, memberships, education.

HTTP Method Description Notes
GET Returns qualification info for the specific qualification type for the matching user
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

  • None.

GET Response

See the GET response section below for the data format.

 

Retrieve qualifications for an account by qualification ID

URI: /<API Version>/accounts/XX/qualifications/QQ/YY

XX is the ID of the user to retrieve.

QQ is the qualification type, which is one of the following: designations, expertise, experience, languages, awards, memberships, education.

YY is the qualification ID for the specific qualification record that is desired.

HTTP Method Description Notes
GET Returns qualification info for the specific qualification ID for the matching user
POST, PUT, DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

  • None.

GET Response

See the GET response section below for the data format.

Retrieve account info for the current user

URI: /<API Version>/my/account/

HTTP Method Description Notes
GET Returns account info for the current user
PUT Allows setting the GetEmailUpdates flag on the user’s account
POST,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

  • Accepts _expand=Settings to include the Settings attribute below. Settings will not be returned unless this parameter is included.

GET Response

This is an example response for all roles and permissions except the IDX role with portal permissions. See below this example for that response.

Note that a null value is returned if a user does not have that specific field, e.g. an MLS account does not have a company or office, and so nulls are returned for office and company attributes.

The Settings attribute is returned only if the parameter _expand=Settings is sent in the request.Settings currently has one sub-attribute, SearchRestriction, that indicates whether the user has restrictions on what listings may be searched. For example, some users are only allowed to search active listings. If SearchRestriction is empty, the user may search any field. Currently, two search restrictions are supported: MlsStatus and PostalCode. The API client may use these settings to inform what search options are available in the application’s user interface. If one restriction is present but not another, then the restriction that’s present will have values returned, but the other will be set to null.
{
    "D": {
        "Success": true,
        "Results": [
            {
                "Name": "Sample User",
                "Id": "20000426173054342350000000",
                "UserType": "Office",
                "Office": "Sample Office Inc",
                "OfficeId": "20030426173014239760000000",
                "Company": null,
                "CompanyId": null,
                "Mls": "Your Local MLS",
                "MlsId": "20000426143505724628000000",
                "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",
                        "Primary": true
                    },
                    {
                        "Id": "20030426173017935470000000",
                        "Type": "Mobile",
                        "Name": "My Mobile Phone",
                        "Number": "702-555-1313"
                    }
                ],
                "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.flexmls.com/az/...."
                    },
                    {
                        "Id": "20080426173011752890000000",
                        "Type": "Logo",
                        "Name": "My Logo",
                        "Uri": "http://photos.flexmls.com/az/...."
                    }
                ],
                "Settings": {
                    "SearchRestriction": {
                        "MlsStatus": [
                            "A",
                            "P"
                        ],
                        "PostalCode": null
                    }
                },
                "Qualifications": {
                    "Designations": [
                        {
                            "Id": "201011120813598729000000",
                            "ResourceUri": "/v1/accounts/20080624194124915376000000/qualifications/designations/201011120813598729000000",
                            "Code": "ABR",
                            "Name": "Accredited Buyer Rep",
                            "Dates": "2005-"
                        }
                    ],
                    "Expertise": [
                        {
                            "Id": "200911120813598729000000",
                            "ResourceUri": "/v1/account/20080624194124915376000000/qualifications/expertise/200911120813598729000000",
                            "Name": "Condo specialist",
                            "Dates": "2005-"
                        }
                    ]
                }
            }
        ]
    }
}

Example response for an IDX role with portal permissions. The GetEmailUpdates attribute is a boolean and indicates whether a portal user has signed up to get daily email updates on new and changed listings.

{
    "D": {
        "Results": [
            {
                "GetEmailUpdates": false
            }
        ],
        "Success": true
    }
}

PUT Request

To update the GetEmailUpdates flag to true or false, issue a PUT to /my/account/ with the following request body. Users who have this set to true will receive daily e-mail updates about new and changed listings.

{
    "D": {
        "GetEmailUpdates": true
    }
}

Comments on this entry are closed.