RentLinx Real-Time Property Syndication API

The RentLinx Real-time Property Syndication API allows RentLinx partners to get updates from RentLinx immediately as properties are updated and added by property managers. This article has technical instructions for RentLinx partners on how to implement this integration to receive real-time property data from RentLinx.

If you are interested in becoming a RentLinx partner, please contact us!

Overview

The integration consists of three HTTP requests. In chronological order, they are:

  1. RentLinx sends an HTTP POST request to your server with a list of Property ID values for properties that have new information.
  2. The partner server sends an HTTP GET request to RentLinx.com requesting property data for the updated properties.
    • The response is XML data with the property information for those properties.
  3. The partner server sends an HTTP POST request to RentLinx with the URL of each property's web page.

1. RentLinx → Partner POST: Property Update Notifications

Request

RentLinx sends a "property update notification" HTTP POST to an endpoint on your server that you set up to accept these requests. For example, a partner whose web server is "partner.example.com" might set up: 

https://partner.example.com/api/rentlinx/properties

The content of the POST request is a JSON-format document with two parameter-value pairs:

Key Value
ApiKey Your secret API key issued to you by RentLinx. This value is populated only when your API endpoint is HTTPS (not HTTP), to preserve the secrecy of your key. If your endpoint is HTTPS and this value is missing or incorrect, then the request is not from RentLinx, and you should ignore it.
RentLinxPropertyIDs Array of RentLinx property ID integer values.

Example POST body content: 

{
  "ApiKey": "YOUR_RENTLINX_API_KEY_HERE",
  "RentLinxPropertyIDs": [
    1378143,​1378141,​1971403,​1451026,​1374561,​1378036,​1371423,​1371424,​1971568,​1371426,​1718539,​1718515,​1831163,​1718540,​1362068,​1376341,​1378221,​1378222,​1378220,​1380468,​1380467,​1417322,​1385612,​1971567
  ]
}

RentLinx sends up to 500 property IDs at a time, at most once every 10 seconds.

Security

  • We strongly recommend that your POST endpoint be secure (HTTPS), so that you can verify that data you receive is legitimate data sent by RentLinx, by verifying that the ApiKey value is correct.

Response

Your server responds with an HTTP 200 OK if the message was received successfully, or an appropriate HTTP error code if something went wrong.

  • If an error is returned, RentLinx will retry the request again later.
  • If errors continue to occur after several attempts, RentLinx will contact you.

Implementation note

There are a couple main reasons we designed the API to post only outgoing Property IDs and require a return request to grab the property data.

  1. Encourage queueing: We recommend you implement your system to queue incoming update requests so that you can quickly return success, then asynchronously request and process the property data as your system's resources allow.
  2. Simpler implementation: This design allows the endpoint for incoming requests that you need to build to be simpler: It needs to accept, parse, and store only a list of property IDs, instead of the full set of data for each property, as updates come in throughout the day. The more complex logic that you may have around parsing property data (e.g. duplicate detection) can be deferred until after you request the actual property data (as described in the next section below).

Implementation aid: Manually triggering an update POST

While you are implementing your endpoint to receive POST notifications from RentLinx, may wish to have RentLinx send you a POST notification as a test, so you can see whether your endpoint is properly receiving and handling the notification.

To have RentLinx send you a POST notification for testing purposes, send a GET request to RentLinx using an URL like: 

https://www.rentlinx.com/api/v1/Test_RequestPropertyUpdate?apiKey=YOUR_RENTLINX_API_KEY_HERE&count=1&postUrl=https%3A//partner.example.com/api/rentlinx/properties

Replace the apiKey value with your real secret RentLinx API keyvalue, and the count value with the number of properties you'd like to have appear in the update (between 1 and 500).

For the postUrl parameter value, enter the UrlEscaped URL value to which you'd like RentLinx to send the test POST.

You can just paste this request URL into a web browser to trigger RentLinx to send you a test update POST; no need to build this request into a program.

2. Partner → RentLinx POST: Property Data Request

Request

After receiving a POST from RentLinx that new property data is available, your server needs to send one or more HTTP POST requests to RentLinx to obtain that data. The endpoint URL is: 

https://www.rentlinx.com/api/v1/PropertyData?apiKey=YOUR_RENTLINX_API_KEY_HERE

The YOUR_RENTLINX_API_KEY_HERE value must be replaced with the secret API key issued to you by RentLinx.

The body of the POST is a JSON-format document with a single key-value pair:

Key Value
RentLinxPropertyIDs Array of RentLinx property ID string values for which you are requesting data. You can include a maximum of 2000 property IDs per request.

In response to a property update notification, typically you will make a single property data request with all of the PropertyID values present in the request body. Example request body: 

{
  "RentLinxPropertyIDs": [
    1378143,​1378141,​1971403,​1451025,​1451026,​1374561,​1378036,​1371423,​1371424,​1971568,​1371426,​1718539,​1718515,​1831163,​1718540,​1362068,​1376341,​1378221,​1378222,​1378220,​1380468,​1380467,​1417322,​1385612,​1971567
  ]
}

Content-Type Header

Your HTTP POST request must include the HTTP header and value:

Content-Type: application/json

Alternative: HTTP GET

Alternatively, you can call PropertyData with the HTTP GET method, instead of POST. In this case, you'll include the list of comma-separated PropertyIDs as an additional URL parameter.

The main limitation of using GET is the total length of the URL must be less than 2000 characters (which equates to about 170 properties maximum per request), or else RentLinx will return an HTTP 404 error due to maximum URL length restrictions.

You may make multiple GET requests to ask for data for a large set of property IDs, with each individual request asking for a portion of the set of ID values.

For brevity, here's an example of a set of requests where 5 PropertyID values are requested at a time. (In a real implementation, RentLinx recommends a larger set of PropertyID values per request, to avoid the inefficiency of more network round-trips than necessary.)

Request 1 (HTTP GET): 

https://www.rentlinx.com/api/v1/PropertyData?ApiKey=YOUR_RENTLINX_API_KEY_HERE&RentLinxPropertyIDs=1378143,1378141,1971403,14510250,1451026

Request 2 (HTTP GET): 

https://www.rentlinx.com/api/v1/PropertyData?ApiKey=YOUR_RENTLINX_API_KEY_HERE&RentLinxPropertyIDs=1374561,1378036,1371423,1371424,1971568

Request 3 (HTTP GET): 

https://www.rentlinx.com/api/v1/PropertyData?ApiKey=YOUR_RENTLINX_API_KEY_HERE&RentLinxPropertyIDs=1371426,1718539,1718515,1831163,1718540

Request 4 (HTTP GET): 

https://www.rentlinx.com/api/v1/PropertyData?ApiKey=YOUR_RENTLINX_API_KEY_HERE&RentLinxPropertyIDs=1362068,1376341,1378221,1378222,1378220

Request 5 (HTTP GET): 

https://www.rentlinx.com/api/v1/PropertyData?ApiKey=YOUR_RENTLINX_API_KEY_HERE&RentLinxPropertyIDs=1380468,1380467,1417322,1385612,1971567

Response

In response to your server's request, RentLinx replies with an XML document in DataLinx format with information on the requested properties. See the DataLinx format help article for details on that format. The response has a status of HTTP 200 OK.

Your server should store the property data (e.g. in a database).

Removed properties

If one of the requested property listings was deleted by the property owner or otherwise should be taken down from being actively listed, then that property is included in the XML document with an empty Property element, for example: 

<Property PropertyID="1378143" />

These properties need to be promptly removed from your website.

Hyphenated PropertyID values

For certain properties, RentLinx returns multiple Property elements for a single requested PropertyID value. For each such Property element, the element's PropertyID value is of the format PPPPPP-NNNNNN, where PPPPPP is the requested PropertyID value, and NNNNNN is the UnitID value for one of that property's units.

Error handling

If there was a problem with the request (e.g. an invalid or nonexistent RentLinxPropertyID value was specified), then the response has an appropriate HTTP 4xx or 5xx error status code, and the body of the response has some helpful information about what the problem was.

Requirements

Max properties per request: You can request data for a maximum of 2000 properties in each message.

Request updated properties only: Limit requests for property data to properties for which an update notification has been received recently. (Don't ignore the update notification messages and instead periodically request data for all properties.)

Timeliness: After receiving a notification that new data is available for a property, please be sure to request that property's data within the next 4 hours. However, the sooner that do you make the request, the fresher the data that you'll have!

Implementation suggestion

You may wish to implement a queue on your server of RentLinx property IDs for which you've received new data notifications, but which you haven't requested yet. Then, at a convenient time, your server can request property data from RentLinx for property IDs from the queue.

Property Location Reports

If you've requested data for many properties, you need to return Property Location Reports for those properties (see below) before you can request data for more properties.

If you have too many properties for which you have requested data but not yet submitted a Property Location Report, and you try to request data for additional properties, then RentLinx will repond with an HTTP 403 error, and a message like: 

Before you can request more property data, you need to return to RentLinx some Property Location Reports for the properties that you've already requested.

If you've forgotten which RentLinx PropertyIDs you've requested data for but have not yet returned a Property Location Report, we've added a RequestedProperties API method that you can use to retrieve them. Make an HTTP GET request to this URL, and RentLinx will return the list of RentLinx PropertyIDs for which you need to submit a Property Location Report: 

https://www.rentlinx.com/api/v1/RequestedProperties?apiKey=YOUR_RENTLINX_API_KEY_HERE

  • Caution: You should not be calling RequestedProperties as part of any automated process; it is provided only as a debugging aid. The set of properties for which you are required to remit Property Location Reports to RentLinx is the same as the set of properties for which you requested data using the PropertyData API; your system should be remembering that set of PropertyID values.

3. Partner → RentLinx POST: Property Location Report

Request

Your server sends an HTTP POST to RentLinx with the URL of each updated property on the partner website. The information is in RentLinx Property Location Report XML format.

For properties that were not listed on your website because they didn't meet requirements or had some other problem, the Property Location Report needs to include that information as well.

The RentLinx.com HTTP POST endpoint for Property Location Reports is:

https://www.rentlinx.com/api/v1/PropertyLocationReport?apiKey=YOUR_RENTLINX_API_KEY_HERE

The body of the POST is the Property Location Report XML-format document. See the Property Location Report format help article for details.

Content-Type Header

Your HTTP request must include this HTTP header:

Content-Type: application/xml

Response

RentLinx replies with an HTTP 204 if the report was received successfully. If there was a problem with the report, RentLinx replies with an appropriate HTTP 4xx or 5xx error code, and includes a helpful message about what the problem was in the response body.

Reporting Property Removals

For properties that RentLinx directs you to stop listing on your website, an empty Property element needs to be returned to RentLinx in the property location report to confirm that the property has been taken down.

See the Property Location Report format help article for details and an example.

Reporting Property Page Changes to RentLinx

A Property Location Report also needs to be sent to RentLinx in certain circumstances that don't directly arise from a property having new data from RentLinx. These include:

  • When a property is de-listed from your website (where the property page content is replaced with a message like "This property is no longer available", or the page is removed altogether);
  • When the property's web page has moved (the URL has changed).

For de-listed properties that were previously being listed, specify an appropriate Property Location Report Error ID value for that property. (For example: 6001, "StaleLastUpdatedDate", "This property hasn't been updated recently enough to be displayed.")

Requirements

Timeliness: The property location report must be submitted within at most 30 minutes of the time that the property data request is made to RentLinx.

  • Timely submission of property location reports for notificationed properties is a requirement for continued participation in the RentLinx integration.

If you have multiple websites on which you publish properties

Please let your RentLinx account manager know! In this case, RentLinx may issue you multiple API keys: A "parent" API key for your account, plus one "child" API key for each of your individual websites. In this case:

  1. RentLinx will use the parent API key when sending you property update notifications (step 1 above).
  2. You use the parent API key when submitting property data requests to RentLinx (step 2 above).
  3. You submit a separate property location report for each of your websites. When submitting each report, you use the child API key corresponding to the website for which property location data is being reported.