JSON API - Hearing Response Reference
This page documents the JSON object returned when you create a hearing via POST /hearings/v1/hearing. It's a companion to JSON API - Hearing Create Payload Reference, which covers what you send — this page covers what you get back.
Field details below are confirmed directly against HearingResponse.java and its nested ServiceResponse class with engineering — not reverse-engineered from a single example.
Note on the public API Explorer: the sample response shown there has fallen behind the actual DTO — trust this page over that example. Two concrete reasons the shapes differ: (1) the sectioned items array (Overview/Where/Who/Details) is mobile-app-only and won't appear on a plain API GET/POST response, and (2) a few declared fields — isReportAllowed, alertFee, confirmCover, alertBusy — are never populated on this v1 path and always come back null. Don't build logic against those four.
Note on offers/counteroffers: the pricing negotiation flow (an attorney offering a different price than posted, and a client countering) is visible only in the Docketly app — there is no field on this response and no separate endpoint that surfaces it. hasAppearance and the appearance/attorney objects below tell you once a hearing is covered, but nothing in this API tells you a pending offer exists before that point.
Top-level fields
Field | Type | Notes |
|---|---|---|
id | String | The unique ID of this hearing. |
attachments | Array | Documents attached to the hearing. Empty if none have been uploaded yet. |
date | String | The hearing date/time, echoed back in ISO 8601 UTC format (e.g. |
dateLocal | String | Display-friendly local date/time with timezone abbreviation (e.g. |
day | String | Day-of-week abbreviation (e.g. |
state | String | Echoed from the request. |
county | String | Echoed from the request. |
court | String | Legacy alias of |
courtName | String | The court value you submitted, echoed back. This is not the resolved court — see |
courtLocation | String | The resolved/official court name Docketly matched your submission to (flat copy of |
courtResponse | Object | The full resolved court/location record. See below. Absent if court resolution failed (see |
caseName | String | Echoed from the request. |
caseNumber | String | Echoed from the request. |
fileNumber | String | Echoed from the request. |
service | Object | The hearing type/service record. See below. |
price | Decimal | The cost of coverage for this hearing. |
balance | Decimal | Echoed from the request. |
principal | Decimal | Echoed from the request. |
interest | Decimal | Echoed from the request. |
attorneyCosts | Decimal | Echoed from the request. |
courtCosts | Decimal | Echoed from the request. |
miscCosts | Decimal | Echoed from the request. |
sifPercentage | Integer | Per-hearing settlement authority "SIF Amount" (whole-number percent, 0–100), echoed back. Populated from what you sent on the request, or — if you omitted it — from your account's auto-add default; null if neither applies. See the create payload reference for how a per-hearing value overrides your auto-add default. |
sifMonths | Integer | Per-hearing settlement authority "SIF Timeframe" (whole number of months, 0 or greater), echoed back. Populated from the request, or your account's auto-add default if omitted; null if neither applies. |
lat | Decimal | Convenience copy of |
lng | Decimal | Convenience copy of |
locator | String | A short reference code for the hearing, distinct from |
isCanceled | Boolean | Whether the hearing has been canceled. |
isTelephonic | Boolean | Whether the hearing is telephonic/remote. Echoed from the request. |
isInHouse | Boolean | Whether the hearing is being covered by an in-house attorney vs. Docketly's attorney network. Related to |
isAuthorized | Boolean | Whether the calling token/user has privileged/owner access to this hearing's sensitive data (client identity, instructions, debt figures, attachments) — not whether the hearing is "approved." True for the owning client and internal/privileged roles; false for e.g. an attorney browsing the marketplace who doesn't own the hearing. Will read |
hasAppearance | Boolean | True once a covering attorney has been secured (an appearance record exists). False if not yet covered — will be |
appearance | Object | The coverage record for this hearing — present once |
attorney | Object | The attorney currently covering the hearing — present once |
isReportAddress | Boolean | The covering attorney's post-hearing report form includes an address field for this service type. Service-type configuration, not hearing state — see note below the table. |
isReportBank | Boolean | The report form includes a bank/account field for this service type. |
isReportContinued | Boolean | The report form includes a "was the hearing continued?" field for this service type. |
isReportDismissed | Boolean | The report form includes a "was it dismissed?" field for this service type. Not a live status of whether the case is dismissed — the hearing hasn't happened yet at create time. |
isReportEmployer | Boolean | The report form includes an employer field for this service type. |
isReportGarnishment | Boolean | The report form includes a garnishment section for this service type. |
isReportGarnishmentFinalOrderEligible | Boolean | The report form includes a garnishment-final-order-eligibility field for this service type. Mirrors the same field nested under |
isReportImpasse | Boolean | The report form includes an impasse field for this service type. |
isReportIssues | Boolean | The report form includes an issues field for this service type. Also OR'd with a per-client feature toggle, so it can read |
isReportJudgment | Boolean | The report form includes a judgment field for this service type. |
isReportMiniMiranda | Boolean | The report form includes a Mini-Miranda field for this service type. |
isReportMotionGranted | Boolean | The report form includes a "was a motion granted?" field for this service type. Not an indicator of case outcome — the hearing hasn't happened yet at create time. |
isReportNextHearing | Boolean | The report form includes a next-hearing-date field for this service type. |
isReportOtherFeesDispute | Boolean | The report form includes an other-fees-dispute field for this service type. |
isReportSettlement | Boolean | The report form includes a settlement field for this service type. |
isRequireGarnishment | Boolean | The garnishment report field (above) is mandatory to submit the report, for this service type. Still post-hearing, service-type-driven — not a pre-hearing requirement. |
isRequireGarnishmentFinalOrderEligible | Boolean | The garnishment-final-order-eligibility report field is mandatory to submit the report, for this service type. Mirrors the same field nested under |
isRequireIssues | Boolean | The issues report field is mandatory to submit the report, for this service type. |
isRequireJudgment | Boolean | The judgment report field is mandatory to submit the report, for this service type. |
isRequireMotionGranted | Boolean | The motion-granted report field is mandatory to submit the report, for this service type. |
About the isReport* / isRequire* clusters: both are service-type form configuration, not hearing state — every one is copied verbatim from the hearing's service type at serialization. isReport* = "the covering attorney's post-hearing report form includes this field for this service type" (which fields show up on the form, not any answer). isRequire* = the subset of those report fields that are mandatory to submit the report (report-form validation) — still post-hearing and service-type-driven, not a pre-hearing prerequisite. None of these fields say anything about this specific hearing's outcome.
appearance (nested object)
The coverage record — a distinct entity from the hearing itself, representing the specific instance of an attorney being assigned to it. Absent/null when hasAppearance is false.
Field | Type | Notes |
|---|---|---|
id | String | The unique ID of this specific coverage instance. Not the attorney's own ID (see |
createdOn | String | When this coverage was secured — i.e. when the attorney locked in. Not the hearing date. |
Change-detection semantics: if the covering attorney drops and a new attorney takes over, hasAppearance stays true throughout (once re-covered) but appearance.id and appearance.createdOn both change to reflect the new coverage instance. Polling appearance.id between GET calls is the way to detect a reassignment your integration might otherwise miss by only checking hasAppearance. Both fields are read-only — no client API call accepts an appearance ID as input.
attorney (nested object)
The attorney currently covering the hearing. Present once hasAppearance is true, absent/null before then.
Field | Type | Notes |
|---|---|---|
id | String | The attorney's own ID — distinct from |
Full field-by-field detail for this object (name, contact info, etc.) has not yet been cataloged against the DTO the way the rest of this page has — only id is confirmed as of this writing. Flag to engineering if your integration needs the complete attorney object shape before relying on it.
courtResponse (nested object)
The full resolved court/location record — a different entity than the hearing itself. Absent if court resolution failed (see courtLocation note above).
Field | Type | Notes |
|---|---|---|
id | String | The unique ID of the court/location record. Different from the top-level hearing |
name | String | The court's official (resolved) name. Also flatly copied to the top-level |
address1 | String | Court street address. |
city | String | Court city. |
state | String | Court state. |
zipCode | String | Court zip code. |
phone | String | The court's phone number. |
lat / lng | Decimal | The court's coordinates. Also copied to the top level of the hearing object for convenience. |
caseNumberPattern | String | An internal pattern Docketly uses to match case numbers to this court (e.g. |
county | String | The court's county. |
service (nested object)
The full hearing type/service record tied to the serviceId submitted on the request. Carries the complete service definition (60+ report flags); the top-level fields of the same name are the actionable subset surfaced flat.
Field | Type | Notes |
|---|---|---|
id | String | Matches the |
name | String | Full display name of the service (e.g. "Collections / Post-Judgment / Protected Property Hearing"). |
category1 / category2 | String | Categorization of the hearing type. |
state | String | State this service applies to. |
isReportTimeCourt | Boolean | The report form includes a time-in-court field for this service type — see the |
isReportGarnishmentFinalOrderEligible | Boolean | The service-level definition. The identical top-level field is copied straight from this — both are read from the same underlying value and will always match. Treat the top-level field as authoritative; this nested copy can be ignored. |
isRequireGarnishmentFinalOrderEligible | Boolean | Same as above — service-level source for the identical top-level field. |
Fields declared but never populated (v1)
isReportAllowed, alertFee, confirmCover, alertBusy — these exist on the DTO but are never populated on this v1 path. They will always be null. Do not build integration logic against them.
Confirmed against HearingResponse.java / ServiceResponse.java with engineering. appearance/attorney object documentation added September 2026 following a live integration test; attorney object field list beyond id still needs full confirmation against the DTO. Last reviewed July 2026 (prior to that addition).