Skip to main content
A formation is created in one request, then progresses asynchronously. You submit everything up front; doola validates it, files with the state, and obtains the EIN. You follow along with webhooks and by reading the company.

​
Formation flow

The diagram shows the typical order, not a strict dependency. company_ein_issued and document_einletter_uploaded fire when the IRS issues the EIN, on the IRS’s own timeline, so they are independent of the formation-completion webhooks (company_formation_submitted and company_formation_completed) and can arrive well after them.
In sandbox you do not have to wait for the state or the IRS. The Sandbox playground completes each milestone on demand and fires the webhooks above through the normal delivery pipeline.
React to changes via webhooks. To display current progress, read each service’s status on the company. The two signals this involves — submission status and the Formation service status — are explained under Two things to track below.

​
Entity types

Set entityType on the create-company request to choose what to form. It defaults to LLC when omitted. For a CCorp, the executive team must include at least one President, Secretary, Treasurer, and Director — President, Secretary, and Treasurer may each appear only once, while Director may repeat. Each name option’s suffix must also match the entity type: an LLC ending (LLC, Limited Liability Company, …) for an LLC, or a corporate ending (Inc., Corporation, …) for a CCorp. See Domain objects for the full field list of executive members and share structure.

​
Addresses

Every create-company request carries exactly two address entries: one mailing and one business. For each entry you choose a provider that decides who supplies the address. So you can supply your own address, hand the entry to doola’s Registered Agent, or mix the two (for example, your own mailing address with a registeredAgent business address):
The two types are used differently:
  • business is the company’s business address on the state formation filing.
  • mailing is where correspondence for the company is directed, including the EIN confirmation letter.
Set an entry to registeredAgent and doola resolves its Registered Agent address for the company’s state automatically, so routing mailing to the Registered Agent means correspondence lands with doola.
Choosing the Registered Agent for an address carries no separate fee. The only per-company charge is the state formation filing fee, which you can look up per state and entity type from the state-fees reference endpoint.

​
Address fields

Within any address, line1, city, state, postalCode, and country are required; line2 is optional. phone differs by where the address is used:
  • Person addresses (the responsibleParty, each member, each executive member): phone is required.
  • Company addresses (the mailing and business entries): phone is optional.
A registeredAgent company entry omits the address object entirely, so none of these fields apply to it.

​
Non-US founders

doola forms US companies for founders anywhere in the world. When no one on the company has a US tax ID, the IRS requires the founder to sign an SS-4 before it issues the EIN. The create-company and retrieve-company responses tell you whether this applies through the signatureRequirements field, and the Non-US founders guide covers the signing flow end to end. Everything else on this page applies unchanged.

​
Expedited EIN

You can request prioritized EIN processing for a non-US founder by adding requestedServices: [{ "service": "EinCreation", "variant": "Expedite" }] to the create-company request. The Expedited EIN guide covers availability, the request shape, and the errors. Everything else on this page applies unchanged.

​
Two things to track

A formation has two separate signals, and confusing them is the most common integration mistake. Decide which question you are answering:
formationSubmissionStatus is not the end-to-end formation status. It only tracks the request handoff and never reaches a “completed” value, so polling it to detect a formed company waits forever. Use the Formation service status for that.

​
Submission status

formationSubmissionStatus tracks how doola is handling your formation request internally. It says nothing about whether the company is formed yet. When you submit a formation, the company starts at PENDING. Once doola confirms it has accepted and started processing the request, it sends the company_formation_submitted webhook and the field becomes SUBMITTED. If the request cannot be accepted, the field becomes FAILED and company_formation_failed fires.
How do I know the submission succeeded? Either signal confirms it:
  • you received the company_formation_submitted webhook, or
  • you fetched the company and formationSubmissionStatus is SUBMITTED.
This happens asynchronously, so prefer the webhook. Do not sit in a polling loop waiting on the field.
If a company sits in PENDING for an extended period, read its adminNotes (returned on the get-company endpoint) or contact engineering@doola.com.

​
Formation progress

To tell a customer their company is formed (filed and confirmed by the state), track the Formation service rather than the submission status. Each service appears in the company’s services array, for example:
The Formation service status moves from InProgress to Completed, and the company_formation_completed webhook fires when it does: Company services covers the full per-service lifecycle for Formation, EIN, and Registered Agent, including the sub-statuses that show what each service is waiting on.

​
Reading progress

The get-company endpoint returns the live state of a formation, including:
  • formationSubmissionStatus — the submission status above; see Company services for the full per-service lifecycle.
  • ein — the Employer Identification Number, populated once issued by the IRS. null until then. The company_ein_issued webhook fires when it is populated.
  • formationFilingDate — the date the formation was filed with the state. null until filed.
  • formationFilingNumber — the filing number the state assigned when the formation was filed. null until filed.
  • adminNotes — notes from the doola operations team flagging anything on the company, such as a filing delay or IRS correspondence.
  • signatureRequirements — for a non-US founder, a pending SS-4 entry until the founder signs (plus a pending Form 8821 entry when the company is on an expedited EIN); an empty list for a US founder. See Non-US founders.
Prefer webhooks over polling: subscribe to the formation and document events to react the moment something changes.

​
Documents

When formation completes, documents become available and a document_* webhook fires for each. Call the document endpoints after receiving the event to list documents and fetch a short lived download URL. Document types are ArticlesOfOrganization, EinLetter, and Mail, plus SignedSS4 for non-US founders and SignedForm8821 for non-US founders on an expedited EIN.