> ## 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 manage objections

> Record regulator requests, maintain response drafts, and discuss individual objection items.

Record an objection letter under a [managed filing](/guides/managed-filings/create-filings),
then add one item for each regulator request. These are workspace records, separate
from letters returned by [filing objection research](/guides/research-filing-objections).
Creating them does not contact the regulator, extract a letter, or start an agent.

Use your [user API key](/getting-started/authentication). Reads require access to
the parent filing and records; writes require edit access to a managed filing and
the affected record. Record IDs select the scope; no scope header is needed.

Set `FILING_ID` to a filing returned by [Read filings](/guides/managed-filings/read-filings)
or [Create and edit filings](/guides/managed-filings/create-filings). Save the IDs
returned below as `OBJECTION_ID` and `ITEM_ID`; all later examples use those same records.

## Record the letter

Use the workspace filing ID, not its regulatory catalog ID. Letter numbers (`seq`)
are positive integers, unique within the filing. The default status is `open`.

```bash theme={null}
curl --request POST \
  --url "https://api.effectiveai.app/api/v2/insurance/managed-filings/$FILING_ID/objections" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"seq":1,"receivedAt":"2026-10-16T00:00:00Z","reviewerName":"State reviewer","dueDate":"2026-11-16"}'
```

A `201` response returns the objection, including its `id`, `filingId`, `seq`, and
`status`. `Location` points to `/api/v2/objections/{id}`. Save that ID as
`OBJECTION_ID` for the following requests.

The objection represents the letter as a whole. Its items, created below, represent
the individual requests. `receivedAt` is a UTC timestamp; `dueDate` is a calendar
date. Optional `reviewerName` and `stateStatus` preserve the reviewer's name and
the regulator's status text. See [Create a workspace objection](/api-reference/objections/create-a-workspace-objection)
for the complete request and response.

## List and read objections

List recorded letters when discovering IDs or reconciling an uncertain create:

```bash theme={null}
curl --request GET \
  --url "https://api.effectiveai.app/api/v2/insurance/managed-filings/$FILING_ID/objections?limit=50" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

The response contains `objections` and `nextCursor`. Letters are ordered by number,
then ID. Continue with the same `limit` and the returned cursor until `nextCursor`
is null, as described in [Pagination](/getting-started/pagination). Lists are live;
renumbering or deleting records while paging can change the results.

Creation is not idempotent. After a timeout, inspect the list by letter number
before retrying. A duplicate number returns `409 conflict`.

Read the selected letter:

```bash theme={null}
curl --request GET \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

The response is the objection record, including its parent `filingId`, metadata,
and current status. To change metadata, PATCH only the fields you want to change:

```bash theme={null}
curl --request PATCH \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"dueDate":"2026-11-23"}'
```

A successful PATCH returns `200` with the updated objection. Its filing cannot be
changed through this endpoint.

## Add the regulator requests

Add each point as an item. Item numbers are unique within an objection; their
default status is `open`. Triage uses `text` as the regulator's request.

```bash theme={null}
curl --request POST \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"seq":1,"text":"Please clarify the scope of the proposed exclusion and provide revised wording."}'
```

A `201` response includes the item `id`, `objectionId`, `text`, `responseText`, and
`status`; `responseText` is initially null. Save the ID as `ITEM_ID`. `Location`
points to `/api/v2/objections/{id}/items/{itemId}`.

```bash theme={null}
curl --request GET \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items?limit=50" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

The response contains `items` and `nextCursor`, ordered by item number then ID.
Use the same pagination and create-recovery approach as letters. Read an item's
current state at `/objections/{id}/items/{itemId}`. An item cannot be moved to
another objection; a wrong-parent ID returns `404 not_found`.

```bash theme={null}
curl --request GET \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items/$ITEM_ID" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

Keep the regulator's original request in `text` and your proposed answer in
`responseText`. If a request cites a submitted document, optional `submissionItemId`
must identify a recorded submission item from the same filing. It is not a filing
item or file ID. See [Create an objection item](/api-reference/objections/create-an-objection-item)
for all fields.

Once the requests and filing evidence are ready, [run triage](/guides/managed-filings/objection-triage).

## Read recommendations and reply

Triage saves recommendations in the item discussion. Use the `itemId` from triage
progress to list its comments:

```bash theme={null}
curl --request GET \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items/$ITEM_ID/comments?limit=50" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

The response contains `comments` and `nextCursor`. Entries are oldest first and
include messages, replies, and events. Group by `threadId`; a discussion can span
pages. A single entry is available at
`/objections/{id}/items/{itemId}/comments/{commentId}`. Add `status=open` or
`status=resolved` to filter discussions, keeping the same filter on later pages.

Set `ROOT_COMMENT_ID` to a top-level recommendation message's `id`, not its
`threadId`, then reply:

```bash theme={null}
curl --request POST \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items/$ITEM_ID/comments" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"body\":\"Use the narrower exclusion; the revised wording is attached to the filing.\",\"parentCommentId\":\"$ROOT_COMMENT_ID\"}"
```

Omit `parentCommentId` to start a new discussion. Replies must address a root
message in this item. A saved reply does not notify the filing agent or start a
fix. Comment creation is not idempotent: inspect the timeline before retrying
an uncertain request.

PATCH the comment URL with either `body` to edit your own message, or `status`
(`open` or `resolved`) to change the discussion state. Do not send both.

## Save a response draft

Save a proposed answer while work is still in progress:

```bash theme={null}
curl --request PATCH \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items/$ITEM_ID" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"responseText":"We propose narrowing the exclusion to the stated exposure.","status":"in_progress"}'
```

A `200` response returns the updated item. After applying and verifying the change,
save the final answer and mark the item resolved:

```bash theme={null}
curl --request PATCH \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items/$ITEM_ID" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"responseText":"We have narrowed the exclusion to the stated exposure and updated the proposed wording.","status":"resolved"}'
```

Item status is `open`, `in_progress`, or `resolved`. Saving `responseText` alone
leaves status unchanged. Resolving a discussion does not resolve an item, and
resolving an item does not mean the regulator accepted the response.

PATCH `/objections/{id}` to edit letter metadata. The letter has its own `open`
or `answered` status: marking it answered requires `answeredBySubmissionId` from
the same filing. Reopening requires setting that reference to null. Letter and
item status changes do not submit anything to SERFF.

PATCH updates supplied fields; omitted fields stay unchanged and null clears
nullable fields. Read current values before retrying an uncertain PATCH, since
another editor may have changed them.

## Remove an item or objection

Remove an item entered by mistake:

```bash theme={null}
curl --request DELETE \
  --url "https://api.effectiveai.app/api/v2/objections/$OBJECTION_ID/items/$ITEM_ID" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

To remove a letter instead, use `DELETE /api/v2/objections/{id}`. Deletion returns
`204` with no body and requires manage permission and managed filing edit access.
An objection with dependent items cannot be removed; dependencies return `409`.
An already removed record returns `404`. SERFF records are unaffected.


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