# Keller Williams

> Keller Williams Realty, Inc. (KWRI) is the largest US residential real estate brokerage franchise by agent count. Its developer surface is a real but partner-gated Apigee "DevHub" portal at developer.kw.com, fronting a live gateway at partners.api.kw.com (sandbox at sandbox.partners.api.kw.com) and an OpenID Connect authorization server at partners.api.kw.com/idp. Access is not self-serve: a developer applies to integrate, is approved by KWRI, receives a DevHub account, signs the KW API License Agreement, and is then issued an API Key and Secret. Only one API — KW Worldwide Listings Search — publishes its specification anonymously; the rest of the catalog is behind a SAML member login.

Generated by API Evangelist on 2026-07-26. Keller Williams publishes no llms.txt of its own (probed https://developer.kw.com/llms.txt — the Angular SPA answers every unmatched path with the same HTML shell). This file is generated from apis.yml and the artifacts harvested into the api-evangelist/keller-williams repository.

## Access model

- Apply to Integrate / Become a Partner: https://share.hsforms.com/2JQHe7zfKRLSo_cXKjy-5nwbg45/
- KW API License Agreement: https://developer.kw.com/api-license-agreement
- DevHub Terms and Conditions: https://developer.kw.com/terms-and-conditions
- Support (PartnerTechSupport@KW.com, 24-48 business hours): https://developer.kw.com/support
- Environments: production https://partners.api.kw.com — sandbox https://sandbox.partners.api.kw.com
- Every request carries two credentials: an `api-key` header and an `Authorization` header (Basic base64(API_KEY:API_SECRET) for non-user-scoped resources, Bearer for user-owned Command data).
- Access tokens expire in 2 days; refresh tokens in 365 days and are single-use.

## APIs

- [KW Worldwide Listings Search API](https://developer.kw.com/docs/listingskww/1/overview): the only anonymously specified API. OpenAPI 3.0.1, 5 paths, 7 operations against https://partners.api.kw.com/v2 — listings search, create, update, delete, plus a controlled-vocabulary lookup table, region details and an organization-people lookup.
- [KW Partner Identity API (OpenID Connect)](https://developer.kw.com/getting-started): authorization-code + PKCE S256 flow at https://partners.api.kw.com/idp, 40 advertised scopes, RS256 ID tokens, revoke/introspect/userinfo/end_session/device_authorization endpoints.
- [KW Marketplace Subscription & Metered Billing API](https://developer.kw.com/marketplace-documentation): outbound subscription lifecycle webhooks to a partner-registered HTTPS endpoint, plus partner-called metered billing and async subscription confirmation.

## Specs

- [KW Worldwide Listings Search OpenAPI 3.0.1](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/openapi/keller-williams-listings-search-openapi.json)
- [OpenID Connect discovery document](https://partners.api.kw.com/idp/.well-known/openid-configuration)
- No AsyncAPI, GraphQL schema or gRPC definition is published (the DevHub catalog record returns null for all three).

## Operations

- `listings-read` — GET /listings — search listings
- `listings-create` — POST /listings — create a listing
- `listings-details-update` — PATCH /listings/{list_uuid} — update a listing
- `listings-details-delete` — DELETE /listings/{list_uuid} — delete a listing
- `listings-read-by-table` — GET /listings/lookup-table — controlled vocabularies
- `listings-region-details-read` — GET /listings/region/{regionId} — region details
- `listings-region-people-read` — GET /listings/orgs/{orgId}/people — people in an organization

## Conventions

- Versioning is URI-path: v1 (marketplace billing), v2 (listings, partner token refresh), v3 (contacts).
- Pagination: `page[offset]`/`page[limit]` (JSON:API style), flat `offset`/`limit`, or `scroll`/`scroll_id`. Max limit 100.
- Filtering: `filter[:attribute][:operator]=:value` on listings; a base64-encoded JSON filter document on contacts. Operators: is, like, gt, gte, le, lte, between, radius, coordinate, in — prefix `!` to negate.
- Sorting: `sort=field1,-field2`; geo sorting needs `location[lat]` and `location[lon]`.
- Errors are a flat `{success, errorCode, message}` JSON envelope — not RFC 9457. `success` is the string "false" on errors.
- No idempotency key exists on any write operation.
- A quota is enforced (429 TOO_MANY_REQUESTS, "Quota exceeded") but no numeric limit or RateLimit header is published.

## Docs

- [Developer portal (DevHub)](https://developer.kw.com/)
- [Getting Started — DevHub, apps, teams, OpenID Connect flow](https://developer.kw.com/getting-started)
- [Getting Started — Marketplace integrations, environments, keys](https://developer.kw.com/docs-getting-started)
- [Authentication and token lifetimes](https://developer.kw.com/docs-authentication)
- [Refresh token endpoint](https://developer.kw.com/docs-refresh-token)
- [Filtering and sorting](https://developer.kw.com/filtering-and-sorting)
- [Marketplace documentation index](https://developer.kw.com/marketplace-documentation)
- [Subscription lifecycles](https://developer.kw.com/subscription-lifecycle-walkthrough)
- [Synchronous subscription](https://developer.kw.com/docs-synchronous-subscription)
- [Asynchronous subscription](https://developer.kw.com/docs-asynchronous-subscription)
- [Subscription async management](https://developer.kw.com/subscription-async-management)
- [Metered billing](https://developer.kw.com/metered-billing)
- [Error code reference](https://developer.kw.com/docs-error-codes-reference)
- [Contact timeline events](https://developer.kw.com/timelines)
- [Partner base path migration guide](https://developer.kw.com/base-path-migration-guide)
- [API catalog](https://developer.kw.com/apis)
- [Keller Cloud status page](https://status.kw.com/)

## API Evangelist artifacts

- [apis.yml](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/apis.yml)
- [Authentication profile](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/authentication/keller-williams-authentication.yml)
- [OAuth scopes](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/scopes/keller-williams-scopes.yml)
- [API conventions](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/conventions/keller-williams-conventions.yml)
- [Error code registry](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/errors/keller-williams-error-codes.yml)
- [Problem types derived from the spec](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/errors/keller-williams-problem-types.yml)
- [Data model](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/data-model/keller-williams-data-model.yml)
- [Marketplace webhook catalog](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/asyncapi/keller-williams-marketplace-webhooks.yml)
- [Lifecycle, versioning and status](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/lifecycle/keller-williams-lifecycle.yml)
- [Sandbox and test environments](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/sandbox/keller-williams-sandbox.yml)
- [Standards conformance](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/conformance/keller-williams-conformance.yml)
- [Published examples extracted from the spec](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/examples/keller-williams-listings-search-examples.json)
- [Agent skills](https://raw.githubusercontent.com/api-evangelist/keller-williams/refs/heads/main/skills/_index.yml)

## Notes for agents

- Nothing here can be called anonymously. Every endpoint returns 401 BAD_TOKEN_AUTHENTICATION without an approved partner credential — including the sandbox.
- Keller Williams holds no RESO certification and its listings contract is not RESO Data Dictionary aligned. The spec states the service "is not a substitution for or tied to any Multiple Listings Services database records." Do not treat KWLS data as MLS data.
- The OIDC discovery document is served at `/idp/.well-known/openid-configuration`, not at the issuer root; resolving the issuer root returns 404.
- The advertised `jwks_uri` (https://partners.api.kw.com/idp/keys) returns 404 anonymously, so ID-token signatures cannot be verified without partner access.