Domain objects

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
`industry`	Yes	An exact label from the NAICS reference. See Choosing an industry
`description`	Yes	Business description, up to 50 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

entityType defaults to LLC. A CCorp swaps members for executiveMembers and ccorpValuation (see below).

Signing requirements use the ssn field, which holds an SSN or ITIN. Under doola’s partner workflow, a valid SSN on any member, executiveMember, or responsibleParty waives formation signatures. An ITIN does not: ITIN-only companies require SS-4 and, for expedited EIN, Form 8821. This checks format, not issuance, citizenship, or tax residency. Read signatureRequirements rather than deriving the answer yourself; see the signing guide.

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 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	SSN or ITIN. Optional. Nine ASCII digits or `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	SSN or ITIN. Optional. Nine ASCII digits or `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	SSN or ITIN. Optional. Nine ASCII digits or `XXX-XX-XXXX`

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 when no member, executive member, or responsible party supplies a valid SSN. ITIN-only companies are eligible. See 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` and `SignedForm8821` (when required by the signing workflow). 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 when no member, executive member, or responsible party supplies a valid SSN (plus FORM8821 for expedited EIN). An ITIN does not waive signing. Otherwise the array is empty unless Form 8821 was separately requested. A FORM8821 entry also appears, for any founder, once doola has asked for one. See SS-4 and Form 8821 signing.

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.

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`, `FORMATION_SIGNATURE_FORM8821_REQUIRED`	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

Get started

Core concepts

Reference

API reference

Help

Updates

Customer

Company formation

Name option

Company address

Address

Responsible party

Member

Executive member (CCorp)

Requested service

Document

Signature requirement

Required action

Signature session

​Customer

​Company formation

​Name option

​Company address

​Address

​Responsible party

​Member

​Executive member (CCorp)

​Share structure (CCorp)

​Requested service

​Document

​Signature requirement

​Required action

​Signature session

Customer

Company formation

Name option

Company address

Address

Responsible party

Member

Executive member (CCorp)

Share structure (CCorp)

Requested service

Document

Signature requirement

Required action

Signature session