> ## 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.
# Domain objects
> The shapes and business rules behind customer and company formation requests.
This page explains the objects and rules you assemble a request from. The API reference has the complete, generated field list and types; this page focuses on the relationships and validation rules that the schema alone does not spell out.
## Customer
| Field | Required | Notes |
| -------------------- | -------- | ----------------------------------------------------------------------- |
| `email` | Yes | Valid email address |
| `firstName` | Yes | 1 to 50 non blank characters |
| `lastName` | Yes | 1 to 50 non blank characters |
| `countryOfResidence` | Yes | ISO 3166-1 alpha-3 code, for example `USA`. See the countries reference |
| `phoneNumber` | No | Include the international code, for example `+12125550100` |
## Company formation
| Field | Required | Notes |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `doolaCustomerId` | Yes | The id returned by Create customer |
| `entityType` | No | `LLC` (default) or `CCorp`. Determines which member and valuation fields apply |
| `state` | Yes | Two letter US state, for example `WY`. See the states reference |
| `naicsCode` | Yes | A valid code from the NAICS reference |
| `description` | Yes | Business description, up to 250 characters |
| `nameOptions` | Yes | 1 to 3 ordered name preferences |
| `members` | Conditional | LLC only. Required for an LLC; ownership must total exactly 100. Omit for a CCorp |
| `executiveMembers` | Conditional | CCorp only. Required for a CCorp; omit for an LLC |
| `ccorpValuation` | Conditional | CCorp only. Required for a CCorp; omit for an LLC |
| `responsibleParty` | Yes | The person responsible for the EIN application |
| `addresses` | Yes | Exactly two: a mailing address and a business address |
| `requestedServices` | No | Per-service variant overrides. Only the EIN service is configurable; see [Expedited EIN](/api/expedited-ein) |
`entityType` defaults to `LLC`. A `CCorp` swaps `members` for `executiveMembers` and `ccorpValuation` (see below).
**US vs non-US founder is derived from the `ssn` field**, which holds a US tax ID (SSN or ITIN). If no `member`, `executiveMember`, or `responsibleParty` supplies one, doola treats the founder as non-US and the response carries a pending SS-4 in `signatureRequirements`. If anyone supplies an SSN or ITIN, `signatureRequirements` is empty. See [Non-US founders](/api/non-us-formation).
### Name option
Provide up to three in order of preference. doola uses the first name that clears the state's availability check. If the state rejects every one of them, doola raises a [required action](/api/required-actions/name-options) asking you for new options.
| Field | Required | Notes |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | Company name without the entity suffix |
| `entityTypeEnding` | Yes | Must match the entity type. LLC: `LLC`, `L.L.C`, `L.L.C.`, `Limited Liability Company`. CCorp: `Inc`, `Inc.`, `Incorporated`, `Corp.`, `Corporation`, `C Corp`, `C Corporation`, `CCorp`, `Company` |
### Company address
Submit one entry per role. There must be exactly two: a `mailing` address and a `business` address.
| Field | Required | Notes |
| ---------- | ----------- | ------------------------------------------------------------------------------------ |
| `provider` | Yes | `customer` (you supply the address) or `registeredAgent` (doola supplies it) |
| `type` | Yes | `mailing` or `business` |
| `address` | Conditional | Required when `provider` is `customer`. Omit it when `provider` is `registeredAgent` |
### Address
| Field | Required | Notes |
| ------------ | ----------- | ----------------------------------------------------------- |
| `line1` | Yes | Street address line 1 |
| `line2` | No | Optional |
| `city` | Yes | City |
| `state` | Yes | State, two letter abbreviation for the US |
| `postalCode` | Yes | Postal or ZIP code |
| `country` | Yes | ISO 3166-1 alpha-3 code, for example `USA` |
| `phone` | Conditional | Optional on a plain address, required on a member's address |
### Responsible party
The person responsible for the company's EIN application.
| Field | Required | Notes |
| ---------------- | -------- | ------------------------------ |
| `legalFirstName` | Yes | Legal first name |
| `legalLastName` | Yes | Legal last name |
| `address` | Yes | See Address |
| `ssn` | No | Optional. Format `XXX-XX-XXXX` |
| `email` | No | Optional, valid email |
### Member
The sum of `ownershipPercent` across all members must equal exactly 100.
| Field | Required | Notes |
| ------------------ | -------- | ----------------------------------------------- |
| `legalFirstName` | Yes | Legal first name |
| `legalLastName` | Yes | Legal last name |
| `contactFullName` | Yes | Full name as it should appear on filings |
| `isNaturalPerson` | Yes | `true` for an individual, `false` for an entity |
| `ownershipPercent` | Yes | Must total 100 across all members |
| `address` | Yes | See Address. `phone` is required here |
| `ssn` | No | Optional. Format `XXX-XX-XXXX` |
### Executive member (CCorp)
Supplied as `executiveMembers` and required for a `CCorp`. The list must include at least one President, Secretary, Treasurer, and Director. President, Secretary, and Treasurer may each appear only once; Director may repeat.
| Field | Required | Notes |
| ---------------- | -------- | -------------------------------------------------------- |
| `type` | Yes | One of `President`, `Secretary`, `Treasurer`, `Director` |
| `legalFirstName` | Yes | Legal first name |
| `legalLastName` | Yes | Legal last name |
| `address` | Yes | See Address |
| `ssn` | No | Optional. Format `XXX-XX-XXXX` |
### Share structure (CCorp)
Supplied as `ccorpValuation` and required for a `CCorp`.
| Field | Required | Notes |
| ------------ | -------- | ------------------------------------------- |
| `noOfShares` | Yes | Number of authorized shares. Greater than 0 |
| `shareValue` | Yes | Par value per share in USD. Greater than 0 |
### Requested service
Supplied as `requestedServices`, optional. Requests a specific variant for one of the company's services; today only the expedited EIN, available for non-US founders. See [Expedited EIN](/api/expedited-ein) for availability and errors.
| Field | Required | Notes |
| --------- | -------- | --------------------------------------------------------------------------- |
| `service` | Yes | Only `EinCreation` is supported |
| `variant` | Yes | `Standard` or `Expedite`. `Standard` behaves the same as omitting the entry |
## Document
Returned by the document endpoints. `downloadUrl` is present only on the single document endpoint and is a temporary signed URL valid for about one hour.
| Field | Notes |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Document id |
| `companyId` | Parent company id |
| `name` | File name |
| `contentType` | MIME type, for example `application/pdf` |
| `documentType` | Common values: `ArticlesOfOrganization`, `EinLetter`, `Mail`, `CorporateBylaws` (CCorp), `OperatingAgreement` (LLC), `SignedSS4` (non-US founders), and `SignedForm8821` (non-US founders on an expedited EIN). Not a closed set — other document types can appear over a company's lifetime |
| `createdAt` | Upload timestamp |
| `lastModified` | Last modification timestamp |
| `downloadUrl` | Temporary signed download URL (single document endpoint only) |
## Signature requirement
Returned on the company as `signatureRequirements` by both Create company and Retrieve company. The array is always present: an `SS4` entry for a non-US founder (plus a `FORM8821` entry when that founder is on an expedited EIN), or empty for a US founder. See [Non-US founders](/api/non-us-formation).
| Field | Values | Notes |
| -------------- | ---------------------- | --------------------------------------------------------- |
| `documentType` | `SS4`, `FORM8821` | The document the founder must sign |
| `status` | `PENDING`, `COMPLETED` | `PENDING` until that document is signed, then `COMPLETED` |
## Required action
Something doola needs from you before a company's formation can continue. Announced by webhook and readable per company or across your whole tenant. See [Required actions](/api/required-actions).
| Field | Values | Notes |
| ------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `requiredActionId` | | Identifier for the action. Key your records on it, and read the action against it |
| `doolaCompanyId` | | The company the action is on |
| `actionCode` | `FORMATION_NAME_OPTIONS_EXHAUSTED`, `FORMATION_SIGNATURE_SS4_RESET` | What is needed. Branch on this, never on `reason` |
| `actionName` | | Short human-readable label for the action |
| `status` | `created`, `delivered`, `delivery_failed`, `submitted`, `resolved`, `rejected` | The last thing that happened to the action |
| `reason` | | Explanation written for your user to read |
| `open` | `true`, `false` | `false` once `resolved` or `rejected`; a closed action never reopens |
| `updatedAt` | | When the action last changed |
| `history` | | Every step, oldest first. Returned by the single-action read and by the resolution endpoint; omitted from both list responses |
## Signature session
Returned by the create-signature-session endpoint. Holds the short lived, whitelabeled signing link to present to the founder.
| Field | Notes |
| -------------- | ------------------------------------------------------------------------------------- |
| `id` | Identifier for the signing session |
| `url` | doola signing link to embed or share. Expires at `expiresAt` |
| `documentType` | `SS4`, `FORM8821` |
| `expiresAt` | When `url` stops working (two hours after issuance). Request a new session after this |