> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Company formation

> The formation flow, the statuses a company moves through, and where to read progress.

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](/api/webhooks) and by reading the company.

## Formation flow

```mermaid theme={null}
sequenceDiagram
    participant P as Your backend
    participant D as doola API
    participant TP as ThirdParty (State, IRS)

    P->>D: Create company
    D-->>P: formationSubmissionStatus: PENDING<br/>Formation: InProgress<br/>EinCreation: NotStarted

    D->>D: doola processes formation submission
    D-->>P: webhook company_formation_submitted
    D-->>P: formationSubmissionStatus: SUBMITTED<br/>Formation: InProgress<br/>EinCreation: NotStarted

    TP-->>D: State confirms formation
    D-->>P: webhook company_formation_completed
    D-->>P: webhook document_aoo_uploaded
    D-->>P: formationSubmissionStatus: SUBMITTED<br/>Formation: Completed<br/>EinCreation: InProgress

    TP-->>D: IRS issues EIN
    D-->>P: webhook company_ein_issued
    D-->>P: webhook document_einletter_uploaded
    D-->>P: formationSubmissionStatus: SUBMITTED<br/>Formation: Completed<br/>EinCreation: Completed
```

<Note>
  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.
</Note>

<Tip>
  In sandbox you do not have to wait for the state or the IRS. The [Sandbox playground](/api/sandbox-playground) completes each milestone on demand and fires the webhooks above through the normal delivery pipeline.
</Tip>

React to changes via [webhooks](/api/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](#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.

| Entity type     | Provide                              | Omit                                 |
| --------------- | ------------------------------------ | ------------------------------------ |
| `LLC` (default) | `members` (ownership must total 100) | `executiveMembers`, `ccorpValuation` |
| `CCorp`         | `executiveMembers`, `ccorpValuation` | `members`                            |

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](/api/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.

| `provider`        | You send `address`?                            | What doola uses                                          |
| ----------------- | ---------------------------------------------- | -------------------------------------------------------- |
| `customer`        | Yes, required                                  | The address you provide                                  |
| `registeredAgent` | No. Omit it (any address you send is not used) | doola's Registered Agent address for the company's state |

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):

```json theme={null}
{
  "addresses": [
    { "provider": "customer",        "type": "mailing",  "address": { "line1": "251 W 30th St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "USA" } },
    { "provider": "registeredAgent", "type": "business" }
  ]
}
```

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.

<Note>
  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](/api/api-reference/reference-data/list-state-filing-fees).
</Note>

### 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](/api/non-us-formation) 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](/api/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:

| You want to know                                   | Read                                                                   | Webhook                       |
| -------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------- |
| Did doola receive and accept my formation request? | `formationSubmissionStatus` on the company                             | `company_formation_submitted` |
| Is the company actually formed with the state?     | The **Formation** service in [Company services](/api/company-services) | `company_formation_completed` |

<Warning>
  `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.
</Warning>

### 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.

| Status      | Meaning                                                                 |
| ----------- | ----------------------------------------------------------------------- |
| `PENDING`   | Request received; doola is processing the submission                    |
| `SUBMITTED` | doola accepted the request and started the formation                    |
| `FAILED`    | Submission failed. Check the company's `adminNotes`, then contact doola |

<Info>
  **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.
</Info>

<Warning>
  If a company sits in `PENDING` for an extended period, read its `adminNotes` (returned on the get-company endpoint) or contact [engineering@doola.com](mailto:engineering@doola.com).
</Warning>

### 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:

```json theme={null}
{ "name": "Formation", "status": "InProgress", "subStatus": "WaitingForRaToSucceed" }
```

The Formation service `status` moves from `InProgress` to `Completed`, and the `company_formation_completed` webhook fires when it does:

| status       | subStatus               | Meaning                                           |
| ------------ | ----------------------- | ------------------------------------------------- |
| `InProgress` | `WaitingForRaToSucceed` | Filing submitted to the state; pending completion |
| `Completed`  | *(none)*                | Articles of organization/incorporation filed      |

[Company services](/api/company-services#statuses) 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](/api/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](/api/non-us-formation).

Prefer [webhooks](/api/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.