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}.

Not yet ingested: zero holder records today. The holder directory holds no records yet, so every search returns an empty result set. That is a property of the dataset, not of your query: responses carry meta.coverage.status = "not_yet_ingested" so it is machine-detectable. The endpoint itself is live, authenticated, and stable, and the response shape documented below will not change as coverage grows, so you can integrate against it now. For production work today, use Search Certificates, which covers 1,267,795 certificates across 52 Florida counties.

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.