> ## Documentation Index
> Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Find the right filings

> Choose catalog browsing, document search, or native-reference lookup and make explicit coverage and filter choices.

Use [connection setup](/guides/index#connect-once) for authentication and request
conventions. You need permission to view SERFF filings.
Readonly user keys can browse and search; content access and export policy are
checked separately when reading or downloading a file.

## Choose an operation

| Question | Operation | What the result means |
| - | - | - |
| Which filings match known metadata? | `GET /api/v2/filings` | Live catalog traversal with keyset pagination across all dates |
| Which documents discuss this wording? | `POST /api/v2/filings/search` with `query` | A bounded set of candidate filings and matching files |
| Which filing has this native reference? | GET catalog with `source` and `sourceReference` | Exact source-qualified lookup; use the returned UUID for detail |

Use GET for metadata browsing and POST for document or tracking-number queries. Both discovery responses
contain a `filings` array and nullable `nextCursor`. Search also reports
`exhaustive`; a text query does not enumerate every matching document in the corpus.

## Browse with GET filters

For example, find California filings with company names containing “Mutual” and
an approved normalized outcome:

```http theme={null}
GET /api/v2/filings?state=CA&companyNameContains=Mutual&normalizedOutcome=APPROVED&limit=20
```

Different filters combine with AND; repeated values of a repeatable exact filter
combine with OR. Exact company/product names are case-sensitive. Their `Contains`
variants match literal substrings without treating `%` or `_` as wildcards.
Carrier exclusions omit filings with unknown carrier codes as well as matches.
See [List catalog filings](/api-reference/filings/list-catalog-filings) for the
supported fields, normalized enums, repetition rules, and bounds.

Each listed filing includes `businessType`, `normalizedOutcome`,
`filingTypeNormalized`, and `stateStatusChangedDate`, with the same field names
and types as search results. Unavailable values are `null`; dates use
`YYYY-MM-DD`. Inspect these fields directly from the list before deciding
whether you need filing detail.

Use returned carrier or group IDs for identity-based research; see
[Research a carrier or MGA](/guides/carrier-filings). A company-name substring
and a carrier association answer different questions.

## Choose classifications and dates

Use normalized `toiCode` and `subToiCode` from returned filing metadata to select
GET's `toi` and `subToi` filters. For example, homeowners uses `04.0` and a returned
label can read `4.0 Homeowners`. Inspect both the code and label before narrowing
an unfamiliar line of business. Raw source labels can vary; do not send the full
label where a code is required. A null normalized code is unknown, and a code
filter can omit filings whose classification has not been normalized.

Similarly, choose `normalizedOutcome` and `filingTypeNormalized` from the reference
enums. Raw `sourceStatus` and `filingType` filters require one explicit `source`.
`FILED`, a closed filing, and `APPROVED` are distinct observations.

Define “recent” with a date and window appropriate to the question:

| Meaning | GET date filters |
| - | - |
| Submitted during a period | `submissionDateFrom` / `submissionDateTo` |
| Received a disposition during a period | `dispositionDateFrom` / `dispositionDateTo` |
| Source status changed during a period | `stateStatusChangedDateFrom` / `stateStatusChangedDateTo` |

Bounds are inclusive and must be ordered. Supplying a date bound excludes rows
without that date. GET defaults to submission date descending with nulls last;
use `sort=submissionDate` for ascending order. Other sort keys are
`dispositionDate`, `stateStatusChangedDate`, `companyName`, `state`, and
`sourceReference`. Prefix a key with `-` for descending and repeat `sort` in
priority order for up to three distinct fields, for example
`sort=state&sort=-dispositionDate`. All keys put nulls last, followed by filing ID
ascending as the final tie-breaker. Reference sorting uses the native reference
shown in the response, including IRFS references without `FL-`. A date filter does not change sorting
and does not establish a policy's effective date.

## Look up a native reference

Use one source and the native spelling: SERFF references normalize to uppercase,
while Florida IRFS references use a value such as `26-003347`, without the internal
`FL-` prefix. Substitute the reference you are researching:

```http theme={null}
GET /api/v2/filings?source=florida_irfs&sourceReference={sourceReference}
```

Use a returned `id` with [filing detail](/api-reference/filings/get-a-catalog-filing).
A native reference is not a Filing UUID. Exact reference lookup avoids guessing
whether a string should be interpreted as a text query or identifier. A partial
reference does not perform a prefix search.

With exactly one `source` and one exact `sourceReference`, each returned filing
also includes `description` (`null` when unavailable). General browsing and
multi-reference requests omit `description` and do not load it.

## Search document text

Find Texas documents discussing roof exclusions, explicitly ranked by relevance
rather than the default submission-date order:

```http theme={null}
POST /api/v2/filings/search
Content-Type: application/json

{
  "query": "roof exclusions",
  "filters": [{ "field": "state", "operator": "eq", "value": "TX" }],
  "sort": [{ "field": "relevance", "direction": "desc" }],
  "includePassages": true,
  "limit": 5
}
```

Filters combine with AND; values within `in` and `containsAny` combine with OR.
Text and identifier queries default to recent data (2018+ and undated). Set
`dataScope` explicitly to `historical`, `recent`, or `all` when that choice matters.
To match a phrase, quote it inside `query`, for example `"\"roof exclusions\""`,
and supply a narrowing state, company, NAIC, tracking-number, or date filter.
Without a narrowing filter, quotes are removed and the service uses keyword
search. Exclusion filters alone do not qualify.

Select a result's `matches[].fileId` to read beyond a passage. Passages and page
numbers can be absent even when requested. A match's evidence `versionId` is
currently null, so current original bytes cannot be assumed to match indexed text.

Text search has a bounded candidate window and returns `exhaustive: false`.
`includePassages: true` limits retrieval to 100 candidate documents; false or
omitted permits up to 1,200. Omitting the setting uses configured passage behavior.
Several documents may belong to one filing. Sorting applies within this window;
a null cursor does not prove there are no more corpus matches. Narrow the question
when more specific evidence is needed.

Carrier search filters use `carrierIds` with `containsAny`/`notContainsAny` and
returned canonical IDs or numeric shorthand strings. Group equality uses `groupId`.
Search's `trackingNumber` filter uses backend spelling, including `FL-` for IRFS;
prefer native-reference GET lookup for an exact source-qualified reference.
See [Search filings](/api-reference/filings/search-filings) for the full contract.

## Use GET for metadata browsing

POST requires a nonempty `query`. Missing or blank queries return
`400 invalid_request` with guidance to use `GET /api/v2/filings`.
For example, browse company metadata alphabetically with:

```http theme={null}
GET /api/v2/filings?companyNameContains=Insurance&sort=companyName&limit=20
```

When moving an old queryless POST request to GET:

* Map `carrierIds` to `carrier`, `groupId` to `group`, `toiCode` to `toi`, and
  `subToiCode` to `subToi`. Use `excludeCarrier` for carrier exclusions.
* Map company/product `contains` to `companyNameContains`/`productNameContains`.
  GET matches literal substrings; `%` and `_` are not wildcards.
* Use each date's `From`/`To` parameters for ranges; use the same date for both
  bounds to express date equality.
* Use `source` plus native `sourceReference` for tracking-number filters.
  Split mixed-source reference lists into separate requests.
* Repeat exact-value parameters for OR, and repeat sort keys in priority order.
  Set-valued filters accept up to 100 values; general text filters allow 500
  characters per value. State and insurance codes retain their narrower formats.
* Start a new GET traversal; POST cursors cannot be used on GET.

GET combines different filters with AND, but does not support arbitrary nested
conditions, multiple substring conditions on one field, or requiring overlap
with each of several separate carrier groups. It searches all dates by default;
use explicit date bounds when needed. It has no `dataScope` parameter.

Search with a query keeps its existing behavior: complete tracking-number queries
match exactly and partial identifier queries use bounded prefix lookup. Search
metadata sorts put missing values last; relevance retains backend score order.

## Continue a search

Repeat the semantic request with its returned cursor, keeping filters, sorting,
data scope, passage setting, and page size unchanged. Search reruns against live
data, so ranking or metadata changes can cause repeats or omissions. Deduplicate
filing IDs. Use [Pagination and recovery](/guides/pagination-and-recovery) for
checkpointing, expiry, and changed-filter examples.

## Read a result progressively

Follow [Read and cite document evidence](/guides/read-filing-documents) for
existing text reads, continuation after interruption, and evidence-version limits.

## Download the original

Follow [Download the original](/guides/read-filing-documents#download-the-original)
for a version-pinned download and safe redirect handling.

## Inspect forms and rate impact

Use [Interpret forms and rate impact](/guides/filing-research-data) to distinguish
unsupported sources, empty results, null fields, and genuine zero values.

## Handle errors

Use [Pagination and recovery](/guides/pagination-and-recovery#repair-a-failed-request)
to choose the next request without silently broadening the research question.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.