New company names needed
FORMATION_NAME_OPTIONS_EXHAUSTED: the state rejected every name you submitted. You send replacements.SS-4 signature needed again
FORMATION_SIGNATURE_SS4_RESET: a name change voided a signed SS-4. Your founder signs again.Form 8821 signature needed
FORMATION_SIGNATURE_FORM8821_REQUIRED: doola could not obtain the EIN online. Your founder signs a Form 8821.Founder address needed
FORMATION_FOUNDER_ADDRESS_REQUIRED: an Indiana or Illinois formation was sent with the registered agent’s address. You send the founder’s own address.New business address needed
ANNUAL_REPORT_ADDRESS_NOT_ACCEPTED: the state will not take the registered agent’s address on an annual report. You send a different business address.Lower share count or par value needed
ANNUAL_REPORT_SHARE_VALUE_TOO_HIGH: share count times par value is above the state’s pricing threshold. You send lower figures.Documents missing for the import
IMPORT_DOCUMENTS_MISSING: an imported company still lacks a required document. You upload it.More information needed for the import
IMPORT_INFO_REQUIRED: doola’s review of an imported company needs a correction. You send the fields and documents it asks for.A closed action is never reopened. If the same thing is needed again, doola raises a new action with a fresh
requiredActionId. Key your records on requiredActionId, not on the company plus the code.Anatomy
Every action carries arequiredActionId, an actionCode that says what is needed, and a reason written for a person to read. These are the three you build against:
Full field list: Required action.
For name rejections the
reason usually names the exact names the state turned down. When doola could not capture them it falls back to a fixed sentence, All submitted company name options were rejected by the state. Submit new options.
Statuses
An action’sstatus is the last thing that happened to it. open tells you whether it still needs attention.
resolved and rejected are terminal, and open is then false. Every other status means the action is still open.
Once a resolution has been submitted, a later delivery outcome (delivered or delivery_failed, from a webhook retry) is still recorded in the history but no longer changes status.
awaitingResponse is true while the action is waiting for a resolution: created, delivered or delivery_failed. It turns false once a resolution is submitted and stays false until the action closes. For a company formed through the embedded SDK, the founder can submit new names from the app, so awaitingResponse can turn false without you submitting. You can still submit your own resolution after that; it replaces the names the founder sent.
How doola tells you
Every code is announced by a webhook event, and all of them carry the same payload shape. Most codes have an event to themselves; the two annual report corrections share one, so branch onactionCode rather than on the event name.
company_import_info_required also carries requestedFieldIds and requestedDocumentTypes when they are not empty.
Delivery follows the standard webhook contract, so treat it as at least once and dedupe on eventId. An action doola never managed to deliver is still open and still blocking — see Reconciling.
Reading actions
Everything still open
One call, across every company you own. This is what a dashboard or a startup check should read.total is the tenant-wide open count whatever page size you ask for, so size=1 is a cheap “is anything waiting on me?” check. size is capped at 100 — a larger value is clamped rather than rejected.
One company
payload, unpaged, most recently changed first. Unlike the open list this one keeps resolved and rejected entries, which is what lets you tell “nothing was ever needed” apart from “something was needed and I missed it”.
One action, with history
history array: every step the action has been through, oldest first, including whether doola reached your endpoint and what you submitted.
submittedPayload appears on submitted steps only. It is a record of what you sent at that moment, not the company’s current state — read the company for that.Reconciling
Webhooks can be missed — downtime on your side, or an endpoint doola disabled after repeated failures. An action left indelivery_failed is still open and still blocking that company, and no further webhook announces it.
Guard against that with one call at startup and on a schedule:
total against what you received and page with page=1, page=2, and so on if you ever hold more than 100 open actions at once; for most tenants this is a single request no matter how many companies you have.
Testing
A founder address action is raised by the API itself: create a sandbox company inIN or IL with provider: registeredAgent on an address entry. The sandbox playground cannot raise the other required actions today. To exercise those end to end in sandbox, ask doola to raise one on a sandbox company at engineering@doola.com; the webhook, the reads, and the resolution endpoint then behave exactly as they do in production. The reads are safe to build against meanwhile: a company with nothing outstanding returns an empty list.
Errors
Branch onerror.code, never on the message. The 400-level codes below come from submitting a resolution; the 404s are returned by the reads as well.
Checks run in a fixed order — body shape, company scope, action scope,
actionCode match, resolvability, then whether the action is still open — so a request with more than one problem reports the first failure in that list. A closed signature action therefore answers 422, not 409.
Resolving an IMPORT_INFO_REQUIRED action can also answer 400 E_REQUEST_BODY_INVALID, 404 E_COMPANY_DOCUMENT_NOT_FOUND and 409 E_COMPANY_ALREADY_REGISTERED. That page lists when.
Anything that is not yours is a 404, never a 403 — a 403 would confirm the ID exists, which is enough to enumerate another partner’s companies.
See Errors for the response envelope and the global codes that any endpoint can return.