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

# doola Partner API

> Form US companies for your customers and track them to completion, programmatically.

The doola Partner API lets you create customers, submit company formations (LLC or C-Corp), retrieve formation documents, and look up reference data. This guide gets you from zero to your first formation in minutes.

## What you need

<Card title="Before your first request" icon="key">
  * An **API key** for the environment you are targeting, provided by the doola team (looks like `dk_test_...` for sandbox or `dk_live_...` for production).
  * A **webhook signing secret**, used to verify incoming webhook events.
  * Any REST client (curl, Postman, your backend HTTP library).
</Card>

Don't have credentials yet? [Get API access](https://www.doola.com/partner-with-us/) and the doola team will get you set up.

## Environments

| Environment | Base URL                     |
| ----------- | ---------------------------- |
| Sandbox     | `https://api.test.doola.com` |
| Production  | `https://api.doola.com`      |

<Note>
  Always build and test against sandbox first. Sandbox keys never trigger real state filings or charges.
</Note>

## Your first call

Authenticate every request with your API key in the `Authorization` header.

```bash theme={null}
curl https://api.test.doola.com/v1/partner/customers \
  -X POST \
  -H "Authorization: dk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNumber": "+12125550100",
    "countryOfResidence": "USA"
  }'
```

A successful response returns a `doolaCustomerId`. Save it: you will need it to submit a company formation.

## How formation works

Formation is a two step flow, then asynchronous progress delivered over webhooks.

<Steps>
  <Step title="Create a customer">
    Call Create customer with the person's details. You get back a `doolaCustomerId`. One customer can own many companies.
  </Step>

  <Step title="Submit a company formation">
    Call Create company with that `doolaCustomerId` and the company details. Set `entityType` to `LLC` (the default) or `CCorp` — see [Company formation](/api/formation) for what each one needs. This starts the formation.
  </Step>

  <Step title="Track progress with webhooks">
    Formation is asynchronous. Do not poll. Subscribe to webhook events to learn when formation completes and documents are ready.
  </Step>
</Steps>

## Key concepts

* **Idempotency.** The create endpoints require an `Idempotency-Key` header. Use a unique key per logical operation. Retrying with the same key and body is safe and never duplicates. If a create fails, the key is released — fix the request and retry with the same key. Once a create succeeds, reusing its key with a different body returns `409 E_IDEMPOTENCY_KEY_REUSED`. See [Authentication](/api/authentication#idempotency).
* **Consistent errors.** Every error carries a machine readable `code`, so you can branch on it without parsing strings. See [Errors](/api/errors).
* **Reference data.** Country, state, NAICS, and fee lookups live in the API reference so your forms always submit valid values.
* **Sandbox playground.** Two sandbox-only endpoints complete the formation and EIN milestones on demand, firing the real webhooks, so you can exercise your whole integration without waiting on the state or the IRS. See [Sandbox playground](/api/sandbox-playground).
* **Non-US founders.** doola forms US companies for founders anywhere in the world. A non-US founder signs an SS-4 (and, for an expedited EIN, a Form 8821) before the EIN is issued, and the company response tells you when that applies. See [Non-US founders](/api/non-us-formation).
* **Expedited EIN.** Partners whose partner agreement includes Expedited EIN can request prioritized EIN processing for non-US founders at company creation. See [Expedited EIN](/api/expedited-ein).