JSON API - Hearing Attachment Reference

This page documents the attachment endpoints for hearings created via the JSON REST API. It is a companion to JSON API - Hearing Create Payload Reference and JSON API - Hearing Response Reference. Attachments are not part of the hearing creation payload — you upload them after the hearing exists.

All requests require an Authorization header (HTTP Basic, or an OAuth2 Bearer token with the scope noted per endpoint) — see the API page for authentication details.

Endpoint and behavior details below are confirmed directly against HearingResource.java and HearingServiceImpl.java — not reverse-engineered from the API Explorer.

Endpoints

Method	Endpoint	Scope	What it does

Method	Endpoint	Scope	What it does
POST	`/hearings/v1/hearing/{hearingId}/attachment`	`hearings:write`	Upload a file to a hearing
GET	`/hearings/v1/hearing/attachment/{attachmentId}`	`hearings:read`	Download an attachment's contents
DELETE	`/hearings/v1/hearing/attachment/{attachmentId}`	`hearings:write`	Delete an attachment

{hearingId} is the hearing's 32-character id (the id returned when you create the hearing). {attachmentId} is the attachment's 32-character id, returned in the upload response and in the attachments array of the hearing response. There is no endpoint that lists a hearing's attachments — to enumerate them, GET the hearing and read its attachments array (see JSON API - Hearing Response Reference).

Upload — POST /hearings/v1/hearing/{hearingId}/attachment

This is a POST, not a PUT. Send the file as multipart/form-data. Do not use PUT on the hearing to add documents.

Content-Type: multipart/form-data (your HTTP client must generate the multipart boundary; do not set the header by hand without one).

Form parts

Part	Required	Type	Notes

Part	Required	Type	Notes
`uploadedFile`	Yes	file	The file to upload. Must be a multipart part named exactly `uploadedFile`.
`fileName`	No	string (max 255)	Overrides the stored attachment name. Send it as a plain text form field — not a file — and note the field name is case-sensitive (exactly `fileName`). Must include the extension (e.g. `motion.pdf`). Must be unique per hearing — see constraints below. If omitted, the name is taken from the uploaded file.

Accepted files

Any file type is accepted — there is no allowlist. A file named .pdf is validated: a corrupt or unreadable PDF (PdfInvalidException) or an encrypted PDF (PdfEncryptionException) is rejected. Other file types are stored as-is.
A file uploaded without an extension that parses as a PDF has .pdf appended automatically; otherwise always include the extension in fileName.
Maximum file size is 16 MB.
One file per request. To attach several files, send several requests — or upload a .zip, whose entries are each added as separate attachments (subject to the constraints below).

Success — 200 OK. Returns a HearingAttachmentResponse:

Field	Type	Notes

Field	Type	Notes
`id`	String	32-character unique identifier of the attachment.
`description`	String	The stored file name.
`length`	Integer	Size in bytes.
`lengthText`	String	Human-friendly size.
`category`	Object	The document category. Auto-assigned only when the file name matches a recognized pattern (e.g. `_POS_` → Proof of Service, `_DONS_` → Proof of Non-Service, `_CONF_` → Filing); otherwise it comes back `(Unknown)`. Not settable via this endpoint — in the Docketly app it's a dropdown that can be set manually from the full list of document types.

Constraints & behavior

A 400 Bad Request is returned (with an ErrorResponse body — see below) when any of these apply:

Duplicate file name. File names must be unique per hearing, compared case-insensitively (Motion.pdf and motion.pdf collide). A duplicate is rejected — the existing file is not overwritten and the new one is not auto-renamed. The error body's original field carries the ID of the existing attachment it collided with. (Note: the match is on the name, not the file contents — two different files sent under the same name will collide.)
Past hearing. Uploads are blocked once the hearing's scheduled time is more than 12 hours in the past.
Canceled hearing. Uploads to a canceled hearing are rejected.
Empty file, an unreadable or encrypted PDF, or a file failing the virus scan are also rejected with a 400.

Attorney-role tokens cannot upload attachments (returns 401). Uploads must use a client/privileged account.

Download — GET /hearings/v1/hearing/attachment/{attachmentId}

Returns the raw file bytes (application/octet-stream) with a Content-Disposition header naming the file. Requires hearings:read scope and access to the owning hearing. A request for an attachment ID that does not exist returns 204 No Content.

Note: if you pass a 6-character hearing locator here instead of a 32-character attachment ID, this endpoint returns a generated docket PDF for the hearing rather than a stored attachment.

Delete — DELETE /hearings/v1/hearing/attachment/{attachmentId}

Deletes are permanent — there is no recovery.

Deletion is only allowed when both are true:

The requesting account is not an attorney-role token, and
The hearing's scheduled date has not yet passed.

If either fails, the request returns 403 Forbidden. A missing attachment returns 404.

Replacing a document (revision): because a duplicate file name is rejected, the pattern to replace a file under the same name is: DELETE the existing attachment (its ID is in the original field of the duplicate error, or in the hearing's attachments array), then re-POST the new file. As deletes are permanent, confirm the new upload succeeds. This only works before the hearing date.

Error responses

All attachment validation failures return 400 Bad Request with an ErrorResponse body. The HTTP status alone does not distinguish the reason — read the body. (Note: a wrong HTTP method returns 405, not 400.)

Field	Type	Notes

Field	Type	Notes
`success`	Boolean	Always `false` on errors.
`message`	String	Human-readable explanation, safe to surface to a user.
`exception`	String	Stable identifier for programmatic branching (see below).
`original`	String	Duplicate errors only — the ID of the existing attachment that caused the collision.
`file`	String	The file name that was rejected.

Exception keys

`exception`	`message`

`exception`	`message`
`DuplicateAttachmentException`	An attachment with this same file name or content already exists.
`PastHearingAttachmentException`	Attachments cannot be added to hearings that occurred in the past.
`HearingCanceledAttachmentException`	This hearing has been canceled so attachments cannot be added.
`EmptyFileException`	This file could not be used as an attachment because it is empty. Please check your file and try again. Contact us for more information.
`PdfInvalidException`	This file could not be used as an attachment because it is an invalid PDF. It may be corrupt, a different file type, or contain text. Please check your file and try again. Contact us for more information.
`PdfEncryptionException`	This file could not be used as an attachment because it has an unsupported PDF encryption applied. Please check your file and do not encrypt if possible. Contact us for more information.
`VirusDetectedException`	The file could not be used as an attachment because it has a virus. Please update your anti-virus software and scan the file. Contact us for more information.

Other status codes: 401 (invalid credentials, or a role not permitted to upload/delete), 403 (not permitted to access the hearing), 404 (hearing not found, or attachment not found on delete).

Endpoint and field details confirmed against HearingResource.java and HearingServiceImpl.java. Last reviewed July 2026.