FILING_ID to a filing returned by Read filings
or Create and edit 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.
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
for the complete request and response.
List and read objections
List recorded letters when discovering IDs or reconciling an uncertain create: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. 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:
filingId, metadata,
and current status. To change metadata, PATCH only the fields you want to change:
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 isopen. Triage uses text as the regulator’s request.
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}.
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.
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
for all fields.
Once the requests and filing evidence are ready, run triage.
Read recommendations and reply
Triage saves recommendations in the item discussion. Use theitemId from triage
progress to list its comments:
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:
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:200 response returns the updated item. After applying and verifying the change,
save the final answer and mark the item resolved:
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: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.