Client API
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.
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.
Note: For the latest features, we always recommend using the latest version of the API. The current version of the API is v1
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"
}
]
}
}
Links
Each resource contains a links
field containing an array of Link objects. These objects provide URLs for the current resource and any associated resources.
Note: Arel
field with a value of self
is for the current object, however, other values may be present.
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 5xx
category 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
Email Update Signup Request
Collection: https://www.idxhome.com/api/v1/client/emailUpdateSignupRequests.json
Single: https://www.idxhome.com/api/v1/client/emailUpdateSignupRequest/{emailUpdateSignupRequestId}.json
Property Organizer Signup Request
Collection: https://www.idxhome.com/api/v1/client/propertyOrganizerSignupRequests.json
Single: https://www.idxhome.com/api/v1/client/propertyOrganizerSignupRequest/{propertyOrganizerSignupRequestId}.json
Listing Report Signup Request
Collection: https://www.idxhome.com/api/v1/client/listingReportSignupRequests.json
Single: https://www.idxhome.com/api/v1/client/listingReportSignupRequest/{listingReportSignupRequestId}.json
Open Home Report Signup Request
Collection: https://www.idxhome.com/api/v1/client/openHomeReportSignupRequests.json
Single: https://www.idxhome.com/api/v1/client/openHomeReportSignupRequest/{openHomeReportSignupRequestId}.json
Market Report Signup Request
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?