Company Formation

Company Formation is the incorporation primitive. Naive orchestrates LLC formation through Doola, pulling verified PII from Footprint’s vault at submission time so sensitive data (SSN, DOB, addresses) never touches your database. Identity verification (KYC) for all founders must be completed before formation can proceed.

CLI First

# 1) Get NAICS options
naive formation naics-codes

# 2) Submit formation to create $249 checkout URL
naive formation submit --verification-id <verification-id> --state WY --naics <naics-code-id> --description "AI-powered business automation platform" --names '[{"name":"Acme Tech","entity_type_ending":"LLC"}]'

# 3) After payment, execute submission to Doola
naive formation execute <formation-id>

Tools

Tool	Type	Description	Cost
`list_naics_codes`	Info	List NAICS industry codes	Free
`submit_formation`	Core	Step 1: Validate KYC + create $249 Stripe Checkout	Free (creates checkout)
`retry_formation_payment`	Core	Regenerate Stripe Checkout if it expired	Free
`execute_formation`	Core	Step 2: Submit to Doola after payment	$249 paid via Stripe
`list_formations`	Info	List all formation requests	Free
`get_formation`	Info	Get formation status and details	Free
`formation_documents`	Info	List formation documents	Free
`formation_document_download`	Info	Get document download URL	Free

Prerequisites

Completed identity verification — all founders must have passed KYC via the verification primitive. The verification’s ready_for_formation must be true.
NAICS code — select the industry code for your business from the NAICS codes list.
Business details — entity type, state, company name options, description, and (optionally) mailing address.
Payment — $249 USD via Stripe Checkout.

Workflow

1. Complete KYC for all founders
   └─ GET /v1/verification/:id → ready_for_formation: true

2. Select NAICS code
   └─ GET /v1/formation/naics-codes → pick naics_code_id

3. Submit formation (creates Stripe Checkout)
   └─ POST /v1/formation (business info + verification_id)
   └─ Returns checkout_url for $249 payment

4. User pays via Stripe Checkout
   └─ Webhook updates payment_status to "paid"

5. Execute formation (submits to Doola)
   └─ POST /v1/formation/:id/submit
   └─ PII decrypted from Footprint vault and sent to Doola

6. Track progress
   └─ GET /v1/formation/:id → status updates

7. Download documents when ready
   └─ GET /v1/formation/:id/documents → Articles of Organization, EIN Letter

Idempotency & Recovery

Duplicate prevention. If you call POST /v1/formation for a verification that already has a non-failed formation, the API returns duplicate_record with the existing formation’s ID. This prevents accidental double-billing. Call GET /v1/formation/:id on the existing one to recover its state. Failed before payment. If a formation hits failed status with payment_status: "unpaid" (e.g. checkout session expired), use POST /v1/formation/:id/retry-payment to generate a fresh checkout URL. The business info is preserved. Failed after payment. If a formation hits failed after payment was confirmed (Doola rejected the submission), do not create a new formation — the original $249 is held against that record. Contact support@usenaive.ai for resolution. You can also retry the Doola submission with POST /v1/formation/:id/submit, which may resolve transient errors.

Pricing

LLC formation costs $249 USD, paid upfront via Stripe Checkout. The fee covers:

Doola formation service
State filing fees
Registered agent service
EIN application
All required legal documents

Payment is collected via Stripe Checkout when you call POST /v1/formation. The formation only proceeds to Doola after payment is confirmed.

Listing NAICS Codes

curl https://api.usenaive.ai/v1/formation/naics-codes \
  -H "Authorization: Bearer nv_sk_your_key"

Submitting Formation

curl -X POST https://api.usenaive.ai/v1/formation \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "3dcde53f-abaa-4bb6-a5b5-2d704fad6c19",
    "entity_type": "LLC",
    "state": "WY",
    "naics_code_id": "2o8v0kcaCWyPyi3LJFsCiTCFSyk",
    "description": "AI-powered business automation platform",
    "name_options": [
      { "name": "Acme Tech", "entity_type_ending": "LLC" },
      { "name": "Acme Technologies", "entity_type_ending": "LLC" },
      { "name": "Acme Solutions", "entity_type_ending": "L.L.C." }
    ],
    "mailing_address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US",
      "phone": "+14155551234"
    }
  }'

Response (201):

{
  "id": "formation-uuid",
  "status": "awaiting_payment",
  "payment_status": "unpaid",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_xxx...",
  "checkout_session_id": "cs_test_xxx",
  "price_usd": "$249",
  "entity_type": "LLC",
  "state": "WY",
  "name_options": [...],
  "next_step": "Open the checkout_url to complete payment, then call POST /v1/formation/:id/submit to submit to Doola"
}

PII fields (SSN, DOB, member addresses) are not included in the request body. They are decrypted from Footprint’s vault during the execute step, after payment is confirmed. This ensures sensitive data never persists in Naive’s database.

Parameters

Param	Type	Required	Description
`verification_id`	string	Yes	UUID of a completed KYC verification
`entity_type`	string	Yes	`"LLC"`
`state`	string	Yes	2-letter US state code (e.g. `"WY"`, `"DE"`)
`naics_code_id`	string	Yes	From `GET /v1/formation/naics-codes`
`description`	string	Yes	Business description (max 256 chars)
`name_options`	array	Yes	At least 1 name option (recommend 3 for availability)
`mailing_address`	object	No	Optional. Defaults to primary member’s KYC address if not provided.

Executing Formation (After Payment)

After the user pays via the checkout URL, the Stripe webhook updates payment_status to paid. Then call:

curl -X POST https://api.usenaive.ai/v1/formation/formation-uuid/submit \
  -H "Authorization: Bearer nv_sk_your_key"

Response:

{
  "id": "formation-uuid",
  "doola_customer_id": "doola-customer-id",
  "doola_company_id": "doola-company-id",
  "status": "submitted",
  "payment_status": "paid",
  "entity_type": "LLC",
  "state": "WY"
}

This step:

Verifies payment_status === "paid" (returns invalid_input error if not)
Creates a Doola customer
Decrypts PII from Footprint vault
Maps fields to Doola schema
Submits the formation to Doola

Name Options

Provide multiple name options in case your first choice is unavailable in the state. Each option needs:

Field	Description
`name`	Company name without entity ending
`entity_type_ending`	`"LLC"`, `"L.L.C"`, `"L.L.C."`, or `"Limited Liability Company"`

Formation Statuses

Status	Meaning
`awaiting_payment`	Created, waiting for $249 Stripe Checkout payment
`pending`	Payment received, ready for execute step
`submitted`	Submitted to Doola, formation in progress
`formation_completed`	Formation complete, documents being generated
`failed`	Formation failed (check `doola_error`)

Payment Statuses

Status	Meaning
`unpaid`	Stripe Checkout created but not paid
`paid`	Payment confirmed, formation can proceed
`refunded`	Payment was refunded (formation cancelled)

Documents

After formation completes, documents become available:

Document Type	Description
`ArticlesOfOrganization`	Filed articles with the state
`EinLetter`	IRS EIN assignment letter
`Mail`	Business mail documents

# List documents
curl https://api.usenaive.ai/v1/formation/formation-uuid/documents \
  -H "Authorization: Bearer nv_sk_your_key"

# Get download URL
curl https://api.usenaive.ai/v1/formation/formation-uuid/documents/doc-id \
  -H "Authorization: Bearer nv_sk_your_key"

Document download URLs are temporary signed URLs that expire after approximately 1 hour. Download immediately or re-fetch the URL when needed.

Error Handling

Error	Cause	Recovery
`feature_not_configured`	DOOLA_API_KEY not set	Configure env var
`invalid_input`	KYC not completed	Complete verification first
`invalid_input`	Missing required fields	Check parameters
`resource_not_found`	Formation or verification not found	Check UUIDs
`provider_error`	Doola API rejected the request	Check field validation

Typical Workflow

Agent receives task: "Incorporate my company as a Wyoming LLC"
    │
    ├─ GET /v1/verification/:id                    → Confirm KYC passed
    │   → ready_for_formation: true
    │
    ├─ GET /v1/formation/naics-codes               → Find industry code
    │   → naicsCodeId: "2o8v0kcaCWyPyi3LJFsCiTCFSyk"
    │
    ├─ POST /v1/formation                          → Submit (creates Stripe Checkout)
    │   { verification_id, state: "WY", ... }
    │   → status: awaiting_payment, checkout_url
    │
    ├─ User opens checkout_url and pays $249       → Stripe webhook fires
    │   → payment_status: paid, status: pending
    │
    ├─ POST /v1/formation/:id/submit               → Execute formation
    │   → id: formation-uuid, status: submitted
    │
    ├─ GET /v1/formation/:id                       → Check progress
    │   → status: submitted (days/weeks)
    │
    ├─ GET /v1/formation/:id                       → Check again
    │   → status: formation_completed
    │
    ├─ GET /v1/formation/:id/documents             → List documents
    │   → ArticlesOfOrganization, EinLetter
    │
    └─ GET /v1/formation/:id/documents/:docId      → Download
        → downloadUrl (signed, 1hr expiry)

Getting Started

Primitives

CLI First

Tools

Prerequisites

Workflow

Idempotency & Recovery

Pricing

Listing NAICS Codes

Submitting Formation

Parameters

Executing Formation (After Payment)

Name Options

Formation Statuses

Payment Statuses

Documents

Error Handling

Typical Workflow

Getting Started

Primitives

Documentation Index

​CLI First

​Tools

​Prerequisites

​Workflow

​Idempotency & Recovery

​Pricing

​Listing NAICS Codes

​Submitting Formation

​Parameters

​Executing Formation (After Payment)

​Name Options

​Formation Statuses

​Payment Statuses

​Documents

​Error Handling

​Typical Workflow

CLI First

Tools

Prerequisites

Workflow

Idempotency & Recovery

Pricing

Listing NAICS Codes

Submitting Formation

Parameters

Executing Formation (After Payment)

Name Options

Formation Statuses

Payment Statuses

Documents

Error Handling

Typical Workflow