Orders & Filing Lifecycle

Anatomy of an order request

POST /orders takes the user, the filing state, and one object per product you want — not a generic items array:

{
  "userId": "user_...",           // required
  "companyId": "comp_...",        // required unless formation is included
  "filingState": "TX",            // required, 2-letter code

  "formation": { ... },           // any combination of these five,
  "ein": { ... },                 // at least one required
  "annualReport": { ... },
  "foreignQualification": { ... },
  "registeredAgent": { ... }
}

Rules that apply across products:

• At least one product object is required.
• companyId or formation — a formation creates the company; everything else needs an existing one. The user must be an admin of that company.
• formation and foreignQualification are mutually exclusive in one request — an entity is either formed in the filing state or qualified there as a foreign entity.
• One filingState per request. Filing in multiple states means multiple requests.
• Product combinations in one request become separate order items sharing the company — formation + EIN + registered agent is the common bundle.
• foreignQualification also accepts the shorthand true when you have nothing to configure on it — see Foreign qualifications.

The response returns companyId plus one item per order created:

{
  "companyId": "comp_...",
  "items": [
    {
      "orderId": "order_...",
      "orderType": "formation",
      "filingStatus": "submitted",
      "filingDate": null,
      "subscriptionStatus": null,
      "createdAt": "2026-07-29T12:00:00.000Z"
    }
  ]
}

subscriptionStatus (active | canceled | past_due) is populated for subscription products — annual report and registered agent — and null for one-time filings.

The filing lifecycle

Every order carries a filingStatus:

Status changes reach you as filing.status_changed webhooks. filed and cancelled are terminal; exception is not.

Exceptions

When a state or the filing team needs something — a name conflict, a bad address, a rejected SSN — the filing enters exception and the webhook carries three fields:

{
  "filingStatus": "exception",
  "exceptionCode": "465",
  "exceptionReason": "Entity name not available",
  "exceptionMessage": "The requested name conflicts with an existing Texas entity."
}

exceptionCode is a stable numeric code, exceptionReason is its standard description, and exceptionMessage adds free-text detail when available. Once resolved, the filing resumes and you'll receive further status events.

Surface exceptions to your customer or your ops team promptly — most require information only the customer can provide.

Exception codes

Idempotency and duplicates

The API prevents the common double-purchases with 409 responses: an EIN order for a company that already has (or has requested) an EIN, or a foreign qualification already purchased for that state. Ordering registered agent service where an active one exists is silently skipped rather than duplicated. There is no general idempotency-key mechanism — treat a network-level retry of POST /orders with care.