OAS 3.0.0

Open Exchange HOA API

The Open Exchange HOA API lets you manage HOA operations programmatically. Integrate property data, HOA information, violations, charges, and lease approvals into your software. Built for developers, this API simplifies complex HOA interactions, allowing you to automate processes and reduce manual work in your SFR portfolio management.

Authentication

This API uses bearer tokens for authentication. To access the API endpoints, you need to include a valid API token in the Authorization header of your requests. Example:

Authorization: Bearer YOUR_API_TOKEN

To obtain an API token, please contact our support team at support@mayhoa.com.

Rate Limiting

This API implements rate limiting to maintain system stability. The current rate limit is 100 requests per minute per API key. Rate limit details are included in the response headers:

X-RateLimit-Limit: Maximum number of requests allowed per minute
X-RateLimit-Remaining: Number of requests remaining in the current time window
X-RateLimit-Reset: Time (in seconds) until the rate limit resets

Error Handling

This API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

2xx range indicate success
4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.)
5xx range indicate an error with our servers

Pagination

List endpoints support pagination using 'page' and 'limit' query parameters. The response includes metadata about the total number of items and current page.

Base URL

Production server

Bearer Authentication (BearerAuth)

Client Libraries

Shell

Ruby

Node.js

PHP

Python

cURL Shell

List properties

Retrieve a paginated list of properties in your portfolio. Use this endpoint to fetch property details, including associated HOAs, charges, and violations. Ideal for building property dashboards or running portfolio-wide analysis.

Query Parameters

page
integer
min:
1
default:
1

Page number for pagination
limit
integer
min:
1
max:
100
default:
20

Number of items per page

Responses

200

Successful response with paginated properties
400

Bad request error
401

Unauthorized error
429

Too many requests

GET/properties

Shell cURL

curl --request GET \
  --url https://api.mayhoa.com/properties

Show Schema

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "code": "h0001364",
      "location": {
        "street": "123 Main St",
        "unit": "4B",
        "city": "Springfield",
        "state": "IL",
        "zip": "62701",
        "county": "Sangamon",
        "latitude": 39.78373,
        "longitude": -89.65063
      },
      "hoa": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Springfield Meadows HOA",
        "county": "Sangamon",
        "state": "IL",
        "manager_phone": "(555) 123-4567",
        "manager_email": "manager@springfieldhoa.com",
        "website_url": "https://www.springfieldhoa.com",
        "owner_portal_url": "https://portal.springfieldhoa.com",
        "management_company": "Springfield Property Management",
        "tags": [
          "QUIET",
          "UTILITIES_INCLUDED"
        ],
        "notes": "Build-to-rent community",
        "documents": [
          {
            "id": null,
            "title": null,
            "type": null,
            "date": null,
            "download_url": null
          }
        ]
      },
      "hoa_2": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Springfield Meadows HOA",
        "county": "Sangamon",
        "state": "IL",
        "manager_phone": "(555) 123-4567",
        "manager_email": "manager@springfieldhoa.com",
        "website_url": "https://www.springfieldhoa.com",
        "owner_portal_url": "https://portal.springfieldhoa.com",
        "management_company": "Springfield Property Management",
        "tags": [
          "QUIET",
          "UTILITIES_INCLUDED"
        ],
        "notes": "Build-to-rent community",
        "documents": [
          {
            "id": null,
            "title": null,
            "type": null,
            "date": null,
            "download_url": null
          }
        ]
      },
      "hoa_account": {
        "account_number": "1234001",
        "owner_portal_username": "john.doe@example.com",
        "owner_portal_password": "P@ssw0rd"
      },
      "hoa_2_account": {
        "account_number": "1234001",
        "owner_portal_username": "john.doe@example.com",
        "owner_portal_password": "P@ssw0rd"
      },
      "charges": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "REGULAR_DUES",
          "amount": 250,
          "due_date": "2024-08-01",
          "description": "Landscaping violation",
          "property_id": "123e4567-e89b-12d3-a456-426614174000",
          "hoa_id": "123e4567-e89b-12d3-a456-426614174000",
          "status": "requested"
        }
      ],
      "violations": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "status": "OPEN",
          "subject": "Unauthorized exterior paint color",
          "notice_url": "https://api.mayhoa.com/violations/123e4567-e89b-12d3-a456-426614174000/notice",
          "notice_summary": "Exterior painted without approval",
          "is_critical": false,
          "due_date": "2024-08-15",
          "fines": [
            null
          ]
        }
      ],
      "lease_approvals": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "status": "REQUESTED",
          "notice": "Lease approval is required on an annual basis, with a $50 application fee.",
          "due_date": "2024-08-15",
          "associated_charge": {
            "id": null,
            "type": null,
            "amount": null,
            "due_date": null,
            "description": null,
            "property_id": null,
            "hoa_id": null,
            "status": null
          }
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 1,
  "total_pages": 1
}

Successful response with paginated properties