Skip to main content
A case is how Palm requests information it needs to complete a filing. Most filings finish without one. When Palm does need something from you, it opens a case on the filing and notifies you by webhook — your response gives Palm what it needs to finish.
Early access — Cases are in preview and may change in backwards-incompatible ways before they are marked stable. Reach out before building on them in production.

​
How cases work

Any time between when you submit a filing and when it completes, Palm may need additional information. When that happens, Palm opens a case on the filing describing exactly what it needs, and you respond with the requested values. There’s no fixed list of cases. Today there’s a single kind, missing_information, used whenever Palm needs data it doesn’t already have — for example:
  • Additional information a filing requires that wasn’t collected at submission.
  • A correction to a value you submitted.
  • A clarification needed while the filing is processed.
Because the specifics vary from one filing to the next, each case carries a request.fields[] array describing exactly what to collect. Render your form from that array and a single generic handler covers every case — no per-case UI.

​
The case object

FieldTypeDescription
idstringUnique case identifier.
objectstringAlways case.
parent_typeenumResource the case is attached to. filing today.
parent_idstringID of the parent filing.
kindenumType of case. missing_information today — determines the shape of request and response.
statusenumLifecycle status. See Lifecycle.
summarystringOne-line summary of what’s needed.
detailsstringOptional markdown with more context.
requestobjectWhat Palm is asking for. For missing_information, a fields[] array.
responseobjectWhat you submitted. Present once you’ve responded.
due_atdatetimeWhen the case is expected to be resolved, if set.
opened_atdatetimeWhen the case was opened.
resolved_atdatetimeWhen the case closed, if it has.
resolution_reasonenumWhy the case closed. Set on resolved or superseded.

​
Request fields

Each entry in request.fields tells you everything you need to render one prompt:
FieldTypeDescription
namestringMachine-readable key. Use it as the key in your response.
typestringValue type: string, number, boolean, or date.
descriptionstringHuman-readable prompt explaining what’s being asked.
requiredbooleanWhether the field must be present in your response. Defaults to true.
exampleanyExample value showing the expected format.

​
Lifecycle

A case has two open states and two terminal states. The status tells you who acts next. 
needs_response ⇄ under_review → resolved | superseded
StatusStateMeaning
needs_responseOpenYour turn — submit a response.
under_reviewOpenPalm’s turn — Palm is actioning the case. Nothing needed from you.
resolvedTerminalClosed because the work moved forward, typically after your response was actioned.
supersededTerminalClosed because the parent filing was canceled, completed, or failed first.
When a case closes, resolution_reason records why: response_received, no_response_needed, parent_canceled, parent_completed, or parent_failed.

​
Webhook events

Each payload’s data.object is the full case object. See Webhooks for delivery, retries, and signature verification.
EventDescription
case.openedPalm opened a case and needs your response.
case.updatedAn open case changed — for example, your response was received and the case moved to under_review.
case.resolvedThe case closed (resolved or superseded).
case.opened — JSON
{
  "id": "evt_1781661076481_a1b2c3d4e5f6",
  "object": "event",
  "type": "case.opened",
  "created_at": "2026-06-17T01:51:16Z",
  "data": {
    "object": {
      "id": "9b3c1e44-2f6a-4c7d-8e10-2a4b6c8d0e12",
      "object": "case",
      "parent_type": "filing",
      "parent_id": "fil_abc123",
      "kind": "missing_information",
      "status": "needs_response",
      "summary": "Additional information needed to complete your filing.",
      "request": {
        "fields": [
          {
            "name": "corrected_principal_address",
            "type": "string",
            "description": "The principal office address on the filing was incomplete. Provide the full street address.",
            "required": true,
            "example": "123 Main St, Raleigh, NC 27601"
          }
        ]
      },
      "opened_at": "2026-06-17T01:51:16Z"
    }
  }
}

​
Respond to a case

  1. Receive case.opened. Use the payload, or fetch the case with GET /v1/case/{case_id}.
  2. Render prompts from request.fields. Label, type, and required flag are all there.
  3. Submit a response while the case is in needs_response, with a fields map keyed by each requested field’s name:
Bash
POST /v1/case/{case_id}/response
Request body — JSON
{
  "response": {
    "fields": {
      "corrected_principal_address": "123 Main St, Raleigh, NC 27601"
    }
  }
}
A successful response moves the case to under_review and fires case.updated. Once the work behind it is done, Palm closes the case and fires case.resolved. If Palm needs more, it opens another round on the same filing — each round is recorded for audit purposes.

​
Read cases

Bash
GET /v1/case/{case_id}
GET /v1/case?parent_type=filing&parent_id={filing_id}&status=needs_response
List supports filtering by parent_type, parent_id, status, and kind, with cursor-based pagination (limit, cursor).

​
Next steps