> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpalm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Form an LLC

> > **⚠️ Early access** — This endpoint is in preview and may change in backwards-incompatible ways before it is marked stable. Avoid depending on it in production, and [reach out](mailto:support@getpalm.com) before building on it.

Form a new LLC by submitting a formation filing to the state.

**What gets created.** The formation filing, plus a business record in your Palm account (legal name, entity type, jurisdiction, and principal address). Everyone you list in `organizers` and `initial_governing_persons` is also created as a user and linked to the business as an owner.

**Add-ons.** Pass `registered_agent` to use your own; omit it to have Palm act as the registered agent. Pass `ein` to apply for an EIN once the formation completes. Each add-on appears under `related_items` and progresses independently — EIN as a `filing`, the Palm registered agent as a `registered_agent` (tracked at `GET /business/:id/registered-agent`).

**Jurisdiction-specific fields.** Some states require extra fields. Send them as additional top-level properties — the [formation requirements endpoint](/api-reference/v1/filing/get-formation-requirements) lists what a given state expects.

**Result.** Returns the filing in `queued` status. It then moves through `ready_to_file` → `processing` → `filed` → `completed`, sending a `filing.*` webhook at each step. Once `completed`, the state registration number is on `filing.result.registration_number`.



## OpenAPI

````yaml /api-reference/v1/openapi.json post /v1/filing/formation/llc
openapi: 3.0.0
info:
  title: Palm Partner API
  description: >-
    The Palm API is identity verification and compliance infrastructure for US
    businesses: onboard businesses, verify businesses and people (KYB/KYC)
    against authoritative sources, monitor them for changes in real time, and
    act on their behalf through filings, formation, and registered agent
    services.
  version: '1.0'
  contact:
    name: Palm Support
    url: https://getpalm.com
    email: support@getpalm.com
  termsOfService: https://getpalm.com/terms
  license:
    name: Proprietary
    url: https://getpalm.com/license
servers:
  - url: https://api.getpalm.com
    description: Production
security: []
tags:
  - name: Registry
    description: Search business registries
  - name: Business
    description: Manage the businesses in your portfolio
  - name: User
    description: Manage the people in your portfolio
  - name: Verification
    description: Identity and business verification
  - name: Monitor
    description: Continuous monitoring of businesses
paths:
  /v1/filing/formation/llc:
    post:
      tags:
        - Filing
      summary: Form an LLC
      description: >-
        > **⚠️ Early access** — This endpoint is in preview and may change in
        backwards-incompatible ways before it is marked stable. Avoid depending
        on it in production, and [reach out](mailto:support@getpalm.com) before
        building on it.


        Form a new LLC by submitting a formation filing to the state.


        **What gets created.** The formation filing, plus a business record in
        your Palm account (legal name, entity type, jurisdiction, and principal
        address). Everyone you list in `organizers` and
        `initial_governing_persons` is also created as a user and linked to the
        business as an owner.


        **Add-ons.** Pass `registered_agent` to use your own; omit it to have
        Palm act as the registered agent. Pass `ein` to apply for an EIN once
        the formation completes. Each add-on appears under `related_items` and
        progresses independently — EIN as a `filing`, the Palm registered agent
        as a `registered_agent` (tracked at `GET
        /business/:id/registered-agent`).


        **Jurisdiction-specific fields.** Some states require extra fields. Send
        them as additional top-level properties — the [formation requirements
        endpoint](/api-reference/v1/filing/get-formation-requirements) lists
        what a given state expects.


        **Result.** Returns the filing in `queued` status. It then moves through
        `ready_to_file` → `processing` → `filed` → `completed`, sending a
        `filing.*` webhook at each step. Once `completed`, the state
        registration number is on `filing.result.registration_number`.
      operationId: formLlc
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LlcFormationRequest'
      responses:
        '201':
          description: Formation filing created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filing'
        '400':
          description: Validation error
        '409':
          description: Business name not available
      security:
        - ApiKey: []
components:
  schemas:
    LlcFormationRequest:
      type: object
      properties:
        jurisdiction:
          type: string
          description: Jurisdiction (ISO 3166-2)
          example: US-NC
        entity_name:
          type: string
          description: Legal name of the LLC being formed
          example: Acme Holdings LLC
        purpose:
          type: string
          description: >-
            Purpose clause for the articles of organization. Some states require
            user-supplied text; others use a statutory boilerplate clause that
            Palm fills in automatically. Distinct from the EIN
            principal_activity / principal_activity_detail fields, which
            describe the business's actual activity for IRS purposes.
          example: Any lawful purpose
        phone:
          type: string
          description: Business phone number
          example: 919-555-1234
        email:
          type: string
          description: Business email address
          example: info@acme.com
        website:
          type: string
          description: Business website
          example: https://acme.com
        effective_date:
          type: string
          description: >-
            Delayed effective date (YYYY-MM-DD). If omitted, defaults to the
            date the formation request is received by Palm.
          example: '2026-05-01'
        contact:
          description: >-
            Primary contact for questions about this filing. Used by Palm
            operations; never sent on the filing itself.
          allOf:
            - $ref: '#/components/schemas/FilingContact'
        principal_address:
          description: Principal office address
          allOf:
            - $ref: '#/components/schemas/FormationAddress'
        mailing_address:
          description: >-
            Mailing address if different from the principal office. Defaults to
            principal_address when omitted.
          allOf:
            - $ref: '#/components/schemas/FormationAddress'
        organizers:
          description: >-
            Persons or entities executing the articles of organization
            (organizers / authorized persons). At least one required.
          type: array
          items:
            $ref: '#/components/schemas/FormationParty'
        initial_governing_persons:
          description: >-
            Initial members or managers of the LLC. Optional on most state
            formation forms but useful for downstream records and filings.
          type: array
          items:
            $ref: '#/components/schemas/GoverningPerson'
        registered_agent:
          description: >-
            Registered agent. If provided, your own registered agent is used on
            the filing. If omitted, Palm provides registered agent service.
          allOf:
            - $ref: '#/components/schemas/FormationRegisteredAgent'
        ein:
          description: >-
            Bundle an EIN application with the formation. Palm submits to IRS
            after the formation succeeds.
          allOf:
            - $ref: '#/components/schemas/FormationEin'
        metadata:
          type: object
          description: >-
            Partner-defined metadata. Round-tripped on webhooks and the filing
            record.
        expedited_tier:
          type: string
          description: >-
            Expedited processing tier. Omit for standard processing. Valid
            values are jurisdiction-specific — discover them via GET
            /v1/filing/formation/requirement (`expedited_tiers`) and price them
            via GET /v1/filing/formation/fee (`expedited_tiers`). Rejected with
            400 if the value is not offered by the jurisdiction.
          example: same_day
      required:
        - jurisdiction
        - entity_name
        - purpose
        - email
        - contact
        - principal_address
        - organizers
      additionalProperties: true
    Filing:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        object:
          type: string
          description: Object type
          example: filing
          enum:
            - filing
        mode:
          type: string
          description: >-
            Whether this resource was created with test or live credentials.
            Test and live data are fully isolated — a test resource never
            appears in live results and vice versa.
          enum:
            - test
            - live
          example: live
        created_at:
          type: string
          description: ISO 8601 timestamp of when the resource was created
          format: date-time
          example: '2025-10-24T10:30:00Z'
        updated_at:
          type: string
          description: ISO 8601 timestamp of when the resource was last updated
          format: date-time
          example: '2025-10-24T15:45:00Z'
        metadata:
          type: object
          description: >-
            Store up to 50 custom key-value pairs for application-specific data.
            Useful for storing references to external systems, feature flags, or
            other custom attributes.
          additionalProperties:
            type: string
          example:
            external_id: user_123_in_my_system
            customer_tier: premium
            signup_source: mobile_app
        type:
          type: string
          description: Filing type
          enum:
            - formation
            - ein
            - amendment
            - scorp_election
        status:
          type: string
          description: Current status
          enum:
            - queued
            - ready_to_file
            - processing
            - filed
            - completed
            - rejected
            - canceled
            - failed
        entity_type:
          type: string
          description: Entity type (for formations)
          enum:
            - llc
            - pllc
            - corporation
            - pcorporation
        jurisdiction:
          type: string
          description: Jurisdiction (ISO 3166-2)
          example: US-NC
        name:
          type: string
          description: Business name for the filing
          example: Acme Holdings LLC
        expedited_tier:
          type: string
          description: >-
            Expedited processing tier requested for this filing, or null for
            standard processing. Only set on formations submitted with an
            `expedited_tier`.
          example: same_day
        business_id:
          type: string
          description: Linked business ID
          format: uuid
        result:
          description: >-
            Filing result — populated on completion, `null` until then. Shape
            depends on the filing `type`: formation → `{ registration_number,
            formation_date }`; EIN → `{ ein_number, entity_name }`. Other filing
            types have no result.
          oneOf:
            - $ref: '#/components/schemas/FormationFilingResult'
            - $ref: '#/components/schemas/EinFilingResult'
          nullable: true
        parent_filing_id:
          type: string
          description: Parent filing ID (for bundled EIN/RA)
          format: uuid
        related_items:
          type: array
          description: >-
            Bundle of obligations tracked under this formation, each with its
            own object type and status: filings (state registration, EIN) and
            the registered agent (`id` is the business, resolvable at `GET
            /business/:id/registered-agent`).
          items:
            oneOf:
              - $ref: '#/components/schemas/FilingRelatedItem'
              - $ref: '#/components/schemas/RegisteredAgentRelatedItem'
        documents:
          description: Documents associated with this filing
          type: array
          items:
            $ref: '#/components/schemas/FilingDocument'
        fee:
          description: >-
            Fee components keyed by type (base, dynamic, late, credit_card,
            ach), plus a convenience `total` grand total (assumes credit-card
            payment). Only present components are included. When `items` is set,
            it lists each evaluated rule for itemized rendering — the
            component-keyed values are the sums across those items.
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/FeeBreakdown'
        status_reason:
          type: string
          description: >-
            Reason the filing was canceled (partner request, parent off-boarded,
            duplicate, etc.). Only present when status is `canceled`.
        canceled_by:
          type: string
          description: >-
            Role that initiated the cancellation. One of: `partner`, `palm`.
            Only present when status is `canceled`.
        canceled_at:
          type: string
          description: Timestamp the filing was canceled
          format: date-time
        cases:
          description: >-
            Cases attached to this filing. One entry per partner-visible case,
            in chronological order. Each case carries a typed `request` payload
            describing what Palm needs and, once submitted, a typed `response`.
            Partners respond via `POST /v1/case/:case_id/response`. An entry
            with `status=needs_response` is an outstanding ask — its presence is
            the signal that the filing needs partner action.
          type: array
          items:
            $ref: '#/components/schemas/Case'
      required:
        - id
        - object
        - mode
        - created_at
        - updated_at
        - metadata
        - type
        - status
    FilingContact:
      type: object
      properties:
        name:
          type: string
          description: Contact name
          example: Jane Doe
        email:
          type: string
          description: Contact email
          example: jane@acme.com
        phone:
          type: string
          description: Contact phone number
          example: 919-555-1234
      required:
        - name
        - email
    FormationAddress:
      type: object
      properties:
        street_line_1:
          type: string
          example: 123 Main St
          description: Street address line 1
        street_line_2:
          type: string
          description: Apt, suite, unit, etc.
          example: Suite 200
        city:
          type: string
          description: City
          example: Raleigh
        region:
          type: string
          description: State or region code
          example: NC
        postal_code:
          type: string
          description: Postal/ZIP code
          example: '27601'
        county:
          type: string
          description: County name (required by some jurisdictions)
          example: Mecklenburg
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
      required:
        - street_line_1
        - city
        - region
        - postal_code
        - country
    FormationParty:
      type: object
      properties:
        name:
          description: Party name (person or entity)
          allOf:
            - $ref: '#/components/schemas/PartyName'
        address:
          description: Party address
          allOf:
            - $ref: '#/components/schemas/FormationAddress'
        title:
          type: string
          description: Title or capacity (e.g., "Member", "Authorized Person")
          example: Authorized Person
        email:
          type: string
          description: Email. Required by some jurisdictions (e.g. MT, WV).
          example: incorporator@example.com
        phone:
          type: string
          description: Phone. Required by some jurisdictions (e.g. WV).
          example: 919-555-1234
      required:
        - name
        - address
    GoverningPerson:
      type: object
      properties:
        name:
          description: Person or entity name
          allOf:
            - $ref: '#/components/schemas/PartyName'
        address:
          description: Address
          allOf:
            - $ref: '#/components/schemas/FormationAddress'
        role:
          type: string
          description: Whether this person is a member or a manager
          enum:
            - member
            - manager
          example: member
        email:
          type: string
          description: Email. Required by some jurisdictions (e.g. MT, LA).
          example: member@example.com
        phone:
          type: string
          description: Phone.
          example: 919-555-1234
        ssn:
          type: string
          description: >-
            Social Security Number. Required by some jurisdictions' filing
            portals (e.g. WV managers). Routed to the user vault — never
            persisted in plaintext on the filing.
          example: 123-45-6789
      required:
        - name
    FormationRegisteredAgent:
      type: object
      properties:
        type:
          type: string
          description: Whether the registered agent is a person or an organization
          enum:
            - person
            - organization
          example: person
        name:
          description: Registered agent name
          allOf:
            - $ref: '#/components/schemas/PartyName'
        address:
          description: Registered office address (must be in the formation jurisdiction)
          allOf:
            - $ref: '#/components/schemas/FormationAddress'
        mailing_address:
          description: Mailing address if different from the registered office
          allOf:
            - $ref: '#/components/schemas/FormationAddress'
        email:
          type: string
          description: Registered agent email. Required by some jurisdictions.
          example: agent@example.com
        phone:
          type: string
          description: Registered agent phone
          example: 919-555-1234
      required:
        - type
        - name
        - address
    FormationEin:
      type: object
      properties:
        responsible_party:
          description: Responsible party for the entity
          allOf:
            - $ref: '#/components/schemas/EinResponsibleParty'
        reason:
          type: string
          description: Reason for applying
          enum:
            - started_new_business
            - hired_employees
            - banking_purposes
            - changed_organization_type
            - purchased_business
            - created_trust
            - created_pension_plan
            - withholding_compliance
            - other
          example: started_new_business
        reason_detail:
          type: string
          description: Details for the reason. Required if reason is "other".
          example: Compliance with state reporting requirements
        fiscal_year_end_month:
          type: integer
          minimum: 1
          maximum: 12
          description: Closing month of accounting year. 1-12.
          example: 12
        expected_employee_count:
          description: Expected employees in next 12 months by category
          allOf:
            - $ref: '#/components/schemas/EinExpectedEmployeeCount'
        wage_date:
          type: string
          format: date
          description: >-
            Date wages will first be paid. Required if total expected employees
            > 0.
          example: '2026-04-01'
        principal_activity:
          description: >-
            Principal activity category, matching the IRS online EIN flow. Pick
            the one that best describes the business:

            - `accommodations`: hotels, motels, casino hotels

            - `construction`: contractors and construction trades

            - `finance`: banks, brokers, lenders, investment and advisory firms

            - `food_service`: restaurants, bars, catering, coffee/ice-cream
            shops

            - `health_care`: physicians, dentists, hospitals, clinics,
            mental-health practitioners

            - `insurance`: insurance carriers, agents, and brokers

            - `manufacturing`: producing goods from raw materials

            - `real_estate`: renting, building, selling, or managing property

            - `rental_and_leasing`: renting or leasing real estate or goods

            - `retail`: selling goods to consumers (online, storefront, direct,
            auction)

            - `social_assistance`: nursing homes, shelters, youth services

            - `transportation`: moving cargo or passengers

            - `warehousing`: storage and warehousing

            - `wholesale`: selling goods to businesses for resale

            - `other`: anything not covered above (consulting, repair, services,
            etc.)


            The object is discriminated by `category`; each category carries its
            own follow-up fields.
          oneOf:
            - $ref: '#/components/schemas/AccommodationsActivity'
            - $ref: '#/components/schemas/ConstructionActivity'
            - $ref: '#/components/schemas/FinanceActivity'
            - $ref: '#/components/schemas/FoodServiceActivity'
            - $ref: '#/components/schemas/HealthCareActivity'
            - $ref: '#/components/schemas/InsuranceActivity'
            - $ref: '#/components/schemas/ManufacturingActivity'
            - $ref: '#/components/schemas/RealEstateActivity'
            - $ref: '#/components/schemas/RentalAndLeasingActivity'
            - $ref: '#/components/schemas/RetailActivity'
            - $ref: '#/components/schemas/SocialAssistanceActivity'
            - $ref: '#/components/schemas/TransportationActivity'
            - $ref: '#/components/schemas/WarehousingActivity'
            - $ref: '#/components/schemas/WholesaleActivity'
            - $ref: '#/components/schemas/OtherActivity'
          discriminator:
            propertyName: category
            mapping:
              accommodations:
                $ref: '#/components/schemas/AccommodationsActivity'
              construction:
                $ref: '#/components/schemas/ConstructionActivity'
              finance:
                $ref: '#/components/schemas/FinanceActivity'
              food_service:
                $ref: '#/components/schemas/FoodServiceActivity'
              health_care:
                $ref: '#/components/schemas/HealthCareActivity'
              insurance:
                $ref: '#/components/schemas/InsuranceActivity'
              manufacturing:
                $ref: '#/components/schemas/ManufacturingActivity'
              real_estate:
                $ref: '#/components/schemas/RealEstateActivity'
              rental_and_leasing:
                $ref: '#/components/schemas/RentalAndLeasingActivity'
              retail:
                $ref: '#/components/schemas/RetailActivity'
              social_assistance:
                $ref: '#/components/schemas/SocialAssistanceActivity'
              transportation:
                $ref: '#/components/schemas/TransportationActivity'
              warehousing:
                $ref: '#/components/schemas/WarehousingActivity'
              wholesale:
                $ref: '#/components/schemas/WholesaleActivity'
              other:
                $ref: '#/components/schemas/OtherActivity'
        principal_activity_detail:
          type: string
          description: >-
            Free-text description of the principal line of merchandise sold,
            products produced, or services provided (IRS Form SS-4, line 17).
          example: Software consulting services
        has_previous_ein:
          type: boolean
          description: Has the entity previously received an EIN?
          example: false
        previous_ein:
          type: string
          description: Previous EIN if applicable. Required if has_previous_ein is true.
          example: 12-3456789
        trade_name:
          type: string
          description: Trade name / DBA if different from legal name
          example: Acme Trading Co
        form_944_election:
          type: boolean
          description: Elect to file Form 944 annually instead of Form 941 quarterly
          example: false
        members_are_married_couple:
          type: boolean
          description: >-
            Whether the two LLC members are married to each other. Required for
            a two-member LLC physically located in a community property state
            (AZ, CA, ID, LA, NM, NV, TX, WA, WI), where the IRS EIN application
            asks whether the members are husband and wife.
          example: false
        llc_classification:
          type: string
          description: >-
            Federal tax classification election for a married-couple LLC in a
            community property state (Rev. Proc. 2002-69): treat the LLC as
            single-member (disregarded entity) or multi-member (partnership).
            Required if members_are_married_couple is true.
          enum:
            - single_member
            - multi_member
          example: single_member
      required:
        - responsible_party
        - reason
        - fiscal_year_end_month
        - expected_employee_count
        - principal_activity
        - principal_activity_detail
        - has_previous_ein
    FormationFilingResult:
      type: object
      properties:
        registration_number:
          type: string
          nullable: true
          description: State-assigned registration/file number.
          example: NC-12345678
        formation_date:
          type: string
          format: date
          nullable: true
          description: Date the entity was formed (YYYY-MM-DD).
          example: '2026-06-23'
      required:
        - registration_number
        - formation_date
    EinFilingResult:
      type: object
      properties:
        ein_number:
          type: string
          nullable: true
          description: Issued Employer Identification Number.
          example: 12-3456789
        entity_name:
          type: string
          nullable: true
          description: Legal entity name the EIN was issued to.
          example: Acme Holdings LLC
      required:
        - ein_number
        - entity_name
    FilingRelatedItem:
      type: object
      properties:
        object:
          type: string
          description: Object type
          enum:
            - filing
        id:
          type: string
          description: Filing ID
          format: uuid
        type:
          type: string
          description: Filing type
          enum:
            - formation
            - ein
            - amendment
            - scorp_election
        status:
          type: string
          description: Current filing status
          enum:
            - queued
            - ready_to_file
            - processing
            - filed
            - completed
            - rejected
            - canceled
            - failed
      required:
        - object
        - id
        - type
        - status
    RegisteredAgentRelatedItem:
      type: object
      properties:
        object:
          type: string
          description: Object type
          enum:
            - registered_agent
        id:
          type: string
          description: Business ID that owns the registered-agent resource
          format: uuid
        status:
          type: string
          description: Current registered-agent status
          enum:
            - pending
            - active
            - termination_requested
            - terminated
            - failed
      required:
        - object
        - id
        - status
    FilingDocument:
      type: object
      properties:
        id:
          type: string
          description: Document ID
          format: uuid
        object:
          type: string
          description: Object type
          enum:
            - document
        type:
          type: string
          description: Document type
          example: articles_of_organization
        uploaded_at:
          type: string
          description: Upload timestamp
          format: date-time
      required:
        - id
        - object
        - type
        - uploaded_at
    FeeBreakdown:
      type: object
      properties:
        base:
          description: Base filing fee total.
          allOf:
            - $ref: '#/components/schemas/FeeAmount'
        dynamic:
          description: >-
            Variable fee total (e.g. franchise tax, share-based or expedited
            surcharges).
          allOf:
            - $ref: '#/components/schemas/FeeAmount'
        late:
          description: Late fee total.
          allOf:
            - $ref: '#/components/schemas/FeeAmount'
        credit_card:
          description: Credit-card payment surcharge total.
          allOf:
            - $ref: '#/components/schemas/FeeAmount'
        ach:
          description: ACH payment surcharge total.
          allOf:
            - $ref: '#/components/schemas/FeeAmount'
        total:
          description: >-
            Grand total across the applicable fee components — a convenience so
            you do not have to sum the breakdown yourself. Assumes a credit-card
            payment method, so it is `base + dynamic + late + credit_card` (the
            mutually-exclusive `ach` surcharge is excluded). `items` and any
            `expedited_tiers` menu are not included; a requested
            `expedited_tier` surcharge is already in `dynamic`. Always an
            estimate.
          allOf:
            - $ref: '#/components/schemas/FeeAmount'
        items:
          description: >-
            Itemized breakdown — one entry per evaluated rule. Component totals
            above are sums across these.
          type: array
          items:
            $ref: '#/components/schemas/FeeLine'
      required:
        - total
    Case:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        object:
          type: string
          description: Object type
          example: case
          enum:
            - case
        mode:
          type: string
          description: >-
            Whether this resource was created with test or live credentials.
            Test and live data are fully isolated — a test resource never
            appears in live results and vice versa.
          enum:
            - test
            - live
          example: live
        created_at:
          type: string
          description: ISO 8601 timestamp of when the resource was created
          format: date-time
          example: '2025-10-24T10:30:00Z'
        updated_at:
          type: string
          description: ISO 8601 timestamp of when the resource was last updated
          format: date-time
          example: '2025-10-24T15:45:00Z'
        metadata:
          type: object
          description: >-
            Store up to 50 custom key-value pairs for application-specific data.
            Useful for storing references to external systems, feature flags, or
            other custom attributes.
          additionalProperties:
            type: string
          example:
            external_id: user_123_in_my_system
            customer_tier: premium
            signup_source: mobile_app
        parent_type:
          type: string
          description: Type of the parent resource this case attaches to.
          enum:
            - filing
            - verification
            - business
            - session
        parent_id:
          type: string
          description: ID of the parent resource (filing_id, verification_id, etc.).
          example: fil_1a2b3c
        kind:
          type: string
          description: >-
            Typed kind of case. Each kind has its own request/response payload
            shape — see the request/response fields.
          enum:
            - missing_information
            - ra_termination
        status:
          type: string
          description: >-
            Lifecycle status. `needs_response` means the partner must act;
            `under_review` means Palm is working on it. Both are open states.
            `resolved` and `superseded` are terminal.
          enum:
            - needs_response
            - under_review
            - resolved
            - superseded
        summary:
          type: string
          description: One-line summary of the case.
          example: Additional information needed to complete your filing.
        details:
          type: string
          description: Markdown-formatted details about the case.
        request:
          description: >-
            Typed request payload — what Palm is asking for. Shape varies by
            kind.
          allOf:
            - $ref: '#/components/schemas/CaseRequestPayload'
        response:
          description: >-
            Typed response payload — what the partner submitted. Present once
            the partner has responded. Shape varies by kind.
          allOf:
            - $ref: '#/components/schemas/CaseResponsePayload'
        due_at:
          type: string
          description: Timestamp by which the case is expected to be resolved.
          format: date-time
        opened_at:
          type: string
          description: Timestamp the case was opened.
          format: date-time
        resolved_at:
          type: string
          description: Timestamp the case was resolved or superseded.
          format: date-time
        resolution_reason:
          type: string
          description: >-
            Why the case left an open state. Set when status is `resolved` or
            `superseded`.
          enum:
            - response_received
            - no_response_needed
            - parent_canceled
            - parent_completed
            - parent_failed
      required:
        - id
        - object
        - mode
        - created_at
        - updated_at
        - metadata
        - parent_type
        - parent_id
        - kind
        - status
        - summary
        - opened_at
    PartyName:
      type: object
      properties:
        type:
          type: string
          description: Whether the party is a person or an entity
          enum:
            - person
            - entity
          example: person
        first:
          type: string
          description: First name. Required when type is "person".
          example: Jane
        last:
          type: string
          description: Last name. Required when type is "person".
          example: Doe
        middle:
          type: string
          description: Middle name or initial
          example: A.
        suffix:
          type: string
          description: Suffix (e.g., Jr., Sr., III)
          example: Jr.
        entity_name:
          type: string
          description: Legal name of the entity. Required when type is "entity".
          example: Acme Holdings LLC
      required:
        - type
    EinResponsibleParty:
      type: object
      properties:
        user_id:
          type: string
          description: >-
            Existing user ID to reference as the responsible party. If provided,
            first_name, last_name, and ssn are not required in the request but
            must be present in the user vault.
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        first_name:
          type: string
          description: First name. Required if user_id is not provided.
          example: Jane
        last_name:
          type: string
          description: Last name. Required if user_id is not provided.
          example: Doe
        ssn:
          type: string
          description: SSN or ITIN. Required if user_id is not provided.
          example: 123-45-6789
    EinExpectedEmployeeCount:
      type: object
      properties:
        agricultural:
          type: integer
          minimum: 0
          description: Expected agricultural employees in next 12 months
          example: 0
        other:
          type: integer
          minimum: 0
          description: Expected other (non-agricultural) employees in next 12 months
          example: 5
      required:
        - agricultural
        - other
    AccommodationsActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - accommodations
          example: accommodations
        type:
          type: string
          description: Type of accommodation
          enum:
            - casino_hotel
            - hotel
            - motel
            - other
          example: hotel
      required:
        - category
        - type
    ConstructionActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - construction
          example: construction
        detail:
          description: Construction follow-up details
          allOf:
            - $ref: '#/components/schemas/ConstructionDetail'
      required:
        - category
        - detail
    FinanceActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - finance
          example: finance
        type:
          type: string
          description: Type of finance activity
          enum:
            - commodities_broker
            - credit_card_issuing
            - investment_advice
            - investment_club
            - investment_holding
            - mortgage_broker
            - mortgage_company
            - portfolio_management
            - sales_financing
            - securities_broker
            - trust_administration
            - venture_capital
            - other
          example: investment_advice
      required:
        - category
        - type
    FoodServiceActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - food_service
          example: food_service
        type:
          type: string
          description: Type of food service
          enum:
            - bar
            - bar_and_restaurant
            - catering_service
            - coffee_shop
            - fast_food_restaurant
            - full_service_restaurant
            - ice_cream_shop
            - mobile_food_service
            - other
          example: full_service_restaurant
      required:
        - category
        - type
    HealthCareActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - health_care
          example: health_care
        includes_md:
          type: boolean
          description: Does the establishment include M.D. practitioners?
          example: true
        md_role:
          type: string
          description: M.D. practitioner role. Required when includes_md is true.
          enum:
            - medical_doctor
            - psychiatrist
            - other_mental_health_practitioner
        non_md_role:
          type: string
          description: Non-M.D. practitioner type. Required when includes_md is false.
          enum:
            - chiropractor
            - dentist
            - hmo_medical_center
            - hospital
            - kidney_dialysis_center
            - optometrist
            - outpatient_care_center
            - podiatrist
            - psychologist
            - other_mental_health_practitioner
            - other
      required:
        - category
        - includes_md
    InsuranceActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - insurance
          example: insurance
        type:
          type: string
          description: Type of insurance activity
          enum:
            - insurance_carrier
            - insurance_agent_or_broker
            - other
          example: insurance_agent_or_broker
        support_activity_detail:
          type: string
          description: Description of the support activity. Required when type is other.
          example: Claims adjusting
      required:
        - category
        - type
    ManufacturingActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - manufacturing
          example: manufacturing
        goods:
          type: string
          description: Type of goods produced and primary materials used
          example: Aluminum cans from sheet aluminum
      required:
        - category
        - goods
    RealEstateActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - real_estate
          example: real_estate
        type:
          type: string
          description: Type of real-estate activity
          enum:
            - rent_lease_owned_property
            - use_capital_to_build_property
            - sell_property_for_others
            - manage_real_estate_for_others
            - other
          example: rent_lease_owned_property
        rental_property_type:
          type: string
          description: >-
            Property type rented/leased. Required when type is
            rent_lease_owned_property.
          enum:
            - residential
            - commercial_industrial
            - other
        construction:
          description: >-
            Construction details. Required when type is
            use_capital_to_build_property (the IRS routes this path through the
            construction questions).
          allOf:
            - $ref: '#/components/schemas/ConstructionDetail'
      required:
        - category
        - type
    RentalAndLeasingActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - rental_and_leasing
          example: rental_and_leasing
        type:
          type: string
          description: Type of rental/leasing activity
          enum:
            - rent_lease_sell_real_estate
            - rent_or_lease_goods
            - manage_real_estate_for_others
          example: rent_or_lease_goods
        real_estate_activity:
          type: string
          description: >-
            Real-estate activity. Required when type is
            rent_lease_sell_real_estate.
          enum:
            - real_estate_agent
            - rent_residential
            - rent_commercial_industrial
        goods:
          type: string
          description: >-
            Type of goods rented or leased. Required when type is
            rent_or_lease_goods.
          example: Construction equipment
      required:
        - category
        - type
    RetailActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - retail
          example: retail
        type:
          type: string
          description: Type of retail activity
          enum:
            - selling_goods_online
            - storefront_sales
            - direct_sales
            - auction_house
            - other
          example: storefront_sales
        direct_sales_method:
          type: string
          description: Direct-sales method. Required when type is direct_sales.
          enum:
            - catalogue
            - mail_order
            - door_to_door
      required:
        - category
        - type
    SocialAssistanceActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - social_assistance
          example: social_assistance
        type:
          type: string
          description: Type of social-assistance activity
          enum:
            - nursing_home
            - shelter
            - youth_services
            - other
          example: youth_services
      required:
        - category
        - type
    TransportationActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - transportation
          example: transportation
        type:
          type: string
          description: What the business primarily transports
          enum:
            - cargo
            - passengers
            - support_activity
          example: cargo
        cargo_mode:
          type: string
          description: Cargo transport mode. Required when type is cargo.
          enum:
            - air
            - rail
            - trucking
            - water
            - other
        passenger_mode:
          type: string
          description: Passenger transport mode. Required when type is passengers.
          enum:
            - limousine
            - shuttle_bus
            - taxi
            - other
      required:
        - category
        - type
    WarehousingActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - warehousing
          example: warehousing
      required:
        - category
    WholesaleActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - wholesale
          example: wholesale
        owns_goods:
          type: boolean
          description: Does the business own or take title to the goods?
          example: true
        receives_commission:
          type: boolean
          description: Does the business receive a commission or fee?
          example: false
        goods:
          type: string
          description: Type of goods sold
          example: Industrial cleaning supplies
      required:
        - category
        - owns_goods
        - receives_commission
        - goods
    OtherActivity:
      type: object
      properties:
        category:
          type: string
          enum:
            - other
          example: other
        type:
          type: string
          description: Type of activity
          enum:
            - consulting
            - manufacturing
            - organization
            - rental
            - repair
            - sell_goods
            - service
            - other
          example: consulting
      required:
        - category
        - type
    FeeAmount:
      type: object
      properties:
        amount:
          type: number
          description: Fee amount in whole units
          example: 125
        currency:
          type: string
          description: Currency code
          example: USD
      required:
        - amount
        - currency
    FeeLine:
      type: object
      properties:
        component_type:
          type: string
          description: Component type this rule rolls up under
          enum:
            - base
            - dynamic
            - late
            - credit_card
            - ach
          example: dynamic
        name:
          type: string
          description: >-
            Stable identifier within the component (e.g., "filing",
            "franchise_tax", "expedited"). "default" when there is exactly one
            rule for this component.
          example: franchise_tax
        amount:
          type: number
          description: Fee amount in whole units
          example: 500
        currency:
          type: string
          description: Currency code
          example: USD
      required:
        - component_type
        - name
        - amount
        - currency
    CaseRequestPayload:
      type: object
      properties:
        fields:
          description: 'Fields you''re being asked to supply (kind: missing_information).'
          type: array
          items:
            $ref: '#/components/schemas/FieldSpec'
    CaseResponsePayload:
      type: object
      properties:
        fields:
          type: object
          description: 'Map of field name to value (kind: missing_information).'
          additionalProperties: true
    ConstructionDetail:
      type: object
      properties:
        single_trade:
          type: boolean
          description: Does the business focus on a single construction trade?
          example: true
        trade:
          type: string
          description: The single construction trade. Required when single_trade is true.
          example: Electrical
        construction_type:
          type: string
          description: Type of construction. Required when single_trade is false.
          enum:
            - new_residential
            - remodeling_residential
            - non_residential
            - other_structures
        construction_type_detail:
          type: string
          description: >-
            Description of the structures built. Required when construction_type
            is other_structures.
          example: Bridges and tunnels
      required:
        - single_trade
    FieldSpec:
      type: object
      properties:
        name:
          type: string
          description: >-
            Stable machine-readable identifier for the requested field. Used as
            the key in the response payload.
          example: corrected_legal_name
        type:
          type: string
          description: >-
            Primitive type of the requested value. One of: string, number,
            boolean, date.
          example: string
        description:
          type: string
          description: Human-readable prompt explaining what is being asked.
          example: >-
            Corrected legal name (state rejected "Acme LLC" — name already
            taken).
        required:
          type: boolean
          description: >-
            Whether this field must be present in the response. Defaults to
            true.
          example: true
        example:
          description: Example value to help you understand the expected format.
          oneOf:
            - type: string
            - type: number
            - type: boolean
          example: Acme Holdings LLC
      required:
        - name
        - type
        - description
  securitySchemes:
    ApiKey:
      scheme: bearer
      bearerFormat: opaque
      type: http
      description: 'Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx'

````