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

# New company names needed

> Handle FORMATION_NAME_OPTIONS_EXHAUSTED by submitting replacement company names after the state rejects every option.

`FORMATION_NAME_OPTIONS_EXHAUSTED` is raised when the state rejects **every** company name you submitted. The formation stops there until you send replacements, and the `reason` on the action usually names the exact names that were turned down, so you can put them in front of your user.

You are told by the `company_name_options_required` webhook. See [Required actions](/api/required-actions) for the payload, the status model, and how to read actions back.

## The flow

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

    TP-->>D: Rejects every name option
    D->>D: Opens a required action
    D-->>P: webhook company_name_options_required

    P->>U: Ask for new company names
    U->>P: New names
    P->>D: Submit resolution
    D-->>P: status: submitted

    D->>TP: doola refiles with the state

    alt State accepts a name
        TP-->>D: Accepted
        D->>D: Action resolved (closed)
        D-->>P: Formation continues
    else State rejects again
        TP-->>D: Rejected
        D->>D: Action rejected (closed)
        D-->>P: webhook company_name_options_required (new action)
    end
```

Refiling and the accept-or-reject outcome are handled by doola's operations team, so expect an action to sit in `submitted` for as long as the state takes.

## Submitting new names

One endpoint resolves every resolvable action, and `actionCode` says which one you are answering — it must match the action's own `actionCode`, or the request is rejected.

```bash theme={null}
curl https://api.test.doola.com/v1/partner/companies/{companyId}/required-actions/{requiredActionId}/resolution \
  -X POST \
  -H "Authorization: dk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "actionCode": "FORMATION_NAME_OPTIONS_EXHAUSTED",
    "nameOptions": [
      { "name": "Acme Ventures", "entityTypeEnding": "LLC", "position": 1 },
      { "name": "Acme Labs", "entityTypeEnding": "LLC", "position": 2 }
    ]
  }'
```

The response is the updated action, `status: "submitted"`, with its full `history` — you do not need a follow-up read.

The names replace the company's existing options immediately, and the first-preference option also becomes the company's `name` and `entityTypeEnding`. A company you read back afterwards reflects what you just sent, so refresh anything you cached.

<Note>
  This endpoint takes no `Idempotency-Key`. Two identical submissions apply the names twice and append two `submitted` steps, so send it once and treat a network timeout as "read the action back" rather than "retry blindly".
</Note>

## Name option rules

The same rules as [creating a company](/api/domain-objects#name-option), because these names go to the state the same way.

<Steps>
  <Step title="One to three names, in preference order">
    `position` sets the order and `1` is the first choice; omit it and doola uses the order you sent. The first preference becomes the company's name if the state accepts it.
  </Step>

  <Step title="Send a recognised ending">
    `entityTypeEnding` must be one of the endings listed under [Name option](/api/domain-objects#name-option). This check is case-sensitive, so send `LLC`, not `llc`.
  </Step>

  <Step title="The ending must match the company's entity type">
    An LLC takes an LLC ending and a CCorp takes a corporate ending. An ending that is recognised but belongs to the other entity type is rejected rather than filed.
  </Step>
</Steps>

Breaking any of these comes back as `400 E_VALIDATION_FAILED`, with the detail under `error.fields.nameOptions` — except an ending that is recognised but belongs to the wrong entity type, which is `400 E_NAME_OPTIONS_INVALID`. The [full error table](/api/required-actions#errors) lists the rest.

## If the state rejects again

The action closes as `rejected` and doola raises a **new** action with the same code and a fresh `requiredActionId`, which arrives as another `company_name_options_required` webhook. Nothing reopens, so resolve against the new id — this is why your records should be keyed on `requiredActionId` rather than on the company.

## After it resolves

Once a name is accepted the action closes as `resolved` and the formation continues from where it stopped.

One thing follows on: if your founder had **already signed an SS-4** against the old name, that signature is now void, and doola raises an [SS-4 signature needed again](/api/required-actions/ss4-reset) action for the replacement. Expect it as a second, separate webhook.