JSON API - Hearing Create Payload Reference

This page documents field-level details for creating a hearing via the JSON REST endpoint POST /hearings/v1/hearing.

This is not the same schema as the EDI - Hearing Create page. That page documents our CSV bulk-import mechanism. Field availability, date formats, and a few field types differ between the two — if you're calling the JSON API directly (as most integrations do), use this page instead.

This page covers what you send. For what you get back after creating a hearing, see JSON API - Hearing Response Reference.

Field list below is confirmed directly against HearingRequest.java, the DTO class backing this endpoint — not reverse-engineered from screenshots. 46 fields total (39 String, 7 Boolean). The "Required" column is carried over from the EDI doc's field list (including its * = conditionally required legend) where the field exists there — see that page for the full conditional-requirement details on date/time, county, and caseName.

Full field reference

Notes & gotchas

Identity & party fields

• attorney — attorney of record. Informational only; does not affect who covers the hearing.

• attorneySelectedEmail — only used if you're auto-assigning an already-provisioned in-house attorney by email.

• contact / contactPhone — the day-of person to call if there's an issue. Defaults to whoever's calling the API if left blank.

• caseName — the full case caption, e.g. "Plaintiff vs. Defendant". There is no separate plaintiff/defendant name field in the JSON payload — this is by design, not a missing field.

• clientName — the display name of the party you represent (e.g. "Portfolio Recovery Associates, LLC").

• clientId — Docketly's internal identifier for the client account the hearing should be associated with. A long alphanumeric string we assign, similar in format to serviceId. Most integrations won't need to set this explicitly.

• isPlaintiff (Boolean) — flags which side clientName is on.

Date fields

• date — use yyyy-MM-dd HH:mm:ss: 4-digit year, 24-hour clock, zero-padded month/day/hour. Example: 2026-02-01 09:00:00. The parser accepts a few other formats (including the MM/dd/yy H:mm style used in the CSV import doc), but standardize on this one — it's unambiguous. Also send zone (e.g. America/Chicago) if you can; if omitted, we infer the timezone from the county/court, which isn't always what you'd expect.

• dateAnswered / dateComplaintFiled / dateDefaulted / dateServed — a stricter, date-only parser applies here, different from date. These accept only yyyy-MM-dd or MM/dd/yy — no time component, interpreted as UTC. A time component will be rejected. Standardize on yyyy-MM-dd (e.g. 2026-02-01). Do not use the date field's yyyy-MM-dd HH:mm:ss format here.

Decimal fields

Applies to balance, interest, principal, attorneyCosts, courtCosts, miscCosts — all typed String on the DTO. Send as a JSON string in plain decimal notation, e.g. "balance": "1234.56". Do not include currency symbols or thousands separators (no $1,234.56).

Settlement authority (SIF) fields

Applies to sifPercentage and sifMonths. These set per-hearing settlement authority that's shown to the covering attorney: sifPercentage is the "SIF Amount" (the settle-in-full amount as a whole-number percentage, 0–100 inclusive) and sifMonths is the "SIF Timeframe" (a whole number of months, 0 or greater). Both are optional. Like the decimal fields they are typed String on the DTO, but send whole numbers with no decimal point, e.g. "sifPercentage": "65", "sifMonths": "12". A value with a decimal point, a non-numeric value, a percentage outside 0–100, or a negative month count is rejected with an HTTP 400 error and the hearing is not created.

If your account already adds a default settlement authority automatically (through your "Automatically Add" Hearing Instruction rules — including rules scoped to a specific creditor), a value you send here overrides that default for this hearing. Omit a field to fall back to your standing default. The two fields are independent — you can override one and let the other fall back. The same fields and behavior apply on the update (PUT) call and on the create_hearing API tool.

opposingCounsel

Typed String on this endpoint — the opposing counsel's name/info. This differs from the EDI/CSV doc, which types opposingCounsel as a Boolean. Use a plain string here, not true/false.

token

A pass-through external ID, up to 32 characters. Set it when you create the hearing and it's returned on every subsequent GET — a good place to store your own system's record ID so you can match records on your end. This is not an authentication token. url (adjacent to it in the payload) is unrelated — it's the join link for remote/telephonic hearings.

Document / attachment uploads

Attachments (including garnishment paperwork or other case documents) are not part of the hearing creation payload — upload them after the hearing exists, via POST /hearings/v1/hearing/{id}/attachment. See JSON API - Hearing Attachment Reference for the full upload/download/delete contract, constraints, and error responses. There is no structured schema for garnishment documents specifically; upload the PDF the same way as any other attachment.

Fields not supported via the JSON API

These fields exist in the CSV/EDI import mechanism but are not on the HearingRequest.java DTO. The JSON binder silently ignores any field not declared on the DTO — sending these will not raise an error, it will just have no effect. Use the alternative listed instead:

Field details on this page were confirmed directly against the HearingRequest.java DTO (the JAXB-bound class behind POST /hearings/v1/hearing) with engineering, not reverse-engineered from the public API Explorer. Last reviewed July 2026.