Accounts

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 qualifications for an account
    3. Retrieve qualifications for an account by qualification type
    4. Retrieve qualifications for an account by qualification ID
    5. Retrieve users in an office
    6. Retrieve account info for the current user
    7. Add qualifications
    8. Update qualification
    9. Delete qualification
  4. GET response format

Applicable API Key Roles

This service is available to API keys with private or 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 Adds a qualification (private roles only; returns HTTP 405 otherwise) See below for details
PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

  • Accepts an _expand=Qualifications parameter to include a user’s qualifications.  See qualification information below.

GET Response

See the GET response section below for the data format.

POST Request: Add Qualifications

Make a POST request to add qualifications to /accounts/XX/qualifications with a request body similar to the the sample request below.

POST requests do not require Id to be sent, since records are new.

If a language or designation does not exist in the pre-defined lists, an appropriate error code will be returned and the entire request will not update any records regardless of other qualification sections that were sent in the request. Languages and designations will not allow duplicate entries, but other qualifications will; if a duplicate occurs in a qualification that doesn’t allow duplicates, an error message will be returned and the entire transaction will fail.

Sample POST request to add two designations and an award to a user’s account profile:

{
    "D": {
        "Qualifications": {
            "Designations": [
                {
                    "Code": "ABR",
                    "Dates": "2005-"
                },
                {
                    "Code": "e-PRO",
                    "Dates": "2011-"
                }
            ],
            "Awards": [
                {
                    "Name": "#1 Sales",
                    "Dates": "2006,2011"
                }
            ]
        }
    }
}

The standard success/fail response is returned with the new qualification record in the response if successful.

Qualifications may also be added just to a specific qualification type; for example, to add two new designations, issue a POST to /accounts/XX/qualifications/designations with the following body:

{
    "D": {
        "Designations": [
            {
                "Code": "ABR",
                "Dates": "2005-"
            },
            {
                "Code": "e-PRO",
                "Dates": "2011-"
            }
        ]
    }
}

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 Adds a qualification to this type (private roles only; returns HTTP 405 otherwise) See documentation for POST requests above for details
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 Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Update qualification Private roles only
DELETE Delete qualification Private roles only

GET Request

Parameters:

  • None.

GET Response

See the GET response section below for the data format.

PUT Request: update qualification

Note: private roles only.
Make a PUT request to update qualifications to /accounts/XX/qualifications/QQ/YY/ with a request body similar to the the sample request below.

PUT requests require Id in the URI to identify which row is to be changed.

If a language or designation does not exist in the pre-defined lists, an appropriate error code will be returned and the entire request will not update any records regardless of other qualification sections that were sent in the request. Languages and designations will not allow duplicate entries, but other qualifications will; if a duplicate occurs in a qualification that doesn’t allow duplicates, an error message will be returned.

Sample PUT request to update a qualification (e.g. /accounts/XX/qualifications/designations/201011120813598729000000 ):

{
    "D": {
        "Code": "ABR",
        "Dates": "2004-"
    }
}

The standard success/fail response is returned with the updated qualification record in the response if successful.

DELETE Request: remove qualification

Note: private roles only.

To delete a qualification record, issue a DELETE to /accounts/XX/qualifications/QQ/YY/.

The standard success/fail response is returned.

 

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 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 for both private and IDX roles (not portal). Settings has two sub-attributes: BrokerLoad and SearchRestriction.

Each BrokerLoad setting (e.g. AddListing, etc.) corresponds to whether that user may perform the specific type of listing edit. The API will still block invalid requests, but this information may be used to display the correct user interface based on the user’s permissions.

SearchRestriction 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.

Qualifications are returned only if requested via _expand.

{
    "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": {
                    "BrokerLoad": {
                        "Level": "Member",
                        "AddListing": true,
                        "ChangeListing": true,
                        "PriceChange": true,
                        "Photos": true,
                        "Documents": true,
                        "Videos": true,
                        "VirtualTours": true,
                        "StatusChange": true,
                        "OpenHousesTours": true,
                        "MapLocation": true,
                        "Supplement": true,
                        "Remarks": true,
                        "Supra": true
                    },
                    "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.