Knowledge Base & Support Center

Overview

The iHomefinder Client API allows you to programmatically perform operations that would otherwise be performed from the UI of the Client Control Panel.

The API is a HAL style REST API. Every resource is exposed by a unique URL, and manipulated with GET, POST, PUT, or DELETE HTTP methods.

Getting Started

iHomefinder provides officially supported libraries for the following languages. Each library follows a very similar structure, with small language specific variances.

PHP
Java

Tip: If you are using a different language, you can implement your own library based on one of the official libraries. Contact us for more information.

For general testing of the REST API, we recommend using Postman.

Authentication

With every request, a basic authentication header must be provided. The username and password combination is the same as the IDX Control Panel.

A 401 Unauthorized HTTP status will be returned if authentication is not successful.

Versioning

API versioning allows iHomefinder to provide developers with stable APIs to integrate with, while still allowing for functionality to be introduced or deprecated. When interacting with the API, your request should specify the version you want to use.

Content Type

The response type of the response can be specified as a file extension in the requesting URL.

For example, to retrieve Markets as JSON, include .json in the requesting URL.

https://www.idxhome.com/api/v1/client/markets.json

We also recommend that you provide an Accept header in your request.

Accept: application/json

Note: JSON is currently the only available content type.

Authorization

Depending on a clients account, certain features may not be available in the the API. For example, Agents and Offices can only be added to an account with broker capability.

A 403 Forbidden HTTP status will be returned if attempting to access a resource that is not permitted.

Resources

Resources are the objects which can be retrieved, added, updated and deleted through the API. A resource can represent a single entity (e.g. Listing, Subscriber) or a collection of entities (e.g. Client Boards, Agents) within iHomefinder.

Note: A single resource is named singular (e.g. Office) and a collection of resources are named plural (e.g. Offices).

You can view a full list of resources and information for each of their fields here:
https://www.idxhome.com/api/v1/docs.html

Example Subscribers Collection Resource:

{
    "links": [
        {
            "rel": "self",
            "href": "https://www.idxhome.com/api/v1/client/subscribers.json"
        }
    ],
    "total": 99,
    "limit": 10,
    "offset": 0,
    "results": [
        {
            "links": [
                {
                    "rel": "self",
                    "href": "https://www.idxhome.com/api/v1/client/subscriber/1234.json"
                }
            ]
        },
        {
            "links": [
                {
                    "rel": "self",
                    "href": "https://www.idxhome.com/api/v1/client/subscriber/7890.json"
                }
            ]
        }
    ]
}

Example Subscriber Resource:

{
    "links": [
        {
            "rel": "self",
            "href": "https://www.idxhome.com/api/v1/client/subscriber/1234.json"
        }
    ],
    "id": 1234,
    "agentId": 4321,
    "firstName": "Joshua",
    "lastName": "Johnston",
    "emailAddress": "josh.johnston@example.com",
    "phone": "(866) 700-8855",
    "address": "1900 Addison St.",
    "city": "Berkeley",
    "state": "CA",
    "postalCode": "94704",
    "agent": {
        "links": [
            {
                "rel": "self",
                "href": "https://www.idxhome.com/api/v1/client/agent/4321.json"
            }
        ]
    }
}

Errors

A typical request to the API should result in an 2xx (e.g. 200 OK) HTTP status code. If an error occurs while processing a request, a 4xx or 5xxcategory of status code will be returned.

When an error occurs, a resource may contain a errors field containing an array of Error objects with more information about the error.

Note: For some types of errors, the resulting HTTP respond may not be in the requested content type (e.g. `JSON`).

Retrieving Resources

Resources are retrieved by making a GET request to the URL of the resource. A single resource would typically be retrieved by way of querying a collection of resources. If the ID of the resource is already known, the resource could also be retrieved using the URLs labeled “single”.

Querying

To search for a subset of resources based on particular field values, you would provide each field and the value you’re searching on in the request.

For example, to search for all Subscriber resources with a first name of “Mary”, you would provide firstName=Mary in the request parameters to the Subscribers resource.

GET https://www.idxhome.com/api/v1/client/subscribers.json?firstName=Mary

Pagination

By default, the first 10 resources are returned for any given collection. To retrieve a different subset of resources, you can provide a limit and offset parameter in the request parameters. limit is used to specify the maximum number of resources to return. offset is used to specify the index of the first result to return.

For example, to retrieve Subscriber 20-25, provide `offset=20&limit=5 in the request parameters to the Subscribers resource.

GET https://www.idxhome.com/api/v1/client/subscribers.json?offset=20&limit=5

While there is currently no technical limit on how many resources you can retrieve at a time, we recommend a maximum of 50 per request.

Partial Response

By default, all fields of a single resource (e.g. Subscriber) are returned. For collection resources (e.g. Subscribers), only the links field of each resource is returned by default.

You can provide a fields parameter in the request to specify which fields of a resource are returned. To specify multiple fields, separate each with a comma.

GET https://www.idxhome.com/api/v1/client/subscriber/1234.json?fields=id,firstName

You can also specify all fields by using the * token.

GET https://www.idxhome.com/api/v1/client/subscribers.json?fields=*

Note: Fields with a `null` value are never returned in the response. Additionally, depending on the type of account, not all fields and resources will be available.

Updating Resources

To update a resource, make a PUT request to the rel=self URL of the resource. Each field of the resource should be specified as parameter in the request.

PUT https://www.idxhome.com/api/v1/client/subscriber/1234.json?firstName=Tom&lastName=Miller&emailAddress=tom@example.com&...

Note: Not all resources or fields are updatable (e.g. IDs, timestamps). Please check the resource specification for more information. A `405 Method Not Allowed` HTTP status will be returned if the the resource cannot be updated.

Partial Update

To make a partial update to a resource, you can provide a fields parameter in the request with the name of each field to update. To specify multiple fields, separate each with a comma.

PUT https://www.idxhome.com/api/v1/client/subscriber/1234.json?firstName=Tom&fields=firstName

Creating Resources

To create a new resource, make a POST request to the rel self URL of the collection of resources.

For example, if you want to create a new Subscriber, you would POST the fields to the Subscribers resource.

POST https://www.idxhome.com/api/v1/client/subscribers.json?emailAddress=s.phillips@example.com&firstName=Suzy&lastName=Phillips&...

Note: Not all resources can be created through the API and not all fields can be specified during creation (e.g. IDs, timestamps). Please check the resource specification for more information. A `405 Method Not Allowed` HTTP status will be returned if the the resource cannot be created.

Deleting Resources

To delete a resource, make a DELETE request to the URL of the resource.

DELETE https://www.idxhome.com/api/v1/client/subscriber/1234.json

Note: Not all resources can be deleted through the API. Please check the resource specification for more information. A `405 Method Not Allowed` HTTP status will be returned if the the resource cannot be deleted.

Types of Resources

Client

Single: https://www.idxhome.com/api/v1/client.json

Client Board

Collection: https://www.idxhome.com/api/v1/client/clientBoards.json

Single: https://www.idxhome.com/api/v1/client/clientBoard/{clientBoardId}.json

Board

Single: https://www.idxhome.com/api/v1/client/board/{boardId}.json

Listing

Collection: https://www.idxhome.com/api/v1/client/listings.json

Single: https://www.idxhome.com/api/v1/client/listing/{listingId}.json

Subscriber

Collection: https://www.idxhome.com/api/v1/client/subscribers.json

Single: https://www.idxhome.com/api/v1/client/subscriber/{subscriberId}.json

Market

Collection: https://www.idxhome.com/api/v1/client/markets.json

Single: https://www.idxhome.com/api/v1/client/market/{marketId}.json

Listing Report

Single: https://www.idxhome.com/api/v1/client/listingReport/{listingReportId}.json

Open Home Report

Single: https://www.idxhome.com/api/v1/client/openHomeReport/{openHomeReportId}.json

Market Report

Single: https://www.idxhome.com/api/v1/client/marketReport/{marketReportId}.json

Listing Report Subscription

Collection: https://www.idxhome.com/api/v1/client/listingReport/{listingReportId}/subscriptions.json

Single: https://www.idxhome.com/api/v1/client/listingReport/{listingReportId}/subscription/{listingReportSubscriptionId}.json

Open Home Report Subscription

Collection: https://www.idxhome.com/api/v1/client/openHomeReport/{openHomeReportId}/subscriptions.json

Single: https://www.idxhome.com/api/v1/client/openHomeReport/{openHomeReportId}/subscription/{openHomeReportSubscriptionId}.json

Market Report Subscription

Collection: https://www.idxhome.com/api/v1/client/marketReport/{marketReportId}/subscriptions.json

Single: https://www.idxhome.com/api/v1/client/marketReport/{marketReportId}/subscription/{marketReportSubscriptionId}.json

Agent

Collection: https://www.idxhome.com/api/v1/client/agents.json

Single: https://www.idxhome.com/api/v1/client/agent/{agentId}.json

Office

Collection: https://www.idxhome.com/api/v1/client/offices.json

Single: https://www.idxhome.com/api/v1/client/office/{officeId}.json

More Info Request

Collection: https://www.idxhome.com/api/v1/client/moreInfoRequests.json

Single: https://www.idxhome.com/api/v1/client/moreInfoRequest/{moreInfoRequestId}.json

Schedule Showing Request

Collection: https://www.idxhome.com/api/v1/client/scheduleShowingRequests.json

Single: https://www.idxhome.com/api/v1/client/scheduleShowingRequest/{scheduleShowingRequestId}.json

Contact Request

Collection: https://www.idxhome.com/api/v1/client/contactRequests.json

Single: https://www.idxhome.com/api/v1/client/contactRequest/{contactRequestId}.json

Valuation Request

Collection: https://www.idxhome.com/api/v1/client/valuationRequests.json

Single: https://www.idxhome.com/api/v1/client/valuationRequest/{valuationRequestId}.json

Collection: https://www.idxhome.com/api/v1/client/emailUpdateSignupRequests.json

Single: https://www.idxhome.com/api/v1/client/emailUpdateSignupRequest/{emailUpdateSignupRequestId}.json

Collection: https://www.idxhome.com/api/v1/client/propertyOrganizerSignupRequests.json

Single: https://www.idxhome.com/api/v1/client/propertyOrganizerSignupRequest/{propertyOrganizerSignupRequestId}.json

Collection: https://www.idxhome.com/api/v1/client/listingReportSignupRequests.json

Single: https://www.idxhome.com/api/v1/client/listingReportSignupRequest/{listingReportSignupRequestId}.json

Collection: https://www.idxhome.com/api/v1/client/openHomeReportSignupRequests.json

Single: https://www.idxhome.com/api/v1/client/openHomeReportSignupRequest/{openHomeReportSignupRequestId}.json

Collection: https://www.idxhome.com/api/v1/client/marketReportSignupRequests.json

Single: https://www.idxhome.com/api/v1/client/marketReportSignupRequest/{marketReportSignupRequestId}.json

Did you find this article helpful?

iHomefinder