Search Holders

GET /api/v1/holders/search

Search the certificate holder directory: the funds, LLCs, banks, and individuals that win and hold Florida tax certificates. Each row aggregates a holder's portfolio — how many certificates they hold, their outstanding face value, the counties they operate in, and the tax-year span. Fetch a single holder's full profile by id with GET /api/v1/holders/{id}.

Authentication

curl -H "X-API-Key: fltc_test_..." \
  "https://fltaxcerts.com/api/v1/holders/search?query=magnolia&county=polk&limit=10"

Fetch a single holder by id:

curl -H "X-API-Key: fltc_test_..." \
  "https://fltaxcerts.com/api/v1/holders/hld_3c19a7"

Query Parameters (/holders/search)

Name	Type	Required	Default	Description
query	string (≤200 chars)	no	—	Holder name (case-insensitive contains).
county	string | string[]	no	—	Only holders active in these county slug(s).
sort	enum (face_desc, certificates_desc, name_asc)	no	—	Result ordering.
limit	integer 1-500	no	25	Page size.
offset	integer ≥ 0	no	0	Pagination offset.

The /holders/{id} route takes the holder id as a path parameter and returns a single holder object.

Response (200)

List envelope { data: Holder[], pagination, meta }. The /holders/{id} route returns { data: Holder, meta }.

{
  "data": [
    {
      "id": "hld_3c19a7",
      "name": "MAGNOLIA TAX FUND LLC",
      "normalized_name": "magnolia tax fund",
      "certificate_count": 1842,
      "outstanding_face_amount": 5821044.19,
      "counties": ["polk", "hillsborough", "orange"],
      "first_seen_tax_year": 2018,
      "last_seen_tax_year": 2023
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345", "dataset_status": "live" }
}

certificate_count and outstanding_face_amount reflect certificates still held (not redeemed). To list a holder's certificates, call Search Certificates with holder=<name>.

Error Responses

Status	Code	Cause
400	bad_request	Invalid query parameters.
401	unauthorized	Missing or invalid API key.
404	not_found	No holder with that id (/holders/{id}).
429	rate_limited	Rate limit exceeded.
500	internal_error	Server error — retry with backoff.