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

# Create and edit filings

> Create a filing in an authorized scope and update its details.

Complete the [authentication setup](/guides/managed-filings#authenticate). You need a write-capable
user key with edit access to the filing's scope. An administrator must provide the scope
(`mc:<UUID or slug>`) and turn on filing preparation there.

A filing references these records, all in the same `scope`:

| Field | Required | Where to get it |
| - | - | - |
| `companyId` | Yes | Companies, below |
| `jurisdictionId` | Yes | Jurisdictions, below |
| `primaryProductId` | Yes | Products, below |
| `additionalProductIds` | No | Products, below; don't repeat the primary product |
| `predecessorFilingId` | No | [List filings](/guides/managed-filings/read-filings) in the same scope |

The company also needs a domicile jurisdiction, from the same jurisdictions API. TOI and sub-TOI codes
come from the insurance types API below.

## Find or create a jurisdiction

Look for the jurisdiction in the scope you'll create the filing in:

```http theme={null}
GET /api/v2/insurance/managed-filings/jurisdictions?scope=mc:your-scope-slug&code=CA
```

The response contains `jurisdictions` and `nextCursor`. Save the matching `id`. If there's no match,
create it:

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

{ "scope": "mc:your-scope-slug", "code": "CA", "name": "California" }
```

The response is `201` with `{ id, code, name }`. Codes are uppercase and unique within the scope. If
someone else creates the same code first, you get `409`; list by code again to get its ID.

## Find or create a company

```http theme={null}
GET /api/v2/insurance/managed-filings/companies?scope=mc:your-scope-slug&naicCompanyCode=00987
```

The response contains `companies` and `nextCursor`. You can also search by `name`. If the company
isn't there, create it with its domicile jurisdiction:

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

{
  "scope": "mc:your-scope-slug",
  "name": "Example Insurance",
  "naicCompanyCode": "00987",
  "domicileJurisdictionId": "<domicile jurisdiction UUID>"
}
```

Save the returned `id`. The domicile can differ from the filing's jurisdiction. Keep leading zeros in
NAIC codes. Names and NAIC codes aren't unique, so check the matches before creating a company.
Catalog carrier IDs can't be used here.

## Find or create a product

```http theme={null}
GET /api/v2/insurance/managed-filings/products?scope=mc:your-scope-slug&name=Commercial%20Property
```

The response contains `products` and `nextCursor`. These are your workspace's products, with
different IDs from the catalog at `/api/v2/insurance/products`. If the product isn't there:

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

{ "scope": "mc:your-scope-slug", "name": "Commercial Property" }
```

Save the returned `id`. New products default to `lifecycleStatus: "draft"` and `admitted: true`.
Product names aren't unique.

All three lists accept `name` (case-insensitive substring) and `limit` (1 to 100, default 50). Pass the returned
`nextCursor` as `cursor` with the same scope, filters, and `limit` until it's null. These cursors expire two
minutes after the first page; on `invalid_cursor`, start the search again.

For example, continue the jurisdiction search with:

```http theme={null}
GET /api/v2/insurance/managed-filings/jurisdictions?scope=mc:your-scope-slug&code=CA&limit=50&cursor={nextCursor}
```

URL-encode the cursor value. The reference pages define all fields for
[companies](/api-reference/companies/create-a-company-for-filing-preparation),
[jurisdictions](/api-reference/jurisdictions/create-a-jurisdiction-for-filing-preparation), and
[products](/api-reference/managed-products/create-a-product-for-filing-preparation).

Read-only keys can use the lists; creating needs edit access. The create calls aren't idempotent, so
after an uncertain response, search again before retrying.

For `predecessorFilingId`, pick a filing from the workspace filing list in the same scope; catalog
filing IDs don't work. Omit it if there's no predecessor.

## Choose insurance type codes

Get the supported NAIC types of insurance (TOIs):

```http theme={null}
GET /api/v2/insurance/insurance-types
```

The response contains `insuranceTypes`, each with `code`, `name`, and `description`. Use the chosen
`code` as `toiCode`, then get its subtypes:

```http theme={null}
GET /api/v2/insurance/insurance-types/01.0/subtypes
```

The response contains `subtypes` with the same fields. Use the chosen `code` as `subToiCode`. Both
calls return the full list.

A sub-TOI must belong to its TOI. When you change the TOI, change or clear the sub-TOI in the same
request. PATCH validates the whole resulting filing, including fields you didn't send.

## Create a filing

See [Create a filing](/api-reference/managed-filings/create-a-filing) for all optional fields.

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

{
  "scope": "mc:your-mc-slug",
  "companyId": "e1e00b65-30bf-4d1a-8b2c-65c21db8a094",
  "jurisdictionId": "20b7747e-d64b-4a6a-9776-37e6723b79c0",
  "primaryProductId": "6ac87c3f-c4d8-49c9-8dd8-e1c450f30fc5",
  "filingType": "form",
  "description": "New forms filing"
}
```

The IDs below and in the other filing guides are illustrative. Replace them with
the IDs returned by your requests. Use authorized reference IDs and an MC UUID
or stable slug after `mc:`.

Example `201` response:

```http theme={null}
HTTP/1.1 201 Created
Location: /api/v2/insurance/managed-filings/3c930b43-06d4-4c77-80c8-68c647a50710
```

```json theme={null}
{
  "id": "3c930b43-06d4-4c77-80c8-68c647a50710",
  "scope": "mc:8f176dde-0651-44bd-82cf-2cde654bafcb",
  "displayName": "3c930b43-06d4-4c77-80c8-68c647a50710",
  "filingMode": "managed",
  "companyId": "e1e00b65-30bf-4d1a-8b2c-65c21db8a094",
  "jurisdictionId": "20b7747e-d64b-4a6a-9776-37e6723b79c0",
  "primaryProductId": "6ac87c3f-c4d8-49c9-8dd8-e1c450f30fc5",
  "filingType": "form",
  "description": "New forms filing",
  "serffTrackingNumber": null,
  "stateTrackingNumber": null,
  "companyTrackingNumber": null,
  "createdAt": "2026-10-07T16:00:00.000Z",
  "updatedAt": "2026-10-07T16:00:00.000Z",
  "additionalProductIds": [],
  "predecessorFilingId": null,
  "reviewType": null,
  "toiCode": null,
  "subToiCode": null,
  "disposition": null,
  "dispositionDate": null,
  "effectiveFromNew": null,
  "effectiveFromRenewal": null,
  "permissions": {
    "read": true,
    "edit": true,
    "manageAccess": true
  }
}
```

Save `id` as `{filingId}` for the following calls. The response uses the canonical
MC UUID in `scope`, even when the request used a slug. API-key creation does not
start an agent session.

## Edit a filing

```http theme={null}
PATCH /api/v2/insurance/managed-filings/{filingId}
Content-Type: application/json

{ "description": "Updated filing", "effectiveFromNew": "2027-01-01" }
```

Omitted fields stay the same; `null` clears a nullable field. You need edit access to both the
scope and the filing. Reference and unclassified filings can't be edited, and neither can
scope, ownership, sharing, or filing mode.

A successful PATCH returns `200` with the full updated filing, in the same shape as
the create response. `effectiveFromNew` applies to new business;
`effectiveFromRenewal` applies to renewals. `reviewType` is the regulatory review
procedure, not an automated review request. See [Edit working filing details](/api-reference/managed-filings/edit-working-filing-details) for the
allowed values and definitions.

Create is not idempotent. After a lost response, [list filings](/guides/managed-filings/read-filings)
and inspect candidates by scope, reference IDs, description, and creation time. The list
has no search filters or request-key lookup, and these fields are not unique.
If you cannot identify the result confidently, stop automatic retries and reconcile
it in the filing workspace. Updates use last-write-wins semantics; read current
values before editing, including before retrying an uncertain update.
These calls neither stage nor submit to SERFF.

Next, [upload and attach documents](/guides/managed-filings/manage-documents). For errors, see
[error recovery](/guides/managed-filings#recover-from-errors).


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