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

# FAQ

> Common questions about the doola Partner API and Partner Portal, in plain language.

Common questions about the doola Partner API and Partner Portal. For endpoint-level request and response detail, see the **API reference** tab and the [guides](/api/formation).

<Note>
  Don't have access yet? [Get API access](https://www.doola.com/partner-with-us/). Already a partner and can't find your answer here? Email [engineering@doola.com](mailto:engineering@doola.com).
</Note>

## What you can do today

* **Form US companies (LLC or C-Corp) for your users.** Submit a formation request via the API; doola handles state filing, registered agent, and EIN. Your user never has to interact with doola directly.
* **Register and manage your customers.** Create customers (idempotent) and attach one or more companies to each.
* **Track formation status in real time.** Poll the API or receive webhook events as a company moves through formation.
* **Download company documents.** Articles of Organization, EIN letter, and forwarded mail, via temporary signed links.
* **Self-manage your API keys and webhook endpoint** in the Partner Portal, including reviewing delivery logs.
* **Browse everything in the Partner Portal**, a ready-made web dashboard for your team.

## Access and authentication

<AccordionGroup>
  <Accordion title="How do I get access?">
    [Request API access](https://www.doola.com/partner-with-us/) and the doola team provisions your account, issues your first API key (`dk_live_...`) and webhook signing secret, and creates Partner Portal logins for anyone on your team who needs dashboard access.
  </Accordion>

  <Accordion title="What support do I get during integration?">
    Once your agreement is signed, you get sandbox access and production keys, a direct line to our engineering team for integration and API questions, and implementation support from sandbox through go-live and beyond.
  </Accordion>

  <Accordion title="What does the API key look like, and is it secure?">
    API keys follow the format `dk_live_...`. They are long, unique, and scoped to your account only, so your key can never see another partner's data. Keys don't expire by default, and if one is ever compromised it can be revoked and replaced without losing any of your customer or company data.
  </Accordion>

  <Accordion title="Can I sign in instead of using the API key?">
    Yes. The Partner Portal uses a standard email and password login. A JWT sign-in flow is also available if you want to build your own UI on top of the API.

    **API key vs. Partner Portal:** the API key (`dk_live_...`) is for machine-to-machine calls such as creating customers, forming companies, and reading status. Anything else, such as managing API keys, setting your webhook URL, or reviewing delivery logs, lives in the Partner Portal.
  </Accordion>

  <Accordion title="Can I manage my own API keys?">
    Yes. Manage your API keys (create, list, revoke, delete) in the Partner Portal. Two intentional guardrails: an existing API key can't mint new keys (only a signed-in user can), and "revoke all keys at once" stays a doola-assisted action to avoid accidental lockouts.
  </Accordion>

  <Accordion title="Can I have multiple team members on the portal?">
    Yes. Each person gets their own email and password login, and all logins see the same company and customer data scoped to your account.
  </Accordion>

  <Accordion title="How is my data isolated from other partners?">
    Completely. Your account is a fully isolated tenant, so your API key only ever has access to companies and customers that belong to you. There is no way to see, or be seen by, another partner through the API or the portal.
  </Accordion>
</AccordionGroup>

## Forming companies

<AccordionGroup>
  <Accordion title="What is included in a formation?">
    Every formation includes:

    * **Entity filing** — the LLC or C-Corp filed with the state authority
    * **EIN** (Employer Identification Number) from the IRS
    * **Registered Agent service for the first year**, in the formation state
    * **Governance document** — an Operating Agreement for an LLC, Corporate Bylaws for a C-Corp
    * **US business address** — the Registered Agent address doubles as a US mailing address. Incoming mail is opened, scanned, and delivered to you through the `document_mail_uploaded` webhook, within these limits:
      * All State and government notices are included, with no cap
      * Plus the first 5 pieces of non-official mail
      * **No packages** — the address accepts letter mail only
      * Physical mail forwarding is available for an additional fee

    The first three arrive as the three services attached to every company (`Formation`, `EinCreation`, `RegisteredAgent`), so you can track each one independently — see [Company services](/api/company-services). The governance document lands as a `document_operatingagreement_uploaded` or `document_corporatebylaws_uploaded` [webhook](/api/webhooks#events) shortly after the Articles of Organization are processed.

    The only per-company charge on the base formation is the state filing fee, which varies by state and entity type — look it up from the [state-fees reference endpoint](/api/api-reference/reference-data/list-state-filing-fees).
  </Accordion>

  <Accordion title="What entity types do you support?">
    **LLC and C-Corp.** Set the optional `entityType` field on the create-company request to `LLC` (the default when omitted) or `CCorp`. The two differ in who you list: an `LLC` takes `members` with ownership percentages, while a `CCorp` takes `executiveMembers` (officers and directors) and a `ccorpValuation` (authorized shares and par value per share).
  </Accordion>

  <Accordion title="What information do I provide to form a company?">
    * The customer the company belongs to (`doolaCustomerId`)
    * The entity type, `LLC` (default) or `CCorp`
    * The US state to form in
    * Up to 3 preferred company names, in order. doola uses the first one that clears the state's availability check
    * The industry (NAICS code)
    * A business description
    * The responsible party (the person legally responsible for the EIN application)
    * For an **LLC**: company members and their ownership percentages (must total exactly 100%)
    * For a **C-Corp**: executive members (at least one President, Secretary, Treasurer, and Director; President, Secretary, and Treasurer may each appear once, Director may repeat) plus the share structure (number of authorized shares and par value per share)

    doola auto-assigns the registered agent based on the chosen state, so you don't supply that.
  </Accordion>

  <Accordion title="Can I form companies for non-US founders?">
    Yes. doola forms US companies for founders anywhere in the world. When no one on the company has a US tax ID (SSN or ITIN), the IRS requires the founder to sign an **SS-4** before it issues the EIN. The create-company response flags this with a pending `signatureRequirements` entry, and you collect the signature through a fully whitelabeled doola signing link. See [Non-US founders](/api/non-us-formation) for the end-to-end flow.
  </Accordion>

  <Accordion title="Can I expedite the EIN?">
    Yes, for **non-US founders** (no member, executive member, or responsible party has an SSN or ITIN). Expedited processing is available for an additional fee, billed per use. Contact our team for pricing details.

    Request it at company creation by adding `requestedServices: [{ "service": "EinCreation", "variant": "Expedite" }]` to the create-company payload. See [Expedited EIN](/api/expedited-ein) for the full guide.
  </Accordion>

  <Accordion title="What states are supported?">
    All 50 US states plus Washington DC. Query `/v1/partner/references/states` for the live list, so you never hardcode anything in your onboarding forms.

    For current state filing fees by state and entity type, see the [doola state fees spreadsheet](https://docs.google.com/spreadsheets/d/1BY5znyrHUcKGj8agkh_mxKyG8tRFegBsvZLGOmJy9w0/edit?usp=sharing).
  </Accordion>

  <Accordion title="How long does formation take?">
    Your API call returns immediately (usually within a second) with a `PENDING` status. The actual formation work happens asynchronously in the background. Timelines vary by state and current volume. You are notified by webhook the moment the status changes, and you can check status any time via the API or the portal.

    The end-to-end journey your customer experiences, from submission to a ready-to-use company, typically runs as follows. Share this timeline with your clients to set expectations.

    <Steps>
      <Step title="Submit the formation request">
        You collect the company details (name options, entity type, state) and member / responsible-party details, then submit them via the API. The call returns immediately with a `PENDING` status.
      </Step>

      <Step title="Company filed with the state — ~1 week on average">
        doola files the formation, prepares the Articles of Organization, and assigns the Registered Agent. Timing varies by state and current volume.
      </Step>

      <Step title="Business documents secured">
        The EIN and the essential business documents needed for banking, hiring, and taxes are issued.

        * **US founder:** 1–2 business days
        * **Non-US founder:** 4–6 weeks on average

        Non-US founders also sign an SS-4 as part of this step — see [Non-US founders](/api/non-us-formation).
      </Step>

      <Step title="US bank account opened — 3–5 business days">
        Once the business documents are ready, your customer can apply for a US bank account through the partner portal. International clients need a passport.
      </Step>

      <Step title="Run & grow the business">
        The company is fully set up and compliant. Optional bookkeeping and tax services support ongoing operations.
      </Step>
    </Steps>

    <Note>
      These are typical estimates, not guarantees. State filing time varies by state and current volume, and EIN issuance follows the IRS's own timeline. The last two steps (bank account, ongoing operations) sit outside the Partner API and are shown only so you can share the full client journey.
    </Note>
  </Accordion>

  <Accordion title="Is there a sandbox?">
    Yes. Develop and test against `https://api.test.doola.com` before going to production (`https://api.doola.com`). Sandbox keys never trigger real state filings or charges. Sandbox also includes a [playground](/api/sandbox-playground) that triggers the formation and EIN webhooks on demand.
  </Accordion>

  <Accordion title="Is a mailing address included?">
    Yes. A mailing address is included as part of the registered agent service. Incoming mail is opened, scanned, uploaded, and delivered to you through the `document_mail_uploaded` webhook — all State and government notices are included, plus the first 5 pieces of non-official mail. The address accepts letter mail only, so **no packages**. Physical mail forwarding, when you need it, carries a separate fee.
  </Accordion>

  <Accordion title="What if none of my submitted company names are available?">
    The formation charge applies at submission, so you are charged when the API request is made. doola then processes the formation and checks name availability. If all of your submitted names are unavailable, doola reaches out (Slack or email) for an updated name and works with you to complete the formation; the charge stays in place while this is resolved.

    Fewer than 5% of formations hit a name conflict, and name-availability checking is coming to the API. Until then, submit all three name options to minimize the chance of a conflict.
  </Accordion>

  <Accordion title="What happens if I miss the annual registered agent renewal?">
    doola follows up directly with webhook reminders ahead of the renewal date, so you have time to act before it lapses.
  </Accordion>
</AccordionGroup>

## Tracking status and documents

<AccordionGroup>
  <Accordion title="How do I track a formation to completion?">
    There are two separate signals, and they answer different questions:

    | You want to know                               | Where to look                                                                                                 |
    | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
    | Did doola receive my formation request?        | `formationSubmissionStatus` on the company (`PENDING` → `SUBMITTED`, or `FAILED`)                             |
    | Is the company actually formed with the state? | The **Formation** service status under [Company services](/api/company-services) (`InProgress` → `Completed`) |

    `formationSubmissionStatus` only tracks the request handoff and never reaches a "completed" value, so don't poll it to detect a formed company. Watch the `company_formation_completed` webhook or the Formation service status instead. The `adminNotes` field carries any flags from the doola operations team (for example filing delays); check it first if something is taking longer than expected.
  </Accordion>

  <Accordion title="What happens if formation fails?">
    If doola's system can't complete the formation (for example a state filing issue), it retries automatically up to **4 times, at 5, 15, 30, and 60 minutes**, before marking the company `FAILED`. When that happens:

    * The company status is set to `FAILED`
    * You receive a `company_formation_failed` webhook
    * The doola team is alerted internally

    From there, reach your doola account contact to resolve it.
  </Accordion>

  <Accordion title="How do I know when the EIN is issued?">
    Subscribe to the `company_ein_issued` webhook, then fetch the company to read the `ein` field. The IRS confirmation letter follows separately via `document_einletter_uploaded` once it is ready to download. The two events arrive independently, so don't assume an order.
  </Accordion>

  <Accordion title="How do I access company documents?">
    After a `document_*` webhook fires, call the documents endpoints to list a company's documents and fetch a temporary signed download URL (valid about 1 hour). Don't cache the URL; request a fresh one each time you need to download.
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="What are webhooks and how do they work?">
    Webhooks are HTTP notifications doola sends to your server whenever something meaningful happens, so you don't have to keep polling "is it done yet?". doola sends a `POST` with a JSON payload to your HTTPS endpoint, and your server responds `200 OK`.
  </Accordion>

  <Accordion title="How do I test webhooks without waiting for a real formation?">
    Use the [Sandbox playground](/api/sandbox-playground). Two sandbox-only endpoints complete a test company's formation and EIN issuance on demand, firing `company_formation_completed`, `document_aoo_uploaded`, `company_ein_issued`, and `document_einletter_uploaded` through the normal delivery pipeline: signed, subscription-filtered, and logged in the Partner Portal.
  </Accordion>

  <Accordion title="Which events will I receive?">
    | Event                                  | Fires when                                                   |
    | -------------------------------------- | ------------------------------------------------------------ |
    | `company_formation_submitted`          | Formation accepted and processing started                    |
    | `company_formation_completed`          | Formation complete, company is active                        |
    | `company_formation_failed`             | Formation failed after all retries                           |
    | `company_filing_date_updated`          | The filing date was updated by doola                         |
    | `company_ein_issued`                   | The company's EIN was issued and is readable on the company  |
    | `document_aoo_uploaded`                | Articles of Organization ready to download                   |
    | `document_einletter_uploaded`          | EIN letter ready to download                                 |
    | `document_mail_uploaded`               | Business mail document uploaded                              |
    | `document_corporatebylaws_uploaded`    | Corporate Bylaws ready to download (CCorp only)              |
    | `document_operatingagreement_uploaded` | Operating Agreement ready to download (LLC only)             |
    | `signature_ss4_completed`              | A non-US founder signed their SS-4                           |
    | `document_ss4_uploaded`                | Signed SS-4 stored and ready to download                     |
    | `signature_ss4_reminder_due`           | An unsigned SS-4 is due a reminder (day 1, 3, 7)             |
    | `signature_form8821_completed`         | A non-US founder on an expedited EIN signed their Form 8821  |
    | `document_form8821_uploaded`           | Signed Form 8821 stored and ready to download                |
    | `signature_form8821_reminder_due`      | An unsigned Form 8821 is due a reminder (day 1, 3, 7)        |
    | `partner_webhook_disabled`             | Your webhook endpoint was automatically disabled (see below) |

    The three SS-4 events fire only for non-US founders; the three Form 8821 events fire only for non-US founders who also requested an expedited EIN. See [Non-US founders](/api/non-us-formation).
  </Accordion>

  <Accordion title="How are deliveries retried?">
    If a delivery fails, doola retries up to **5 times, at 1 minute, 15 minutes, 1 hour, 12 hours, and 24 hours**.
  </Accordion>

  <Accordion title="What if my endpoint keeps failing?">
    After all retries are exhausted, doola automatically disables your webhook endpoint and sends a final `partner_webhook_disabled` event. Once you have fixed your endpoint, re-enable delivery in the Partner Portal.
  </Accordion>

  <Accordion title="Can I set or change my own webhook URL?">
    Yes. Set your webhook URL in the Partner Portal. Generating or rotating the webhook signing secret stays a doola step, since it is a one-time-view value and rotating it is a cutover for your signature verification.
  </Accordion>

  <Accordion title="Can I see webhook delivery logs?">
    Yes. Every delivery attempt is visible in the Partner Portal (timestamp, event name, HTTP status, attempt number).
  </Accordion>

  <Accordion title="How do I verify a webhook is really from doola?">
    Each delivery is signed with an `x-doola-signature` header, an HMAC-SHA256 hex digest of the raw request body, keyed with your webhook signing secret. Recompute it on your side and compare using a constant-time comparison (for example `timingSafeEqual` or `compare_digest`), never plain string equality.
  </Accordion>
</AccordionGroup>

<Info>
  In rare cases you may receive a duplicate `document_*` event for the same document (for example when ops re-issues a document after an IRS correction). Handle document events idempotently using `documentId`.
</Info>

## Partner Portal

<AccordionGroup>
  <Accordion title="What is the Partner Portal?">
    The Partner Portal (`partners-portal.doola.com`) is a ready-to-use web dashboard for your team, with no technical setup, just log in. It shows a searchable list of all your companies and customers, full company details (status, EIN, filing date, state, entity type, members, addresses), a Formation / EIN / Registered Agent status stepper, downloadable documents, and any notes left by the doola team. It is also where you self-manage your API keys and webhook URL, and review delivery logs.

    Company and customer data is read-only in the portal. To create or change those, use the API.
  </Accordion>

  <Accordion title="Is the portal white-labeled?">
    The portal currently shows doola branding. White-labeling is not a standard offering today, but can be discussed for enterprise partners case by case. If you want a fully custom experience, build your own UI on top of the API.
  </Accordion>

  <Accordion title="Can my users see their own company status?">
    Not directly. doola does not host a customer-facing interface for partner-created companies. You build whatever your end-users see, pulling current status from the API and displaying it in your own product.
  </Accordion>
</AccordionGroup>

## Data and privacy

doola stores the registration info you submit (email, first name, last name, country of residence, and optionally phone number) plus the company formation details.

SSNs, when submitted as part of responsible-party or member information, are **masked in all API responses**. Only a redacted version is ever returned (for example `****-**-1234`). The raw value is stored securely and used only for formation.

## Quick reference: available vs not

| Capability                                          | Available?                                            |
| --------------------------------------------------- | ----------------------------------------------------- |
| Form LLCs via API                                   | ✅ Yes                                                 |
| Form C-Corps via API                                | ✅ Yes                                                 |
| Expedited EIN                                       | ✅ Yes (non-US founders; billed per usage)             |
| Register and list or search customers and companies | ✅ Yes                                                 |
| Download company documents                          | ✅ Yes                                                 |
| Real-time webhooks on key events                    | ✅ Yes                                                 |
| Self-service API key management                     | ✅ Yes                                                 |
| Self-service webhook configuration                  | ✅ Yes                                                 |
| Webhook delivery logs                               | ✅ Yes                                                 |
| Sandbox environment                                 | ✅ Yes                                                 |
| Trigger formation and EIN completion in sandbox     | ✅ Yes ([sandbox playground](/api/sandbox-playground)) |
| Partner Portal                                      | ✅ Yes                                                 |
| Multiple team members on the portal                 | ✅ Yes                                                 |
| Name-availability check via API                     | ❌ Coming soon (submit 3 name options)                 |
| Self-serve initial signup                           | ❌ doola provisions your account                       |
| Edit companies or customers through the portal      | ❌ Read-only, use the API                              |
| Customer-facing portal                              | ❌ You build your own                                  |
| White-label portal                                  | ❌ Not standard (enterprise case by case)              |

## Related docs

* [Company formation](/api/formation): entity types, required fields, status lifecycle
* [Webhooks](/api/webhooks): setup, events, signature verification
* [Sandbox playground](/api/sandbox-playground): complete formation and EIN issuance on demand in sandbox
* [Errors](/api/errors): error codes and handling
* [Domain objects](/api/domain-objects): field-level reference