> ## 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. # Research a carrier, group, or MGA > Resolve directory identities, select filing filters, and keep company and group evidence distinct. This guide answers questions like “Which Texas homeowners filings did this carrier submit during 2025?” Follow [connection setup](/guides/index#connect-once) first. ## Find the carrier Search by name or alias with [List carriers](/api-reference/carriers/list-carriers): ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/carriers?name=Travelers&limit=20" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` ```json Response (first two carriers) theme={null} { "carriers": [ { "id": "carrier_N1WF3AR", "identifiers": [{ "scheme": "naic_company", "value": "40282" }], "name": "TRAVELERS COMMERCIAL CASUALTY COMPANY", "group": { "id": "carrier_group_25KQ2ZH", "name": "Travelers Grp" }, "domicile": "CT", "status": "active", "grossPremiumWritten": { "year": 2025, "amount": 258362326 }, "cessionRatio": { "year": 2025, "value": 0.2848 } }, { "id": "carrier_5WQJYEC", "identifiers": [{ "scheme": "naic_company", "value": "19038" }], "name": "TRAVELERS CASUALTY AND SURETY COMPANY", "group": { "id": "carrier_group_25KQ2ZH", "name": "Travelers Grp" }, "domicile": "CT", "status": "active", "grossPremiumWritten": { "year": 2025, "amount": 8531314319 }, "cessionRatio": { "year": 2025, "value": 0.0633 } } ], "nextCursor": null } ``` A brand can match several legal entities. Compare the names and groups, follow `nextCursor` if needed, and pick the entity your question is about. For homeowners in Texas, that's Travelers Personal Insurance Company. Get its aliases, group members, and MGAs: ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/carriers/carrier_BYAQZJV" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` ```json Response (abbreviated) theme={null} { "id": "carrier_BYAQZJV", "identifiers": [{ "scheme": "naic_company", "value": "38130" }], "name": "TRAVELERS PERSONAL INSURANCE COMPANY", "group": { "id": "carrier_group_25KQ2ZH", "name": "Travelers Grp" }, "domicile": "CT", "status": "active", "aliases": [], "groupMembers": [{ "id": "carrier_9B86YGE", "name": "AMERICAN EQUITY INSURANCE COMPANY" }], "mgas": [] } ``` Directory IDs look like `carrier_…`, `carrier_group_…`, and `mga_…`. External identifiers such as NAIC codes are in the `identifiers` array. Some directory entries have no NAIC code; their relationships still work, but they can't be used as filing filters, which need a NAIC code. If you know the NAIC code, look it up directly: ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/carriers?identifier=naic_company:38970" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` Filings reference the same IDs in `carrierIds` and `groupId`, so you can use a carrier ID as a filing filter and compare it with filing results. The source NAIC codes are in `naicCompanyCodes` (five-digit strings) and `naicGroupCode` (no leading zeros). `carrierIds` only includes carriers matched to the directory, so it can be empty even when NAIC codes are present, and it's `null` when the source has no codes. A `null` `groupId` means the group is missing or unmatched. Merged carriers resolve to the surviving ID, and filing filters use that carrier's current NAIC code. A filing filter on a carrier or group that matches no catalog identifier returns 404. Look up the carrier again. The carrier `state` and `toi` filters reflect SERFF activity in the last 12 months, and a carrier's domicile isn't the state it files in. For older activity, find the carrier first, then put dates on the filing query. ## Start from a carrier group If the question is about a whole group, such as Travelers Grp (`carrier_group_25KQ2ZH`), find it with [List carrier groups](/api-reference/carrier-groups/list-carrier-groups): ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/carrier-groups?name=Travelers&limit=20" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/carrier-groups/carrier_group_25KQ2ZH" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/carriers?group=carrier_group_25KQ2ZH&limit=20" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` Groups have a managed `id`, a `name`, and registered `identifiers`. To look up a NAIC group code exactly, use `identifier=naic_group:785`, keeping any padding in the registered value. The detail path takes a managed ID, not a NAIC code. List the group's carriers with the carrier list's `group` filter. Groups are sorted by name, then ID. To paginate, send `nextCursor` with the same filters and `limit`; cursors expire after 24 hours. On `invalid_cursor`, start again without a cursor. Pass the group ID as the filing `group` filter. That's a broader question than one carrier, so don't switch to the group just because the carrier query returned few results. Not every filing in a group belongs to the same program or product. ## Find the carrier's filings Texas homeowners (TOI `04.0`) filings submitted in 2025: ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/filings?carrier=carrier_BYAQZJV&state=TX&toi=04.0&submissionDateFrom=2025-01-01&submissionDateTo=2025-12-31" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` ```json Response (first filing, abbreviated) theme={null} { "filings": [ { "id": "7c9aacbe-1f5d-42cf-9fe8-0c8fa8f26779", "source": "serff", "sourceReference": "TRVD-G134775768", "state": "TX", "companyName": "The Travelers Home and Marine Insurance Company", "naicCompanyCodes": ["27998", "36137", "38130"], "carrierIds": ["carrier_08H5W4H", "carrier_BYAQZJV", "carrier_RAHCJJM"], "groupId": "carrier_group_25KQ2ZH", "productName": "Quantum Homeowners 2.0, Quantum Homeowners and Quantum High Value Homeowners", "toiCode": "04.0", "filingTypeNormalized": "RATE_RULE", "normalizedOutcome": "FILED", "submissionDate": "2025-12-24", "dispositionDate": "2026-07-09" } ], "nextCursor": "v1.zFS306mpf_iYLGUyX-nlm0TTKqeHYSGvIfFlVPZrgKw" } ``` Page through results as described in [pagination and recovery](/guides/pagination-and-recovery). If you broaden the query (another carrier, state, or date range), keep those results separate. A filing's `companyName` can be a different company in the same filing while `carrierIds` still includes your carrier, as in the example above. In a multi-company filing, the rate impact covers all companies, not just yours. Carrier financials in the directory are company-wide annual figures, not filing-level ones. ## Start from an MGA Search by name or alias: ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/mgas?name=AEGIS&limit=20" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` [Get the MGA](/api-reference/mgas/get-an-mga) to see the carriers that back it, with each link's role and source notes. Use those carrier IDs to find filings as above. Not every filing by a backing carrier belongs to the MGA, so check filing descriptions and documents for the program or MGA name. There's no `mga` filter on filings. ## Report the answer [Get each filing's detail](/api-reference/filings/get-a-catalog-filing), then its [forms and rate impact](/guides/filing-research-data) or [source documents](/guides/read-filing-documents). In your answer, include the carrier and date range you chose, the native filing references, and what you read. If you stopped before the last page, say so. ## Find related catalog products Use the carrier group ID to discover products, optionally filtering by a configured state: ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/products?group=carrier_group_25KQ2ZH&state=CA&limit=20" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` ```json Response (first product, states abbreviated) theme={null} { "products": [ { "id": "product_SYAPWB1", "name": "CyberFirst Essentials", "type": "cyber", "admitted": true, "group": { "id": "carrier_group_25KQ2ZH", "name": "Travelers Grp" }, "mga": null, "availabilitySummary": { "states": ["AL", "AR", "CA", "CO", "CT"], "stateCount": 41 } } ], "nextCursor": null } ``` Each result includes its identity and `availabilitySummary` with all configured states and their count. The summary includes states beyond the filter; configured availability does not establish that the product is currently sold there. Read a selected product for state-specific writing companies and comparison claims: ```bash theme={null} curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/products/product_SYAPWB1" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" curl --fail-with-body --silent --show-error \ "https://canary.effectiveai.app/api/v2/insurance/products/product_SYAPWB1/availability/CA/filings" \ --header "Authorization: Bearer $EFFECTIVE_API_KEY" ``` Comparison claims retain qualifications and scope. Public citations are included where available; `kind: "unavailable"` with `reason: "internal_source"` means the claim's evidence cannot be retrieved through this API. Treat those claims as unverified and consult the recorded filings and their files for source material. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.