Getting started

API keys belong to an organization, and organizations belong to a Common Elements account. If you don't have one yet, create an account first. It's free, and you don't need a credit card to browse the platform or start on the free API tier.

During onboarding you'll create or join an organization. Any organization type works for API access (vendor, management company, individual, and so on) — API keys aren't tied to a specific org type.

Once you're signed in, go to Settings → API keys. Click Create API key, give it a name that describes where it'll run (for example "Production server" or "Local dev"), and confirm.

The raw key is shown exactly once, immediately after creation. Copy it and store it somewhere secure — a secrets manager or environment variable, never a committed file. If you lose it, revoke the key and create a new one; there is no way to reveal a raw key a second time.

Keys are prefixed ce_live_ for production use. Every request must send the key in the Authorization header:

Authorization: Bearer ce_live_your_key_here

A new key inherits whatever tier your organization is currently on (Free, by default, for a brand-new org). If you create a second key later after upgrading, it starts on your org's current paid tier rather than resetting to Free.

Every key belongs to one of five tiers. Limits are enforced per key on a rolling monthly window; when a key runs out, requests return 429 Too Many Requests until the window resets.

Start on Free. It's enough to evaluate the API and build against it locally, but it's for personal use and evaluation only — it doesn't carry a commercial-use license. When you're ready to ship, upgrade from the Plan & billing section of the same API keys page, or compare tiers in detail on the developer plans page. Existing keys pick up a tier upgrade automatically; you don't need to regenerate them.

The easiest first call is GET /api/v1/associations/lookup— it searches associations by name or address and doesn't require anything but a query string. Swap in your own key:

curl "https://commonelements.com/api/v1/associations/lookup?q=Pelican+Bay&state=FL" \
  -H "Authorization: Bearer ce_live_your_key_here"

If the key and header are correct, you'll get back a 200with a JSON body. If something's wrong, the most common early mistakes are:

• 401 invalid_api_key— the header is missing, isn't prefixed Bearer (with a trailing space), or the key was revoked.
• 403 scope_not_allowed— the key doesn't carry the scope this endpoint needs (associations lookups need the associations scope; the risk endpoint needs risk).
• 429 quota_exceeded— you've used your tier's monthly request allowance. Wait for the reset or upgrade.

Here's the actual response shape for that lookup call:

{
  "ok": true,
  "data": [
    {
      "id": "org_01JZA...",
      "name": "Pelican Bay Community Association",
      "state": "FL",
      "subtype": "hoa",
      "unit_count": 742,
      "address": "6300 Pelican Bay Blvd",
      "city": "Naples",
      "zip": "34108",
      "external_document_number": "N04000006125",
      "is_claimed": true,
      "created_at": "2025-11-02T14:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Field by field, on the outer envelope:

And inside each object in data:

From here, take the id from any result and pass it to GET /api/v1/associations/{id}/risk to pull risk signals for that specific association — see the worked underwriting example for exactly what that looks like end to end.