Apartments.com API v1

Overview

The Apartments Customer APIs provides access to customer data—contact your customer service representative for access and more information. The APIs consist of HTTP RPC-style methods and must be called using HTTPS. See the documentation for all endpoint parameters.

Authentication

Customers must use OAuth authentication and is based on the Resource Owner Password Credentials Grant flow of the OAuth 2 specification. A client application makes a request to the POST endpoint to exchange credentials for a bearer token. When accessing the API, the application uses the bearer token to authenticate.

Tokens are passwords

Keep in mind that the username, password, and the bearer token itself grant access to make requests on behalf of a user. These values should be considered as sensitive as passwords and must not be shared or distributed to untrusted parties.

Getting Started with the Reviews API

Review retrieval for customer listings.

GET https://api.apartments.com/v1/api/reviews?pageSize=100&pageNumber=1
Authorization: Bearer <TOKEN>
Accept: application/json

HTTP/1.1 200 OK
{
  "ReviewCount": 1,
  "CurrentPage": 1,
  "TotalPages": 1,
  "Reviews": [
    {
      "ReviewId": 1234,
      "CultureCode": "en-us",
      "Title": "I love this place!",
      "Text": "I have live here for 2 years now and...",
      "Rating": 4
    }
  ]
}

Comment submission.

POST https://api.apartments.com/v1/api/reviews/123/comments
Authorization: Bearer <TOKEN>
Accept: application/json
{ 
  "CommentText": "From the management and maintenance teams, thanks for the review!",
  "CultureCode": "en-us",
  "CommentTranslations": [
    "CultureCode": "es-us",
    "CommentText": "De los equipos de gestión y mantenimiento, gracias por el comentario!"
   ]
}

HTTP/1.1 200 OK
{
  "CommentId": 1
}

Discovering a client's other properties

When a client manages several properties grouped under one HQ, this endpoint returns every listing under that HQ so reviews can be collected for all of them, rather than one listing key at a time. Submit the listing key of any one property you already know, and the response identifies the rest. Each returned ListingKey is the same key the reviews endpoints above accept. Available to integration partners only.

GET https://api.apartments.com/v1/api/listings/hq?listingKey=<LISTINGKEY>
Authorization: Bearer <TOKEN>
Accept: application/json

HTTP/1.1 200 OK
{
  "TotalCount": 113,
  "Listings": [
    {
      "ListingKey": "2xy0818",
      "PropertyName": "Colonnade at The Market Place",
      "Address": {
        "StreetAddress": "3000 Marketplace",
        "City": "Irvine",
        "StateCode": "CA",
        "PostalCode": "92602",
        "CountryCode": "US"
      }
    }
  ]
}

The listing key you submit is included in the results, and TotalCount is always the number of listings in the response. The response is not paged — every listing under the HQ comes back in one call. An HQ with no listings returns 204 No Content.

API Documentation

See the documentation for all endpoint parameters.

Localization

Apartments.com Review API localizes its content in the following languages: en-us (English), es-us (Spanish). Comment submissions will default to English (en-us) if not specified. Alternative translations may be submitted via the translations collection. Reviews returned on the retrieval endpoints will only return content in its origin language.

Errors

Apartments.com APIs use conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a page number was invalid, etc.), and codes in the 5xx range indicate an error with Apartments.com servers.

Questions

For other questions or feature requests, please contact support@apartments.com.