> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.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.

Follow [connection setup](/guides/index#connect-once) first. You need permission to view SERFF
filings; read-only keys can browse and search.

## Choose an operation

| Question | Operation | Returns |
| - | - | - |
| Which filings match known metadata? | `GET /insurance/filings` | All matching filings, across all dates |
| Which documents discuss this wording? | `POST /insurance/filings/search` with `query` and `intent` | The top matching filings and files |
| Which filing has this native reference? | `GET /insurance/filings` with `source` and `sourceReference` | The filing with that exact reference |

Both return a `filings` array and a nullable `nextCursor`. Search also returns `exhaustive`, which is
`false` when there may be more matches than it returned.

## Browse with GET filters

Find California filings with company names containing “Mutual” and an approved outcome:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  "https://canary.effectiveai.app/api/v2/insurance/filings?state=CA&companyNameContains=Mutual&normalizedOutcome=APPROVED&limit=20" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

```json Response (first filing) theme={null}
{
  "filings": [
    {
      "id": "fd83e0f5-2c05-4022-b91a-fb3656f63469",
      "source": "serff",
      "sourceReference": "NWPP-G135016204",
      "state": "CA",
      "companyName": "Nationwide Mutual Insurance Company",
      "naicCompanyCodes": ["23787"],
      "naicGroupCode": "140",
      "carrierIds": ["carrier_6F5GSA9"],
      "groupId": "carrier_group_1N7K2RK",
      "productName": "Commercial Output Program",
      "typeOfInsurance": "05.0 CMP Liability and Non-Liability",
      "subTypeOfInsurance": "05.0004 Manufacturers Output",
      "toiCode": "05.0",
      "subToiCode": "05.0004",
      "filingType": "Form",
      "sourceStatus": "Closed - Approved",
      "submissionDate": "2026-07-28",
      "dispositionDate": "2026-09-23",
      "businessType": "Property & Casualty",
      "normalizedOutcome": "APPROVED",
      "filingTypeNormalized": "FORM",
      "stateStatusChangedDate": "2026-09-23"
    }
  ],
  "nextCursor": "v1.U64XEU3mF7LBl-pBo3zb5oiOOcl_iqRVZuL5W8bQHA0"
}
```

Different filters combine with AND; repeated values of one filter combine with OR. Exact company and
product names are case-sensitive. The `Contains` variants match literal substrings (`%` and `_` are
not wildcards). `excludeCarrier` also excludes filings whose carrier is unknown. See
[List catalog filings](/api-reference/filings/list-catalog-filings) for every filter, enum, and limit.

Each listed filing includes `businessType`, `normalizedOutcome`, `filingTypeNormalized`, and
`stateStatusChangedDate`, so you often won't need the detail call. Missing values are `null`, and
dates use `YYYY-MM-DD`.

To research a specific carrier or group, filter by its ID rather than a company-name substring; see
[Research a carrier or MGA](/guides/carrier-filings).

## Choose classifications and dates

Filter by line of business with `toi` and `subToi`, using normalized codes like those in each
filing's `toiCode` and `subToiCode`. For example, homeowners is `04.0` (label `4.0 Homeowners`).
Send the code, not the label. Filings whose classification hasn't been normalized have a null code
and won't match a code filter.

Choose `normalizedOutcome` and `filingTypeNormalized` values from the enums in the reference. The raw
`sourceStatus` and `filingType` filters require a single `source`. `FILED`, closed, and `APPROVED`
mean different things.

Pick the date that matches your 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. A date filter excludes filings that don't have that date.

Results are sorted by submission date, newest first. Other sort keys are `submissionDate`,
`dispositionDate`, `stateStatusChangedDate`, `companyName`, `state`, and `sourceReference`. Prefix a
key with `-` for descending, and repeat `sort` for up to three keys, for example
`sort=state&sort=-dispositionDate`. Nulls sort last, and filing ID breaks ties.

## Look up a native reference

Use one `source` and the native reference, such as a SERFF tracking number:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  "https://canary.effectiveai.app/api/v2/insurance/filings?source=serff&sourceReference=APCG-133627915" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

```json Response (abbreviated) theme={null}
{
  "filings": [
    {
      "id": "6371c8c4-e4d0-4196-ab2a-bae518433104",
      "source": "serff",
      "sourceReference": "APCG-133627915",
      "state": "TX",
      "companyName": "AIG Property Casualty Company",
      "description": "AIG Property Casualty Company is submitting the following endorsements for your review: ..."
    }
  ],
  "nextCursor": null
}
```

SERFF references are case-insensitive. For Florida, use `source=florida_irfs` with the file log
number, such as `26-003347`, without an `FL-` prefix.

Pass the returned `id` to [Get a catalog filing](/api-reference/filings/get-a-catalog-filing); a
native reference isn't a filing ID. Partial references don't match.

A lookup with exactly one `source` and one `sourceReference` also returns each filing's
`description`. Other requests omit it.

## Search document text

Find Texas documents about roof exclusions, ranked by relevance:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  "https://canary.effectiveai.app/api/v2/insurance/filings/search" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "roof exclusions",
    "intent": "Compare how Texas homeowners carriers word roof exclusions for a policy update",
    "filters": [{ "field": "state", "operator": "eq", "value": "TX" }],
    "sort": [{ "field": "relevance", "direction": "desc" }],
    "includePassages": true,
    "limit": 5
  }'
```

```json Response (first filing, abbreviated) theme={null}
{
  "filings": [
    {
      "id": "6371c8c4-e4d0-4196-ab2a-bae518433104",
      "sourceReference": "APCG-133627915",
      "state": "TX",
      "companyName": "AIG Property Casualty Company",
      "productName": "AIG Private Client Group Homeowners Program",
      "filingTypeNormalized": "ENDORSEMENT",
      "normalizedOutcome": "APPROVED",
      "submissionDate": "2023-04-17",
      "matches": [
        {
          "fileId": "b0a6a4e1-204c-4f5e-b0b7-877c64e9f413",
          "versionId": null,
          "name": "APCG-133627915.pdf",
          "passages": [
            {
              "text": "...The department began reviewing exclusions involving cosmetic damage, marring and total roof exclusions...",
              "pageStart": null,
              "pageEnd": null
            }
          ]
        }
      ]
    }
  ],
  "nextCursor": "v1.Jdfu8kDxISuHQL8M7f_9_Sxc18FbFn74vFCo-l_hQV0",
  "exhaustive": false
}
```

Each result has the same filing fields as the list above, plus `matches`: the files that matched,
with passages when you set `includePassages`. To read past a passage, take its `fileId` to
[Read and cite document evidence](/guides/read-filing-documents). Passages and page numbers aren't
always present.

`intent` is required: one sentence, 10 to 500 characters, on what you're looking for and why, for
example "Compare BOP schedule rating ranges for Carrier A and Carrier B in Texas". It improves
ranking. An `intent` that just repeats `query` returns `400 invalid_request`.

`query` can also be a tracking number. A complete tracking number matches exactly; a partial one
matches by prefix.

Filters combine with AND; values inside `in` and `containsAny` combine with OR. Search covers 2018
onward plus undated filings unless you set `dataScope` to `historical` or `all`. Results are sorted
by submission date, newest first, unless you sort by `relevance`.

<AccordionGroup>
  <Accordion title="Match an exact phrase">
    Quote the phrase inside `query`, for example `"\"roof exclusions\""`, and add a narrowing filter
    such as state, company, NAIC code, tracking number, or date. Without one, quotes are ignored.
    Exclusion filters don't count as narrowing.
  </Accordion>

  <Accordion title="Filter by carrier, group, or tracking number">
    Use `carrierIds` with `containsAny` or `notContainsAny`, and `groupId` for a group. The
    `trackingNumber` filter expects IRFS references with an `FL-` prefix; for an exact reference,
    prefer the [GET lookup](#look-up-a-native-reference).
  </Accordion>

  <Accordion title="How many documents search considers">
    Search scores a capped set of candidates: 100 documents with `includePassages: true`, or up to
    1,200 without. Several documents can belong to one filing. When you need more specific results,
    narrow the query or filters, and check `exhaustive` before claiming you found every match.
  </Accordion>
</AccordionGroup>

See [Search filings](/api-reference/filings/search-filings) for the full contract.

## Use GET for metadata browsing

Search requires a non-empty `query`. To browse by metadata, use GET:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  "https://canary.effectiveai.app/api/v2/insurance/filings?companyNameContains=Insurance&sort=companyName&limit=20" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

<Accordion title="Map POST search filters to GET parameters">
  * `carrierIds` becomes `carrier`, `groupId` becomes `group`, `toiCode` becomes `toi`, and
    `subToiCode` becomes `subToi`. Use `excludeCarrier` for exclusions.
  * Company and product `contains` become `companyNameContains` and `productNameContains`.
  * Date ranges use each date's `From` and `To` parameters; set both to the same date for equality.
  * Tracking-number filters become `source` plus `sourceReference`, one source per request.
  * Repeat a parameter for OR, and repeat `sort` in priority order. Set filters accept up to 100
    values; text filters accept up to 500 characters.
  * Start without a cursor; POST cursors don't work on GET.

  GET doesn't support nested conditions or several substring conditions on one field. It searches
  all dates and has no `dataScope`.
</Accordion>

## Continue a search

Resend the same request with `cursor` set to `nextCursor`, keeping filters, sort, `dataScope`,
`includePassages`, and `limit` unchanged. Each page reruns the search, so deduplicate by filing ID.
See [Pagination and recovery](/guides/pagination-and-recovery).

## Next steps

* [Read and cite document evidence](/guides/read-filing-documents): read text and download originals.
* [Interpret forms and rate impact](/guides/filing-research-data): read extracted forms and rates.
* [Pagination and recovery](/guides/pagination-and-recovery#repair-a-failed-request): handle errors.


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