Find the right filings

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

Use connection setup 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:

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

GET /api/v2/filings?source=florida_irfs&sourceReference={sourceReference}

Use a returned id with filing detail. 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:

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 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:

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 for checkpointing, expiry, and changed-filter examples.

Read a result progressively

Follow Read and cite document evidence for existing text reads, continuation after interruption, and evidence-version limits.

Download the original

Follow Download the original for a version-pinned download and safe redirect handling.

Inspect forms and rate impact

Use Interpret forms and rate impact to distinguish unsupported sources, empty results, null fields, and genuine zero values.

Handle errors

Use Pagination and recovery to choose the next request without silently broadening the research question.