How it works
- Palm opens a case on the filing and sends a
case.openedwebhook. - Read what it asks for. Each case carries a list of the values and documents Palm needs, and any file Palm is sending you.
- Collect the answers from your member, rendering your prompts from that list.
- Submit the response, keying each answer by the name Palm asked for.
- Palm acts on it and the filing continues.
What a case asks for
Cases are exceptions, and exceptions do not come from a fixed list. Rather than define one, Palm sends each case with its own description of what it needs, so a situation nobody anticipated arrives in a shape you already know how to read. Every case carries akind. There are two.
missing_information is the general kind, raised when a filing needs something the request did not carry: an address the state will not accept, a detail a state asks for but does not publish as a requirement, a document only the business owner holds. It lists what Palm needs under request.fields, each entry carrying the prompt to show and the type of answer expected, which may be a value or a document.
legal_name_change is raised when the state will not accept the name on the filing, most often because another business registered it first, or because the state judges it too close to an entity already on the register. It asks for one field, legal_name, and nothing else. Because that shape is fixed, Palm acts on the answer directly: it renames the filing, any bundled filing not yet submitted so a pending EIN application follows the new name, and the business record. filing.legal_name always reports the name the filing completed under.
For the exact object and field definitions, see Retrieve a case.
Documents on a case
Documents move in both directions, so the evidence behind a request and the answer to it both stay on the filing. From Palm.request.documents carries the ids of any files Palm is sending you, so the evidence behind a request travels with it and you can see what Palm saw. Retrieve each one through the document endpoints.
From you. A document field is answered with a file uploaded to the business. The response carries anything else worth sending with it: the certificate for a name the member reserved with the state, a written approval a regulator issued, or a form the state requires the member to sign themselves.
Either way the document is bound to the work it belongs to. related_items on the document names the case, and the filing behind it, so a file is traceable to the filing it was sent for long after the case closes. The same relationship is available as a filter.
Bash
Respond to a case
Bash
case.opened payload carries the whole case. Submit while the case is still needs_response, keying each answer by the name Palm asked for.
A successful submission hands the case back to Palm. When the work behind it finishes, Palm closes the case.
For the request body, see Submit a response to a case.
Track a case
Bash
needs_response is the only status that accepts a response, and the only point in a filing that blocks on you.
Waiting on Palm. under_review means your answer arrived and Palm is acting on it.
Finished. resolved when the work moved forward, superseded when the filing behind the case stopped first. resolution_reason records which.
case.* webhook fires at each transition, so you can drive your UI from events rather than polling: case.opened when Palm needs you, case.updated when an open case changes, and case.resolved when it closes. Each payload carries the full case object, including any documents on it. See Webhooks for delivery, retries, and signature verification.