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

# Create and edit filings

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

Complete the [authentication setup](/guides/managed-filings#authenticate).
Use a write-capable user key with MC edit access. The MC must already have
`filings`, `companies`, `jurisdictions`, and `products` registered; item operations
also need `filing_items`. An administrator can configure these in the Records UI.

## Find reference values

Find reference IDs through the existing
`GET /api/v1/mission-controls/{mcId}/records/reference-options?targetKind=system_record&recordType=companies`
API; repeat with `jurisdictions` and `products`. Follow that endpoint's pagination.

`toiCode` and `subToiCode` use NAIC registry values. A sub-TOI requires its parent TOI.
Discover choices with
`GET /api/v1/mission-controls/{mcId}/records/types/filings/fields/toiCode/options?limit=25&query=property`
and discover matching sub-TOIs with
`GET /api/v1/mission-controls/{mcId}/records/types/filings/fields/subToiCode/options?dependencyValue=01.0&limit=25`.
The options endpoint supports `query` to narrow the results. When changing a TOI,
change or clear an incompatible sub-TOI in the same request. PATCH checks the
resulting filing, including fields you leave unchanged.

## Create a filing

Create with `POST /api/v2/managed-filings` and `Content-Type: application/json`:

```json theme={null}
{
  "scope": "mc:your-mc-slug",
  "companyId": "<company UUID>",
  "jurisdictionId": "<jurisdiction UUID>",
  "primaryProductId": "<product UUID>",
  "filingType": "form",
  "description": "New forms filing"
}
```

Save this body as `filing.json`, using authorized reference IDs and an MC UUID
or stable slug after `mc:`. Send it with:

```bash theme={null}
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${EFFECTIVE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-binary @filing.json \
  "${EFFECTIVE_API_BASE_URL%/}/api/v2/managed-filings"
```

The response is `201`, includes the created filing and canonical scope, and supplies its detail URL in
`Location`. API-key creation does not start a Captain session.

## Edit a filing

Use `PATCH /api/v2/managed-filings/{filingId}` to change selected fields:

```json theme={null}
{ "description": "Updated filing", "effectiveFromNew": "2027-01-01" }
```

Omitted fields stay unchanged; null clears nullable values. Editors need both
MC and filing edit access. Imported/reference and unclassified filings cannot
be prepared. Scope, ownership, sharing, and filing mode cannot be edited here.

Create is not idempotent. After a lost response, [list filings](/guides/managed-filings/read-filings)
before retrying. Updates use last-write-wins semantics; read current values before editing.
These calls neither stage nor submit to SERFF.

Next, [upload and attach documents](/guides/managed-filings/manage-documents).
See [error recovery](/guides/managed-filings#recover-from-errors) for failed requests.


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