Skip to main content
Complete the authentication setup. Use a write-capable user key with MC and filing edit access. The MC must have filing_items registered. Set FILING_ID to the ID of your managed filing. The shell examples use Bash, curl, and jq.

​
Choose the upload location and owner

Read GET /api/v2/managed-filings/{filingId}. Set FILING_SCOPE to the returned scope, including its mc: prefix. Use it to initialize uploads for this filing. To match the native filing Documents tab, use:
  • targetUri: "@mc/Documents": the Documents folder in the selected MC.
  • scope: "mc:<MC UUID or stable slug>": selects the MC for @mc in v2.
  • ownerType: "records.filings" and ownerId: <filing UUID> on each uploaded file: associates the artifact with the filing record.
Use these values for new filing documents instead of a personal Vault folder. The upload API calls the record relationship ownerType/ownerId, not parentType. The server derives the artifact’s folder parentId from targetUri; do not put the filing ID in that field. The general upload API also supports non-MC destinations. Send scope only for @mc destinations. V2 uploads do not use an MC header; completion uses the destination captured in the upload token.

​
Upload a document

Save this filing-specific request as upload-request.json:
Follow the shared Vault upload steps using this request and form.pdf:
  1. POST /api/v2/files/uploads: initialize the upload.
  2. PUT the bytes to the returned signed URL.
  3. POST /api/v2/files/uploads/complete: confirm the upload and save the successful result’s artifact.id and artifact.name.
Then add that artifact to a filing item below. The Vault guide covers returned headers, partial failures, expiry, and retry behavior. Repeat this flow for related documents such as redlines. Give each new file the same filing owner. Filing-owned uploads can appear in the native Documents tab without a schedule assignment. Uploading a file does not create a filing item.

​
Add a filing item

Call POST /api/v2/managed-filings/{filingId}/items with Content-Type: application/json and the uploaded artifact IDs:
Use artifactId and artifactName from the same successful completion result (artifact.id and artifact.name). Do not reuse the requested filename: Vault may rename redline.pdf to redline (1).pdf when a file with that name exists. The 201 response contains the created item. Save its id for updates. Omit attachments when there are no related documents. Omit both schedule fields to add preparation notes or other unscheduled working items. The artifact’s owner identifies its record relationship. The filing item stores the working document reference and any schedule position. Adding an item is not a substitute for setting the upload location and owner. Existing documents may belong to another record, such as a form edition. They can be referenced without changing their owner if the caller has the required access. The server checks access to every attached file. Working attachments follow the file’s current content; submission recording pins versions later.

​
List filing items

Use GET /api/v2/managed-filings/{filingId}/items?limit=50. The response contains items and nextCursor. Follow nextCursor with the same filing and limit until null. Item cursors expire after 24 hours. This lists filing items, not every filing-owned Vault document. Reading an item does not itself grant permission to read its file bytes.

​
Update or remove an item

  • PATCH /api/v2/managed-filings/{filingId}/items/{itemId}: send a new artifactId to replace the working file reference. Send both schedule fields as null to remove an assignment, or both values to assign a position. Updating an item does not change retained submission contents.
  • DELETE /api/v2/managed-filings/{filingId}/items/{itemId}: remove the item. Returns 204, retains file bytes, and rejects removal when dependencies require the item. A repeated delete returns 404.
Add requests are not idempotent. After a lost response, inspect the item list before retrying. Updates use last-write-wins semantics; read current values before editing. These calls neither stage nor submit to SERFF. Next, comment on the filing or a document version. See error recovery for failed requests.