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

# Read carrier state licensing

> Read dated Schedule T status observations for a carrier’s US states and territories.

Use these endpoints to inspect a carrier’s reported year-end licensing status.
They require your organization’s NAIC dataset access. Contact support to enable
it after accepting the NAIC terms; the API does not enable access itself.

## Choose the carrier and year

Start with a carrier ID from `GET /insurance/carriers`. A five-digit NAIC company
code is also accepted; the response returns the canonical managed carrier ID.

Set `EFFECTIVE_API_KEY` to your user API key, then request California for a specific
statement year:

```bash theme={null}
curl --request GET \
  --url "https://api.canary.effectiveai.app/api/v2/insurance/carriers/19682/state-licenses?year=2025&state=CA" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

Expected response for the reported California observation:

```json theme={null}
{
  "year": 2025,
  "stateLicenses": [
    {
      "id": "nsl1.WyIxOTY4MiIsMjAyNSwiQ0EiXQ",
      "carrier": {
        "id": "carrier_SD0SC8Y",
        "name": "HARTFORD FIRE INSURANCE COMPANY"
      },
      "naicCompanyCode": "19682",
      "year": 2025,
      "state": "CA",
      "stateName": "California",
      "status": {
        "code": "L",
        "label": "Licensed or chartered"
      },
      "sources": [
        {
          "exhibit": "Schedule T",
          "statementYear": 2025
        }
      ]
    }
  ],
  "nextCursor": null,
  "sources": [
    {
      "exhibit": "Schedule T",
      "statementYear": 2025
    }
  ]
}
```

Omit `state` to read all reported US states and territories. Omit `year` to select
the carrier’s latest loaded Schedule T jurisdiction year. The response includes
that year and a `stateLicenses` array. Each observation includes:

* `id`: pass unchanged to the item endpoint under the same carrier.
* `naicCompanyCode`: the source company, separate from the managed carrier ID.
* `state`, `stateName` and `year`: where and when the status was reported.
* `status.code` and `status.label`: reported status and its explanation.
* `sources`: Schedule T and the statement year.

Copy `stateLicenses[].id` from your response into the item URL. For the observation
above, the request is:

```bash theme={null}
curl --request GET \
  --url "https://api.canary.effectiveai.app/api/v2/insurance/carriers/19682/state-licenses/nsl1.WyIxOTY4MiIsMjAyNSwiQ0EiXQ" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

Expected response (abbreviated):

```json theme={null}
{
  "id": "nsl1.WyIxOTY4MiIsMjAyNSwiQ0EiXQ",
  "naicCompanyCode": "19682",
  "year": 2025,
  "state": "CA",
  "status": {
    "code": "L",
    "label": "Licensed or chartered"
  }
}
```

The item has the same shape as its list entry. A directory carrier that resolves
to multiple source companies can return separate statuses for the same state.
They are not combined into one admission flag.

## Interpret the status

| Code | Meaning |
| - | - |
| L | Licensed or chartered |
| R | Registered risk retention group |
| E | Eligible surplus lines insurer |
| Q | Qualified or accredited reinsurer |
| D | Domestic surplus lines insurer |
| N | None of those statuses |
| S | Suspended |
| O | Other |

Codes may differ across statement years. New codes are preserved with a null
label. A null code means unreported; it does not mean N. See [NAIC’s Schedule T
status definitions](https://content.naic.org/cmte_e_app_blanks_related_editorial_rev.htm)
and [subsequent adopted changes](https://content.naic.org/cmte_e_app_blanks_related_adopted_mods.htm).

These are historical carrier observations, **not current license verification or
proof that a particular product is admitted**. Canada, other foreign aggregates
and totals are excluded. Schedule T Part 2 and premium/loss amounts are not returned.

## Continue and recover

Lists default to 50 observations; `limit` accepts 1–200. Follow `nextCursor` with
the same filters and limit. An omitted year stays pinned during traversal.
Cursors expire after 24 hours; restart without the cursor after `invalid_cursor`.
Imported values can change between calls; this is not a frozen snapshot.

* `dataset_not_enabled` (403): request NAIC access from support.
* `statutory_data_not_found` (404): no loaded jurisdiction observations for that
  carrier/year. This does not prove the carrier failed to file or has no license.
* Empty `stateLicenses`: coverage exists, but the requested state has no matching observation.
* Item `not_found` (404): the observation was removed, is unavailable, or belongs
  to another carrier. Return to the collection to discover current items.

A nonempty call costs $0.02 plus $0.05 per returned observation. One item costs
$0.07; a 50-row page costs $2.52. Errors and empty results are free. Repeating a
successful read incurs another charge. API and MCP use the same prices.


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