# Introduction (https://docs.fileforms.com/guides) FileForms is a compliance automation platform for businesses and their advisors — annual report filings, registered agent service, new entity formation, foreign qualifications, certificates of good standing, and EIN services across all 50 states. These docs cover the two ways partners build on FileForms: * **The API** — a REST API at `https://api.fileforms.com/v1` for placing filing orders programmatically, receiving webhooks when filings progress, and embedding compliance into your own product. Orders placed via the API are billed to your organization's prepaid balance. * **The dashboard** — a white-label portal where your clients manage their own compliance. Depending on your [billing mode](/guides/billing/how-billing-works), they pay by card at retail prices you control, or their filings are billed to your organization. The docs are developer-first, but the billing, pricing, and state fee pages apply to dashboard partners too. Pages that only matter for one audience say so at the top. ## Start here [#start-here] ## Get help [#get-help] Email [info@fileforms.com](mailto:info@fileforms.com) or reach out to your FileForms contact. --- # Custom Pricing (https://docs.fileforms.com/guides/billing/custom-pricing) Retail prices apply only to dashboard orders paid through in-app checkout. Organization-billed orders — every API order, plus dashboard orders covered by your [billing mode](/guides/billing/how-billing-works) — always debit your balance at wholesale; retail prices never apply to them. Every product has three prices from your organization's point of view: | Price | Meaning | | ----------------- | -------------------------------------------------------------------------- | | `wholesaleAmount` | What FileForms collects. This is also the **floor** for your retail price. | | `retailAmount` | Your custom price — what your users pay. `null` until you set one. | | `defaultAmount` | The FileForms list price, used when you haven't set a retail price. | Your margin on each in-app checkout order is `retail − wholesale`. State fees are always passed through as a separate checkout line item and are not part of these prices. ## Setting prices [#setting-prices] In the dashboard: **Settings → Billing → Product pricing**. Via the API: ```bash curl -X PUT https://api.fileforms.com/v1/organization/prices/annual_report \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "retailAmount": 199 }' ``` Prices are whole dollars. Setting a price below your wholesale floor returns `400`: ```json { "message": "Price must be at least $149. Contact FileForms about bulk credit purchasing to lower your wholesale rates.", "minimumAmount": 149 } ``` `GET /organization/prices` lists every product with all three amounts; `DELETE /organization/prices/{type}` reverts a product to the list price (`404` if no custom price is set). ### Disabling formation tiers [#disabling-formation-tiers] Each price row has an `enabled` flag, but only the **formation tiers** can be turned off (`enabled: false` on anything else returns `400`), and at least one tier must remain enabled. Disabling a tier removes it from your users' dashboard checkout. It does **not** block API orders — those are governed by your integration, not the catalog. ## Formation packages and registered agent [#formation-packages-and-registered-agent] The tier 2 and tier 3 formation packages "include" registered agent service — but RA is an annual **subscription**, so it can't be folded into the one-time formation price. At checkout it's added as its own line item, and the package price your user sees is: ``` formation tier price + registered agent price (+ state fee) ``` When pricing your formation packages, remember that raising or lowering your `registered_agent` retail price also changes the effective price of every tier 2 and tier 3 formation package. ## Lowering your wholesale rates [#lowering-your-wholesale-rates] Wholesale rates are set by FileForms. Partners with volume can negotiate bulk credit agreements that lower wholesale on specific products — [contact FileForms](mailto:info@fileforms.com). (If a new wholesale floor lands above one of your existing retail prices, that retail price is raised to the floor automatically.) --- # How Billing Works (https://docs.fileforms.com/guides/billing/how-billing-works) Every order is settled one of two ways: * **Billed to your organization** — debited from your **prepaid balance** at your wholesale rates. There is no checkout step; the debit happens when the order is placed. * **Paid by your end user** — a card payment through in-app Stripe checkout, at the retail prices you set. You never front the money; FileForms collects the wholesale portion and your margin is the difference. Which one applies depends on where the order comes from and on your **billing mode**: * **API orders** are always billed to your organization. * **Dashboard orders** follow the billing mode set in **Settings → Billing → Billing mode**: everyone pays in-app (the default), organization admins are billed to the organization while other users pay in-app, or everyone is billed to the organization. Both paths charge the **state fee** on top of the service fee — see [State fees](/guides/billing/state-fees). ## Setting up billing [#setting-up-billing] Billing setup is required before you can create an API key or place organization-billed orders. An organization admin sets it up in **Settings → Billing**: 1. **Add a payment method** — card or US bank account (ACH). 2. **Make your initial top-up** — minimum **$500**. Your balance activates when the top-up settles: instantly for cards, **about 4 business days** for bank accounts. 3. **Configure auto top-up** (recommended) — see below. ## The prepaid balance [#the-prepaid-balance] Your balance is a ledger: top-ups credit it, orders debit it, and every entry is visible under **Settings → Billing → Transactions** (with CSV export). When an order is billed to your organization — any API order, or a dashboard order covered by your billing mode — the debit is `wholesale service fee + state fee`, charged at order creation. If a filing is later **cancelled**, the debit is automatically reversed to your balance. ### Auto top-up [#auto-top-up] When a debit takes your balance below your **balance threshold** (default $1,000), FileForms automatically charges your payment method for your **replenish amount** (default $5,000, minimum $500). Both are configurable in **Settings → Billing**. Bank-account top-ups take \~4 business days to settle, and while one is in flight no additional charge is attempted — an order that exceeds your remaining balance is rejected immediately. If you top up by ACH, set your threshold high enough to cover several days of order volume. ### Insufficient balance [#insufficient-balance] If an order would overdraw your balance, FileForms first attempts an immediate shortfall top-up from your saved payment method. If that can't settle instantly (card declined, your payment method is ACH, or a top-up is already in flight), the order is rejected with **`402 Payment Required`**: ```json { "message": "Insufficient organization balance for this order. Top up your balance in Settings → Billing to place new orders.", "balance": 12050, "required": 38800 } ``` `balance` and `required` are in **cents**. The order is not placed — top up and retry. If billing isn't set up at all, order endpoints return `403` instead. ## In-app checkout [#in-app-checkout] When a dashboard user isn't covered by your billing mode, they pay by card in a Stripe checkout composed of: * Your **retail price** for each product (set in [Custom pricing](/guides/billing/custom-pricing), or the FileForms list price if you haven't set one) * The **state fee** as a separate line item * For subscription products (annual report, registered agent), a recurring annual subscription One behavior worth knowing: **formation packages that include registered agent** (the tier 2 and 3 packages) add the RA subscription as its own line item at checkout — the price your user sees is the formation price *plus* the RA price. See [Custom pricing](/guides/billing/custom-pricing#formation-packages-and-registered-agent). ## One balance, one currency of truth [#one-balance-one-currency-of-truth] The dashboard shows prices in dollars; API error responses and the transactions ledger use cents. Amounts on `GET /organization/prices` (`defaultAmount`, `retailAmount`, `wholesaleAmount`) are whole dollars. --- # State Fees (https://docs.fileforms.com/guides/billing/state-fees) Every filing includes the government's own fee, charged on top of the FileForms service fee: * **Organization-billed orders** (every API order, plus dashboard orders covered by your [billing mode](/guides/billing/how-billing-works)) — the state fee is included in the amount debited from your prepaid balance. * **In-app checkout orders** — the state fee appears as its own line item in your user's checkout. State fees are set by the states and change when states change them. This table is generated from the same fee data the API bills with, so it always matches what you'll actually be charged. Notes: * **Varies** means the state calculates the fee from entity-specific inputs (for example, share counts or revenue), so it can't be quoted flat. Support for these filings is in development — coming soon. * **No filing** means the state does not require that filing for that entity type. Where a state requires the filing but charges nothing, the fee is listed as $0. * **Expedited fee** replaces the standard state filing fee (it is not added on top); the expedited service charge is separate. Expedited filing is available only where a fee is listed — see [Formations](/guides/products/formations#expedited-filing). * Annual report rows marked **(foreign)** apply to companies foreign-qualified in that state. * **Certificate of good standing: Required** on a foreign qualification row means that state won't admit the entity without one, so the certificate is [added to the order automatically](/guides/products/foreign-qualifications) and billed as its own line. That line is priced from the **formation** state's certificate fee — the certificate is issued by the company's home state, not the state being qualified into — so read its cost from the Certificate of Good Standing tab under the formation state, not from the row you're looking at. --- # Data Model (https://docs.fileforms.com/guides/core-concepts/data-model) Five resources make up the API's world: ``` Your organization ├── Users (your customers) │ └── Companies (a user can administer many companies) │ ├── Orders (one per product ordered) │ └── Documents (filed articles, confirmations, RA mail, ...) └── Webhook endpoints ``` **Everything is scoped to your organization.** Your API key can only see and touch users, companies, orders, and documents that belong to your organization — there is no cross-tenant access in either direction. ## Users [#users] A user is the person (usually your customer) who owns companies and receives any enabled email notifications. Users are identified by `user_...` ids and can be fetched by id **or email**: `GET /users/{userIdOrEmail}`. Emails and phone numbers are unique across FileForms, so `POST /users` returns `409` if either already exists. ## Companies [#companies] A company is the legal entity filings are made for — identified by a `comp_...` id or its URL slug (both work in `GET /companies/{companyIdOrSlug}`). Key attributes: * `entityType` — `LLC` or `CORP` (the only supported types) * `structureType` (`MEMBER`/`MANAGER`) for LLCs; `taxElection` (`C Corporation`/`S Corporation`) for CORPs * Principal and mailing addresses, officers, optional EIN and trade name Companies are created two ways: explicitly via `POST /companies` (for an existing entity your customer already owns), or implicitly by a formation order (`POST /orders` with a `formation` object — see [Formations](/guides/products/formations)). A company is linked to the user who administers it; a user can administer many companies. ## Orders [#orders] An order (`order_...`) is one product purchased for one company: a formation, an annual report, an EIN, registered agent service, a foreign qualification, or a certificate of good standing. One `POST /orders` call can create several orders at once — e.g. a formation + EIN + registered agent is three order items in one request. Every filing order carries a `filingStatus` that progresses as the filing moves through the state — covered in [Orders & filings](/guides/core-concepts/orders-and-filings). [Certificates of good standing](/guides/products/certificate-of-good-standing) are the exception: they aren't filings and carry no status. Orders are created via the API and tracked via webhooks — `filing.status_changed` tells you every time a filing order's status changes (certificates of good standing have none, and arrive as `document.uploaded` instead). Store the `orderId`s from order-creation responses and reconcile against webhook events. ## Documents [#documents] Documents (`doc_...`) are the files filings produce: articles of organization/incorporation, state confirmations, EIN letters, certificates, and registered agent mail. Each belongs to a company. You learn about new documents from the `document.uploaded` webhook, which includes the `orderId` it relates to. Fetch a fresh download link any time with `GET /documents/{documentId}` — download URLs expire after one hour. ## State registrations [#state-registrations] Behind the scenes, each company tracks its registration per state — whether it's domestic (formed there) or foreign (qualified there), its registered agent, and its annual report subscriptions. You don't manipulate this resource directly; it's maintained by the orders you place. It explains one behavior worth knowing: ordering registered agent service for a state where the company already has an active one is a no-op rather than a duplicate purchase. --- # Orders & Filing Lifecycle (https://docs.fileforms.com/guides/core-concepts/orders-and-filings) ## Anatomy of an order request [#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: ```json { "userId": "user_...", // required "companyId": "comp_...", // required unless formation is included "filingState": "TX", // required, 2-letter code "formation": { ... }, // any compatible combination, "ein": { ... }, // at least one required "annualReport": { ... }, "foreignQualification": { ... }, "registeredAgent": { ... }, "certificateOfGoodStanding": true } ``` 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` is mutually exclusive with both `foreignQualification` and `certificateOfGoodStanding`** in one request — an entity is either formed in the filing state or qualified there as a foreign entity, and a newly formed entity has no good standing to certify yet. * **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](/guides/products/foreign-qualifications). `certificateOfGoodStanding` has no options at all, so it simply takes `true` — see [Certificates of good standing](/guides/products/certificate-of-good-standing). The response returns `companyId` plus one item per order created: ```json { "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 [#the-filing-lifecycle] Every filing order carries a `filingStatus`. Certificates of good standing are the exception — they aren't filings and carry no status at all (see [Certificates of good standing](/guides/products/certificate-of-good-standing)). | Status | Meaning | | ----------- | --------------------------------------------------------------------------------------------------- | | `submitted` | FileForms accepted the order and it's in the filing pipeline. Every filing order starts here. | | `pending` | The filing is with the state, awaiting processing. | | `filed` | Accepted by the state. `filingDate` is set, and documents typically follow via `document.uploaded`. | | `exception` | Something needs attention before the filing can proceed — see below. | | `cancelled` | The order was cancelled. For balance-billed orders, the debit is reversed automatically. | Status changes reach you as [`filing.status_changed` webhooks](/guides/webhooks/event-catalog) — for filing orders only; a certificate of good standing never emits one. `filed` and `cancelled` are terminal; `exception` is not. ## Exceptions [#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: ```json { "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 [#exception-codes] ## Idempotency and duplicates [#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. [Certificates of good standing](/guides/products/certificate-of-good-standing) are deliberately unguarded — repeat orders for the same company and state are legitimate, so each one creates a new order and a new charge. There is no general idempotency-key mechanism — treat a network-level retry of `POST /orders` with care. --- # Users & Magic Links (https://docs.fileforms.com/guides/core-concepts/users-and-magic-links) Your API integration does the filing work server-to-server — but your customers may still want to see their companies, documents, and filing statuses. Magic links give them that without you building UI or managing credentials. ## How it works [#how-it-works] ```bash curl -X POST https://api.fileforms.com/v1/auth/magic-link \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8" }' ``` ```json { "magicLink": "https://apps.fileforms.com/?token=..." } ``` * `userId` is required and must be one of **your** users — the link signs them into their own account. * `companyId` is optional; when provided, the link lands the user directly on that company's page. The user must be an admin of the company. * The link **expires after 7 days** and grants a normal dashboard session for that user. If your organization has a white-label domain configured, the link points at your branded domain instead of `apps.fileforms.com`. ## Usage patterns [#usage-patterns] * **"View your filing" links** — mint a fresh link when you email or notify your customer about a filing event, deep-linked to the company. * **Embedded access** — an "Open compliance dashboard" button in your product that calls your backend, mints a link, and redirects — or an iframe, below. Mint links on demand rather than storing them: they're single-purpose URLs with a 7-day shelf life, and each call returns a fresh one. ## Embedding in an iframe [#embedding-in-an-iframe] The dashboard can be embedded directly in your product with an iframe whose `src` is a freshly minted magic link: ```html ``` The flow: when your page loads, your frontend asks your backend for an embed URL, your backend calls `POST /auth/magic-link` (server-side — never expose your API key to the browser), and you set the returned URL as the iframe `src`. **Mint a fresh link on every load.** Magic link tokens are single-use — once the iframe authenticates with one, that URL is spent. The session it creates lives in the embedded frame's browser storage, which browsers partition and may clear between visits, so don't count on it surviving. Treat the magic link as the way in every time: fresh page load, fresh `POST /auth/magic-link`, fresh `src`. A magic link is a live credential for that user's account. Generate it server-side, deliver it only to that user, and never log full link URLs. --- # Authentication (https://docs.fileforms.com/guides/getting-started/authentication) Every API request is authenticated with your organization's API key, sent in the `x-api-key` header: ```bash curl https://api.fileforms.com/v1/organization \ -H "x-api-key: sk_live_..." ``` Keys are prefixed `sk_live_` (production) or `sk_test_` (the [test environment](/guides/getting-started/environments)). A missing or invalid key returns `401`: ```json { "message": "Unauthorized" } ``` ## Create your API key [#create-your-api-key] Your organization has one API key, created and managed in the dashboard — API keys can never be created or rotated via the API itself. 1. In the [dashboard](https://apps.fileforms.com), go to **Settings → Developers**. You need to be an organization admin. 2. Click **Create API Key**. 3. Copy the key and store it in your secrets manager. **It is shown exactly once** — the dashboard can never display it again, only the masked placeholder. Creating an API key requires billing to be set up first, because API orders are debited from your organization's prepaid balance. If billing isn't configured, the Developers tab shows a **Set Up Billing** button instead — see [How billing works](/guides/billing/how-billing-works). ## Rolling your key [#rolling-your-key] Key rotation is a two-phase operation designed for zero-downtime cutover: 1. **Roll API Key** — generates a new key. **Both the old and new keys work** from this moment. 2. Update your integrations to the new key at your own pace. 3. **Complete Rotation** — revokes the old key. Until you complete (or cancel) the rotation, the overlap window stays open indefinitely. If a key leaks, roll it and complete the rotation immediately — completing is what revokes the compromised secret. ## Key security [#key-security] * Treat the key like a password: server-side only, never in client-side code, mobile apps, or version control. * All requests must use HTTPS. * The key acts on behalf of your whole organization. Every user, company, and order it touches is scoped to your organization — one partner can never read another's data. --- # Test vs. Live Environments (https://docs.fileforms.com/guides/getting-started/environments) FileForms has two environments, each with its own base URL, database, and API keys: | | Live | Test | | -------------- | ------------------------------ | -------------------------------------- | | API base URL | `https://api.fileforms.com/v1` | `https://api.staging.fileforms.dev/v1` | | Dashboard | `https://apps.fileforms.com` | `https://staging.fileforms.dev` | | API key prefix | `sk_live_` | `sk_test_` | | Payments | Live Stripe | Stripe test mode | | State filings | Really submitted | Never reach a state | A `sk_test_` key only works against the test base URL, and a `sk_live_` key only works against the live one. There is no sandbox flag on the live API — the environments are fully separate deployments with separate data. Nothing you create in test exists in live, and vice versa. ## What behaves differently in test [#what-behaves-differently-in-test] * **Orders and data are real records** in the test environment — the API behaves identically, so your integration code doesn't change between environments except for the base URL and key. * **Filings are never actually submitted to a state.** Fulfillment runs against sandbox systems, and the automation that performs real state filings is disabled. * **Filing statuses do not auto-advance.** A test order won't progress to `filed` on its own. To exercise your status-change handling, use [test webhook deliveries](/guides/webhooks/retries-and-redelivery#send-a-test-event) — or ask your FileForms contact to advance a specific test filing. * **Payments use Stripe test mode.** Prepaid balance top-ups and end-user checkouts accept Stripe test cards (e.g. `4242 4242 4242 4242`). * **Webhooks behave identically** — same signatures, same retry schedule, same delivery inspection. Test your webhook consumer entirely in the test environment. ## Getting test credentials [#getting-test-credentials] [Sign up](https://staging.fileforms.dev/auth/signup) at `staging.fileforms.dev` to create a test account and organization — it's a separate signup from live. Then create your API key the same way as in live (**Settings → Developers**), after completing test billing setup with a Stripe test card. ## Going live [#going-live] 1. Complete billing setup in the [live dashboard](https://apps.fileforms.com) (**Settings → Billing**). 2. Create your live API key (**Settings → Developers**). 3. Point your integration at `https://api.fileforms.com/v1` with the `sk_live_` key. 4. Re-create your webhook endpoints in live — endpoints and signing secrets do not carry over from test. 5. Review your [pricing](/guides/billing/custom-pricing) and [auto top-up settings](/guides/billing/how-billing-works#auto-top-up) before placing real orders. --- # Quickstart (https://docs.fileforms.com/guides/getting-started/quickstart) This walkthrough places a real order end to end in the [test environment](/guides/getting-started/environments). You'll need a `sk_test_` API key ([create one here](/guides/getting-started/authentication)). All requests go to `https://api.staging.fileforms.dev/v1` with your key in the `x-api-key` header. When you go live, only the base URL and key change. ## 1. Create a user [#1-create-a-user] Every company and order belongs to one of your users — typically your customer. ```bash curl -X POST https://api.staging.fileforms.dev/v1/users \ -H "x-api-key: sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "fullName": "Jane Doe", "email": "jane@example.com", "phoneNumber": "+17135550123" }' ``` Save the returned `id` (`user_...`). ## 2. Register a webhook endpoint [#2-register-a-webhook-endpoint] Do this before ordering so you see the filing progress. The signing secret is returned only once — store it. ```bash curl -X POST https://api.staging.fileforms.dev/v1/webhook-endpoints \ -H "x-api-key: sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/webhooks/fileforms", "eventTypes": ["filing.status_changed", "document.uploaded"] }' ``` See [Setup & verification](/guides/webhooks/setup-and-verification) for verifying the `FileForms-Signature` header. ## 3. Place a formation order [#3-place-a-formation-order] One request creates the company and orders the formation. This example forms a Texas LLC with FileForms registered agent service — it's valid as-is, so you can paste and send it: ```bash curl -X POST https://api.staging.fileforms.dev/v1/orders \ -H "x-api-key: sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "filingState": "TX", "formation": { "expedited": false, "company": { "legalName": "Acme Holdings LLC", "entityType": "LLC", "structureType": "MEMBER", "principalAddress": { "line1": "123 Main Street", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "officers": [{ "type": "PERSON", "firstName": "Jane", "lastName": "Doe", "title": "Managing Member", "isPrimary": true, "address": { "line1": "123 Main Street", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" } }] } }, "registeredAgent": { "isChangeOfAgent": false } }' ``` (Want an EIN with the formation? Add an `ein` object to the same request — it has a longer required field list (responsible party, employee counts, IRS questions), so see the [EIN guide](/guides/products/ein) for a complete example.) The response returns the new `companyId` and one item per product ordered: ```json { "companyId": "comp_x1y2z3w4v5u6t7s8", "items": [ { "orderId": "order_...", "orderType": "formation", "filingStatus": "submitted", ... }, { "orderId": "order_...", "orderType": "registered_agent", "filingStatus": "submitted", ... } ] } ``` Placing the order debits your prepaid balance ([wholesale + state fee](/guides/billing/how-billing-works)). A `402` means your test balance needs topping up. ## 4. Receive webhooks [#4-receive-webhooks] As the filing progresses, your endpoint receives `filing.status_changed` events — and when documents arrive, `document.uploaded`: ```json { "id": "evt_...", "type": "filing.status_changed", "createdAt": "2026-07-29T12:00:00.000Z", "data": { "orderId": "order_...", "orderType": "formation", "filingStatus": "filed", ... } } ``` There is no order-polling endpoint — webhooks are how you learn about status changes, so wire them up first. In the test environment filings don't auto-advance; use [test deliveries](/guides/webhooks/retries-and-redelivery#send-a-test-event) to exercise your consumer. ## 5. Let your user in (optional) [#5-let-your-user-in-optional] If you want your customer to see their company in your branded dashboard without building UI yourself, mint a magic link: ```bash curl -X POST https://api.staging.fileforms.dev/v1/auth/magic-link \ -H "x-api-key: sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8" }' ``` The returned URL signs the user straight into the dashboard (valid 7 days). More in [Users & magic links](/guides/core-concepts/users-and-magic-links). ## Where next [#where-next] --- # Annual Reports (https://docs.fileforms.com/guides/products/annual-reports) An annual report order files the company's periodic report with a state. Include `annualReport` in `POST /orders` with an existing `companyId`: ```bash curl -X POST https://api.fileforms.com/v1/orders \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "FL", "annualReport": { "filingYear": "2026" }, "registeredAgent": { "isChangeOfAgent": false } }' ``` ## Field requirements [#field-requirements] * **`filingYear`** — required, a four-digit **string** (`"2026"`, not `2026`). * **Registered agent** — the filing state must have an agent on record. If the company already has active FileForms RA service there, you're done. Otherwise either order RA service in the same request (as above) or supply the existing agent's details in `annualReport.registeredAgent` (its address state must equal `filingState`). * The company's `entityType` and `formationState` drive the state fee, so make sure they're set on the company record. ## What it costs, and when reports vary [#what-it-costs-and-when-reports-vary] The debit is the annual report wholesale price plus the state's fee. State fees for annual reports vary widely — some states charge nothing, some calculate from entity attributes ("Varies" in the [state fees table](/guides/billing/state-fees), support coming soon), and filing cadence differs by state and entity type. States whose reports are biennial are handled through the same `annualReport` order — the cadence is a property of the state, not a different product. ## Subscriptions [#subscriptions] Annual report is a subscription product: ordering one establishes an annual subscription for that company + state, and order items report a `subscriptionStatus` (`active` | `canceled` | `past_due`). Renewal reports are generated under the subscription so the company stays compliant year over year. ## After ordering [#after-ordering] * `filing.status_changed` → `filed` with `filingDate` when the state accepts it (reports pass through `pending` while queued with the state) * `document.uploaded` → the filed report / state confirmation * A common exception: code 482, a prior-year report problem that must be cured first --- # Certificate of Good Standing (https://docs.fileforms.com/guides/products/certificate-of-good-standing) A certificate of good standing is a state-issued document confirming a company is registered, active, and current on its obligations there. Include `certificateOfGoodStanding` in `POST /orders` with the existing `companyId`; `filingState` is the state the certificate is issued **from**. A [foreign qualification](/guides/products/foreign-qualifications) can also add one on its own, and changes which state it comes from — both cases are covered in [Field requirements](#field-requirements). ```bash curl -X POST https://api.fileforms.com/v1/orders \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "DE", "certificateOfGoodStanding": true }' ``` ## Field requirements [#field-requirements] * **The key takes no options.** Pass `"certificateOfGoodStanding": true`. * **`companyId` is required.** A certificate attests to an existing entity's standing, so there is nothing to certify for a company being created in the same request. Combining it with `formation` returns `400`. * **`filingState` is the state the certificate comes from** when the certificate is ordered on its own, which is not necessarily the company's formation state. A company registered in several states can be in good standing in each, and which one you need depends on why you need it: a bank, landlord, or counterparty in another state will usually want that state's own certificate, so that state is the one you name. * **Alongside `foreignQualification`, the certificate comes from the company's formation state instead.** `filingState` still names the state being qualified into, but the state admitting a foreign entity wants to see a certificate from that entity's **domestic** state — a certificate from the state you're entering is the one certificate the qualification can't use. The company's `formationState` must be set on the company record for this; without it the request returns `400`. * **You don't have to ask for it: where the qualifying state requires a certificate, one is added to the order automatically.** Whether a state requires it depends on the state and the company's `entityType` — several ask it of corporations but not LLCs, or the reverse — so a foreign qualification resolves the requirement for you and orders the certificate when it applies. It is charged as its own line and returned in `items` like any other order. Sending `"certificateOfGoodStanding": true` for a state that already requires one is not an error and does not double-charge: an order carries at most one certificate. * **No registered agent is required.** Unlike the filing products, a certificate is a records request — nothing about an agent is needed in the filing state. ## What it costs [#what-it-costs] One-time: the certificate of good standing wholesale price plus the issuing state's fee (see [State fees](/guides/billing/state-fees)). Unlike formations and foreign qualifications, the state fee doesn't depend on entity type — LLCs and corporations pay the same, and only the state varies. ## Repeat orders [#repeat-orders] Ordering a certificate again for the same company and state is **allowed**. There's no `409` and no silent skip — unlike foreign qualification, where a second order for a state you've already qualified into is rejected. Each request creates a new order and a new charge. That's deliberate: certificates are routinely required to be recently issued. Florida wants one issued within the last 30 days to support a foreign qualification, and lenders often ask for a fresh certificate at closing even if you pulled one days earlier. Because repeat orders are legitimate, nothing on our side will catch an accidental double-submit, and [there is no idempotency key](/guides/core-concepts/orders-and-filings#idempotency-and-duplicates) — guard against retries in your own integration. ## After ordering [#after-ordering] A certificate of good standing doesn't move through filing statuses. It isn't a state filing — the certificate is pulled from the state's records, and delivering it is the fulfillment. The order item carries no `filingStatus` and no `filingDate` at all; those fields are absent from a certificate item, not null. * `document.uploaded` fires when the certificate is available, carrying the `orderId` of your order, a `documentType` of `certificate_of_good_standing`, and a temporary download URL. You can also fetch it later with `GET /documents/{documentId}`. * This is the only event a certificate order emits. There is no `filing.status_changed` for certificates, so don't wait on one. --- # EIN (https://docs.fileforms.com/guides/products/ein) An EIN order obtains the company's federal tax ID from the IRS. Include `ein` in `POST /orders` — with a `formation` for a new company, or with `companyId` for an existing one. ```bash curl -X POST https://api.fileforms.com/v1/orders \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "TX", "ein": { "businessCategory": "Consulting", "businessPurpose": "Management consulting services", "applicationReason": "Started a new business", "vehicle55kPounds": false, "gamblingWagering": false, "fileForm720": false, "alcoholTobaccoFirearms": false, "isW2Expected": true, "agricultureEmployeesCount": 0, "otherEmployeesCount": 3, "firstWagesDate": "2026-09-01", "fileForm944": false, "responsiblePartyFirstName": "Jane", "responsiblePartyLastName": "Doe", "responsiblePartyTitle": "Managing Member", "responsiblePartySsn": "123456789", "responsiblePartyPhoneNumber": "+17135550123" } }' ``` ## Field requirements [#field-requirements] Every field in the `ein` object is required (the IRS application needs them all), with the responsible-party exceptions noted below: * **`businessCategory`** — one of the fixed categories (Consulting, Retail, Real Estate, Finance, … — the full enum is in the [API reference](/api-reference)); `businessPurpose` is free text. * **`applicationReason`** — one of: `Started a new business`, `Hired employee(s)`, `Banking purposes`, `Changed type of organization`, `Purchased active business`. * **IRS yes/no questions** — `vehicle55kPounds`, `gamblingWagering`, `fileForm720`, `alcoholTobaccoFirearms`, `fileForm944`. * **Employment** — if `isW2Expected` is `true`, the employee counts must sum to at least 1 and `firstWagesDate` is required; otherwise counts can be 0 and `firstWagesDate` can be `null` (the key must still be present). * **Responsible party** — name, title, phone, and SSN (9 digits, no dashes). It must be an SSN, not an ITIN — the API validates the format only, but the IRS rejects ITINs (surfaced as exception code 483). The responsible party is the person who controls the entity. The phone number accepts E.164 format (`+17135550123`); a bare 10-digit number is treated as US. ### Foreign responsible parties [#foreign-responsible-parties] If the responsible party is a foreign person without an SSN, set `responsiblePartyIsForeign: true`. The SSN is then omitted, and the phone number can be international (E.164 with the country code, e.g. `+447911123456`): ```json { "responsiblePartyFirstName": "Pierre", "responsiblePartyLastName": "Dupont", "responsiblePartyTitle": "Managing Member", "responsiblePartyIsForeign": true, "responsiblePartyPhoneNumber": "+33612345678" } ``` `responsiblePartyIsForeign` defaults to `false`, in which case `responsiblePartySsn` is required. The responsible party's SSN is sensitive data. Send it only over this API call, don't log request bodies for this endpoint, and don't store it on your side unless you have a reason to. ## Billing: standalone vs. bundled [#billing-standalone-vs-bundled] * **Bundled** — `ein` + `formation` in the same order: the formation is billed at the tier 2 wholesale price, which includes the EIN. The EIN line itself owes nothing. * **Standalone** — `ein` + `companyId`: billed at the EIN wholesale price. No state fee (it's a federal filing). ## Duplicate protection [#duplicate-protection] `409 Conflict` if the company already has an EIN on record (`EIN already exists for this company`) or a previous EIN order (`EIN already requested for this company`). ## After ordering [#after-ordering] * `filing.status_changed` events as the application progresses; `filed` when the IRS issues the number * `document.uploaded` → the EIN confirmation letter * Exceptions specific to EINs: code 483 (SSN rejected by the IRS) and 484 (SSN doesn't match the responsible party's name) — both need corrected information from your customer --- # Foreign Qualifications (https://docs.fileforms.com/guides/products/foreign-qualifications) A foreign qualification registers a company formed in one state to legally operate in another. Include `foreignQualification` in `POST /orders` with the existing `companyId`; `filingState` is the state being qualified **into**. ```bash curl -X POST https://api.fileforms.com/v1/orders \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "CA", "foreignQualification": true, "registeredAgent": { "isChangeOfAgent": false } }' ``` ## Field requirements [#field-requirements] * **A registered agent in the qualifying state is required** — states demand one before admitting a foreign entity. Either order FileForms RA service in the same request (as above, the common case), or supply an existing agent: `"foreignQualification": { "registeredAgent": { ... } }` with the agent's address in the filing state. * With an agent ordered or on file, the shorthand `"foreignQualification": true` is all you need. * **Cannot be combined with `formation`** in one request — a company is formed in a state or qualified into it, never both. Form first, then qualify in additional states with follow-up orders (one request per state). * **The company's `formationState` and `entityType` must be set on the company record** — they determine the state fee and appear on the qualification filing. * **A certificate of good standing is added automatically where the qualifying state requires one.** Most states won't admit a foreign entity without a certificate from its home state, and several require it of corporations but not LLCs (or the reverse), so the requirement is resolved from the filing state and the company's `entityType` rather than left to you — the Foreign Qualification tab of [State fees](/guides/billing/state-fees) marks which rows require one. When it applies, the certificate is ordered for you, **billed as its own line**, and returned in `items` alongside the qualification — see [Billing](#billing). It is issued from the company's formation state, not the state being qualified into, which is the certificate the qualifying state asks to see. Without `formationState` on the record, the order returns `400`. * You can also add `"certificateOfGoodStanding": true` yourself — in a state that already requires one this changes nothing, and you are charged for one certificate, not two. Order it that way when you want a certificate the state doesn't strictly require. See [Certificate of Good Standing](/guides/products/certificate-of-good-standing). ## Duplicate protection [#duplicate-protection] `409 Conflict` — `Foreign qualification already purchased for this state` — if the company already has a paid qualification there. A cancelled or unpaid earlier attempt doesn't block reordering. ## Billing [#billing] One-time: foreign qualification wholesale plus the qualifying state's fee (see [State fees](/guides/billing/state-fees)). RA service, if ordered, is its own annual subscription line. A certificate of good standing — whether you asked for it or the state requires it — is a separate one-time line, priced from the **formation** state it is issued from, not the state being qualified into. ## After ordering [#after-ordering] * `filing.status_changed` → `filed` when the state admits the entity * `document.uploaded` → the state's qualification certificate/confirmation * Common exception: code 487 (out-of-state registered agent) — the supplied agent must be in the qualifying state --- # Formations (https://docs.fileforms.com/guides/products/formations) A formation order creates the company in FileForms and files it with the state. Include the `formation` object in `POST /orders` — no `companyId`, since the company doesn't exist yet. ```bash curl -X POST https://api.fileforms.com/v1/orders \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "filingState": "DE", "formation": { "expedited": true, "company": { "legalName": "Acme Holdings LLC", "entityType": "LLC", "structureType": "MEMBER", "principalAddress": { "line1": "123 Main Street", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "officers": [{ "type": "PERSON", "firstName": "Jane", "lastName": "Doe", "title": "Managing Member", "isPrimary": true, "address": { "line1": "123 Main Street", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" } }] } }, "registeredAgent": { "isChangeOfAgent": false } }' ``` ## Field requirements [#field-requirements] **Entity types are `LLC` and `CORP`.** Each brings a required companion field: * LLC → `structureType`: `MEMBER` (member-managed) or `MANAGER` (manager-managed) * CORP → `taxElection`: `C Corporation` or `S Corporation` **Officers** — at least one, with at least one marked `isPrimary: true` (mark exactly one — the primary officer is the company's main contact). Titles must match the entity type: | Entity | Allowed titles | Extra rule | | ------ | -------------------------------------------------------------- | -------------------------------------------------------- | | LLC | Managing Member, Member, Manager | At least one officer must be a Member or Managing Member | | CORP | President, Vice President, Secretary, Treasurer, CEO, CFO, COO | — | An officer is a person (`type: "PERSON"`, first/last name) or a company (`type: "COMPANY"`, company name); every officer needs an address. **Not settable at formation**: `ein`, `tradeName`, `formationDate`, and `formationState` are excluded from the formation company object — the state sets the formation date when it files, `formationState` comes from `filingState`, and the EIN comes from an [EIN order](/guides/products/ein). **Registered agent** — every formation needs one. Either order FileForms RA service alongside (`"registeredAgent": { "isChangeOfAgent": false }`, as above), or supply your own agent in `formation.registeredAgent` (the agent's address state must equal `filingState`). See [Registered agent](/guides/products/registered-agent). **Alternative names** (API only) — `formation.alternativeNames` takes up to 10 fallback entity names, in order of preference, used if the state rejects the primary legal name. It sits alongside `company` in the `formation` object, not inside it: ```json "formation": { "company": { ... }, "alternativeNames": ["Acme Holdings of Texas LLC", "Acme Holdings Group LLC"] } ``` Providing alternatives lets a name-availability conflict be resolved without a round-trip through an [exception](/guides/core-concepts/orders-and-filings#exceptions). The dashboard wizard doesn't collect them — this is an API-only field. **Fiscal year end** defaults to December if `fiscalEndMonth` is omitted. ## How API formations are billed [#how-api-formations-are-billed] The dashboard sells formation packages in tiers; **the API has no tier field**. Your balance is debited based on what the order contains: | Order contents | Billed as | | ------------------- | ---------------------------------------------------------------------- | | `formation` alone | Tier 1 wholesale | | `formation` + `ein` | Tier 2 wholesale — the EIN is **bundled**, its line owes nothing extra | An EIN ordered *separately* (a later `POST /orders` with `ein` + `companyId`) is billed at the standalone EIN wholesale price — bundle pricing only applies when formation and EIN are in the same order for the same company. The top dashboard package (tier 3, which adds a DBA) is not available via the API. Registered agent service, when ordered, is its own line at RA wholesale. The state's formation fee is included in the debit — see [State fees](/guides/billing/state-fees). ## Expedited filing [#expedited-filing] Set `"expedited": true` to request expedited processing. Expedited filing is available only where the state offers it and FileForms supports it — currently **LLCs** in: | State | Expedited state fee | | -------- | ------------------- | | Arizona | $85 | | Delaware | $185 | | Florida | $195 | | Nevada | $550 | | New York | $205 | | Wyoming | $103.75 | The expedited state fee **replaces** the standard state filing fee, and the expedited service charge is billed on top. Requesting `expedited: true` for any other state/entity combination fails validation with `"Expedited formation is not available for the selected state and entity type"`. ## After ordering [#after-ordering] The response includes the new `companyId` and an order item per product. Then, via webhooks: 1. `filing.status_changed` → `filed` when the state accepts the formation (with `filingDate`) 2. `document.uploaded` → the filed articles of organization/incorporation 3. If you ordered an EIN: its own status events and the EIN confirmation document A formation can hit an `exception` — commonly name availability (codes 463–465). See [Orders & filings](/guides/core-concepts/orders-and-filings#exceptions). --- # Product Availability (https://docs.fileforms.com/guides/products) Each product guide shows a complete, copy-pasteable `POST /orders` request, the product's specific field requirements, and what to expect after ordering. | Product | API (`POST /orders`) | Dashboard | | ----------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------- | | [Formation](/guides/products/formations) | ✅ `formation` | ✅ | | [EIN](/guides/products/ein) | ✅ `ein` | ✅ | | [Annual report](/guides/products/annual-reports) | ✅ `annualReport` | ✅ | | [Registered agent](/guides/products/registered-agent) | ✅ `registeredAgent` | ✅ | | [Foreign qualification](/guides/products/foreign-qualifications) | ✅ `foreignQualification` | ✅ | | [Certificate of good standing](/guides/products/certificate-of-good-standing) | ✅ `certificateOfGoodStanding` | ✅ | | DBA | ❌ not yet | ✅ (as part of the top formation package) | DBAs aren't orderable through the API yet — the `POST /orders` schema has no key for them. When they land in the API, they'll get a full guide here. The dashboard sells formations as three packages (with the top one bundling a DBA). The API doesn't take a package choice — what you're billed is derived from what you order. See [Formations](/guides/products/formations#how-api-formations-are-billed). --- # Registered Agent (https://docs.fileforms.com/guides/products/registered-agent) Registered agent service appoints FileForms as the company's agent for service of process in a state, receives official mail there, and forwards it to you as `document.uploaded` events. Include `registeredAgent` in `POST /orders`: ```bash curl -X POST https://api.fileforms.com/v1/orders \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "TX", "registeredAgent": { "isChangeOfAgent": true } }' ``` ## `isChangeOfAgent` [#ischangeofagent] The one required field: * `false` — a **new appointment**, typically ordered alongside a formation or foreign qualification where FileForms becomes the agent from day one. (When ordered with a formation it's always treated as a new appointment.) * `true` — a **change of agent** filing with the state, replacing the company's current agent with FileForms. Status events for these carry `"filingType": "change_of_agent"`. ## Service vs. supplying your own agent [#service-vs-supplying-your-own-agent] Ordering `registeredAgent` buys **FileForms' RA service** — FileForms' own agent address is used automatically; you never supply one. If the company already has an agent you want to keep, don't order `registeredAgent`. Instead, pass the agent's details in the product that needs them (`formation.registeredAgent`, `annualReport.registeredAgent`, or `foreignQualification.registeredAgent`). A supplied agent can be a person or a company, and its address state must equal the `filingState`. Note the shape: unlike officers and companies (which nest an `address` object), a supplied agent uses **flat** address fields: ```json "registeredAgent": { "type": "COMPANY", "companyName": "Lone Star Agents Inc", "addressStreet": "456 Congress Ave", "addressCity": "Austin", "addressState": "TX", "addressZip": "78701" } ``` With `"type": "PERSON"`, send `firstName`/`lastName` instead of `companyName`. If the company **already has active FileForms RA service** in the filing state, ordering `registeredAgent` again is a no-op — the request succeeds but no duplicate service or charge is created. ## Billing [#billing] Registered agent is an annual **subscription** (order items report `subscriptionStatus`). For balance-billed API orders, your balance is debited the RA wholesale price when the order is placed; there is no state fee for the service itself. For orders paid through in-app checkout, note that the tier 2/3 formation packages add RA as its own subscription line item at checkout — see [Custom pricing](/guides/billing/custom-pricing#formation-packages-and-registered-agent). ## After ordering [#after-ordering] * For change-of-agent filings: `filing.status_changed` events (with `filingType: "change_of_agent"`) as the state processes the change * Ongoing: state and legal mail received by the agent arrives as `document.uploaded` events (`documentType: "registered_agent"`). If your organization's [email notifications](/guides/webhooks/setup-and-verification#email-notifications-for-the-same-events) are on, users are emailed about the mail too. --- # Event Catalog (https://docs.fileforms.com/guides/webhooks/event-catalog) ## Envelope [#envelope] Every delivery shares the same envelope: ```json { "id": "evt_a1b2c3d4e5f6g7h8", "type": "filing.status_changed", "createdAt": "2026-07-29T12:00:00.000Z", "data": { ... } } ``` Two things to build around: * **Deduplicate on `id`.** The event `id` is stable: retries and manual resends deliver the same event with the same `id` and payload. The one field that can change between deliveries is the `fileUrl` of a `document.uploaded` event, which is freshly signed on every delivery ([details below](#documentuploaded)) — so process each `id` at most once, but treat a duplicate's `fileUrl` as a replacement download link rather than discarding it. * **Fan-out creates distinct events.** When multiple endpoints subscribe to the same event type, each endpoint receives its own event with its own `id`. ## `filing.status_changed` [#filingstatus_changed] Sent when a filing progresses. `data` varies by `orderType`: | Field | Type | Notes | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `orderId` | string | The order this filing belongs to (`order_...`) | | `orderType` | string | `formation`, `ein`, `annual_report`, `registered_agent`, or `foreign_qualification` | | `filingStatus` | string | `submitted`, `pending`, `filed`, `exception`, or `cancelled` | | `filingDate` | string \| null | ISO datetime; set when `filingStatus` is `filed`, otherwise `null` | | `createdAt` | string | When the order was created | | `subscriptionStatus` | string \| null | `active`, `canceled`, or `past_due` for subscription products (annual report, registered agent); `null` otherwise | | `filingType` | string | Only on `registered_agent` orders: `change_of_agent` when the filing is an agent change | | `exceptionCode` | string \| null | Set when `filingStatus` is `exception` — see the [exception codes table](/guides/core-concepts/orders-and-filings#exception-codes) | | `exceptionReason` | string \| null | Human-readable explanation of the exception code | | `exceptionMessage` | string \| null | Free-text detail from the filing team, when available | ```json { "id": "evt_a1b2c3d4e5f6g7h8", "type": "filing.status_changed", "createdAt": "2026-07-29T12:00:00.000Z", "data": { "orderId": "order_x9y8z7w6v5u4t3s2", "orderType": "formation", "filingStatus": "filed", "filingDate": "2026-07-29T11:58:31.000Z", "createdAt": "2026-07-25T09:12:44.000Z", "subscriptionStatus": null, "exceptionCode": null, "exceptionReason": null, "exceptionMessage": null } } ``` What each status means: * `submitted` — FileForms accepted the order and it's in the filing pipeline * `pending` — the filing is with the state, awaiting processing * `filed` — accepted by the state; `filingDate` is set, and documents typically follow as `document.uploaded` events * `exception` — the state or filing team needs something; check the exception fields * `cancelled` — the order was cancelled `filed` and `cancelled` are terminal. An `exception` is not — once resolved, the filing continues and you'll receive further status changes. ## `document.uploaded` [#documentuploaded] Sent when a document becomes available on an order: filed articles, state confirmations, registered agent mail, EIN letters, certificates of good standing. For a [certificate of good standing](/guides/products/certificate-of-good-standing) this event *is* the fulfillment — it's the only event that order emits. | Field | Type | Notes | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `orderId` | string | The order the document belongs to | | `documentId` | string | Use with `GET /documents/{documentId}` (`doc_...`) | | `documentType` | string | Document category: `articles_of_organization`, `articles_of_incorporation`, `annual_report`, `ein`, `registered_agent`, `change_of_agent`, `certificate_of_good_standing`, `foreign_qualification`, or `company` | | `fileName` | string | | | `fileType` | string | MIME type | | `fileUrl` | string | Presigned download URL — **expires after 1 hour** | | `createdAt` | string | | ```json { "id": "evt_h8g7f6e5d4c3b2a1", "type": "document.uploaded", "createdAt": "2026-07-29T12:00:00.000Z", "data": { "orderId": "order_x9y8z7w6v5u4t3s2", "documentId": "doc_q1w2e3r4t5y6u7i8", "documentType": "articles_of_organization", "fileName": "articles-of-organization.pdf", "fileType": "application/pdf", "fileUrl": "https://bucket.s3.us-east-1.amazonaws.com/document.pdf?X-Amz-Signature=...", "createdAt": "2026-07-29T12:00:00.000Z" } } ``` Download the file promptly or fetch a fresh URL from `GET /documents/{documentId}` — the `fileUrl` in the payload expires after an hour. Retried and resent deliveries reuse the same event `id` but carry a freshly signed `fileUrl` in the payload; it's the only field that changes between deliveries of the same event. --- # Retries & Redelivery (https://docs.fileforms.com/guides/webhooks/retries-and-redelivery) ## What counts as a failed delivery [#what-counts-as-a-failed-delivery] A delivery succeeds only on a `2xx` response. Everything else is a failure and will be retried: * Any non-`2xx` status code * A redirect — deliveries never follow redirects * No response within **30 seconds** * Connection or DNS errors ## Retry schedule [#retry-schedule] After the initial attempt, failed deliveries are retried with increasing backoff: | Attempt | Delay after previous failure | Time since event (approx.) | | ------- | ---------------------------- | -------------------------- | | 1 | immediate | — | | 2 | 5 minutes | 5m | | 3 | 30 minutes | 35m | | 4 | 2 hours | \~2.5h | | 5 | 5 hours | \~7.5h | | 6 | 10 hours | \~17.5h | | 7 | 10 hours | \~27.5h | That's **7 attempts over roughly 27.5 hours**. Retries run on a sweep every 5 minutes, so actual times can lag the schedule by up to 5 minutes. After the final attempt the delivery is marked `failed` and no further automatic attempts are made — but you can always [redeliver manually](#redeliver-manually). Endpoints are never automatically disabled, no matter how many deliveries fail. To stop deliveries entirely, delete the endpoint. Every delivery has a status: `delivered`, `pending` (automatic retries remain — shown as "Retrying" in the dashboard), or `failed` (retries exhausted). ## Inspect deliveries [#inspect-deliveries] In the dashboard, **Settings → Developers → Deliveries** lists every event sent to your endpoints, filterable by endpoint, status, event type, and date. Click a row for the full payload, attempt history, response status, and the error returned by your endpoint. The same data is available via the API: ```bash curl "https://api.fileforms.com/v1/webhook-deliveries?status=failed&limit=50" \ -H "x-api-key: sk_live_..." ``` Filters: `endpoint`, `status` (`delivered` | `pending` | `failed`), and `type` — each accepting a comma-separated list — plus `from`, `to`, `order`, `limit` (1–100, default 10), and cursor pagination via `nextCursor`. ## Redeliver manually [#redeliver-manually] Two operations, for two situations: **Resend specific deliveries** — `POST /webhook-deliveries/resend` with up to 100 event ids (or the **Resend** button on any delivery in the dashboard). Each event gets one immediate attempt with the same event `id` and payload (for `document.uploaded` events the `fileUrl` is freshly signed — see the [event catalog](/guides/webhooks/event-catalog#documentuploaded)), and the result is reported synchronously per event: ```bash curl -X POST https://api.fileforms.com/v1/webhook-deliveries/resend \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "eventIds": ["evt_a1b2c3d4e5f6g7h8"] }' ``` ```json { "results": [ { "id": "evt_a1b2c3d4e5f6g7h8", "delivered": true, "responseStatus": 200, "responseError": null } ] } ``` Resending works on any delivery — including already-delivered ones, which is useful while developing — and never affects the automatic retry schedule. Unknown event ids come back in `results` as failed rather than erroring the whole call. **Retry everything that failed for an endpoint** — `POST /webhook-endpoints/{id}/retry-failed` (or the **Retry Failed** button). Re-queues all undelivered events for that endpoint — both exhausted ones and ones still waiting on backoff — for the next automatic sweep, and returns `{ "queued": n }`. Use this after fixing an outage on your side to catch up in bulk. ## Send a test event [#send-a-test-event] `POST /webhook-endpoints/{id}/test` with `{ "eventType": "filing.status_changed" }` (or the **Send Test** button) sends a signed test delivery to that endpoint and reports whether it was delivered. The endpoint must be subscribed to the requested event type (`400` otherwise). Test events match the real event shape exactly — same envelope (`evt_` id, requested `type`, signature) and same `data` fields as the [event catalog](/guides/webhooks/event-catalog) — with obviously fake sample values: ```json { "id": "evt_...", "type": "filing.status_changed", "createdAt": "2026-07-29T12:00:00.000Z", "data": { "orderId": "order_test0000000000000000", "orderType": "formation", "filingStatus": "filed", "filingDate": "2026-07-29T12:00:00.000Z", "createdAt": "2026-07-29T12:00:00.000Z", "subscriptionStatus": null, "exceptionCode": null, "exceptionReason": null, "exceptionMessage": null } } ``` The sample ids don't resolve to real resources (a test `document.uploaded` event's `fileUrl` won't download anything), so use test events to develop your parser and verify connectivity and signatures — then place orders in the [test environment](/guides/getting-started/environments) to exercise the full flow. --- # Setup & Verification (https://docs.fileforms.com/guides/webhooks/setup-and-verification) Webhooks notify your systems when something happens to your orders: a filing changes status, or a document becomes available. FileForms sends two event types — `filing.status_changed` and `document.uploaded` — described in the [event catalog](/guides/webhooks/event-catalog). ## Create an endpoint [#create-an-endpoint] Create endpoints via the API or in the dashboard under **Settings → Developers → Webhook endpoints → Add Endpoint**. ```bash curl -X POST https://api.fileforms.com/v1/webhook-endpoints \ -H "x-api-key: sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/webhooks/fileforms", "eventTypes": ["filing.status_changed", "document.uploaded"] }' ``` ```json { "id": "we_a1b2c3d4e5f6g7h8", "url": "https://api.example.com/webhooks/fileforms", "eventTypes": ["filing.status_changed", "document.uploaded"], "createdAt": "2026-07-29T12:00:00.000Z", "secret": "whsec_..." } ``` Endpoint URLs must be `https://` and publicly resolvable — URLs that resolve to private or internal addresses are rejected. The `whsec_` secret appears only in the create response (or the one-time dialog in the dashboard). It cannot be retrieved later, and there is no rotation endpoint — if you lose it or need to rotate, delete the endpoint and create a new one. Note that deleting an endpoint also deletes its delivery history. Updating an endpoint (`PATCH /webhook-endpoints/{id}`) replaces `eventTypes` wholesale rather than merging, and keeps the existing secret. ## Verify signatures [#verify-signatures] Every delivery is a `POST` with a JSON body and a `FileForms-Signature` header: ``` FileForms-Signature: t=1722268800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd ``` * `t` — Unix timestamp (seconds) of when the delivery was signed * `v1` — hex-encoded HMAC-SHA256 of `{t}.{raw request body}`, keyed with your endpoint's `whsec_` secret (the full secret string, prefix included) Verify every delivery before acting on it: ```ts import crypto from "node:crypto"; function verifyWebhookSignature( rawBody: string, header: string, secret: string, ): boolean { const parts = Object.fromEntries(header.split(",").map((p) => p.split("="))); const expected = crypto .createHmac("sha256", secret) .update(`${parts.t}.${rawBody}`) .digest("hex"); const expectedBuf = Buffer.from(expected); const actualBuf = Buffer.from(parts.v1 ?? ""); const isValid = expectedBuf.length === actualBuf.length && crypto.timingSafeEqual(expectedBuf, actualBuf); const isFresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; return isValid && isFresh; } ``` Three rules that prevent almost every verification bug: 1. **Sign the raw body bytes.** Compute the HMAC over the exact bytes you received — don't parse and re-serialize the JSON. With Express, use `express.raw({ type: 'application/json' })` and pass `req.body.toString()`. 2. **Compare in constant time** (`crypto.timingSafeEqual` above). 3. **Reject stale timestamps.** Anything older than 5 minutes should be treated as a possible replay. Respond with any `2xx` status quickly — deliveries time out after 30 seconds, and redirects are treated as failures. Do heavy processing asynchronously after acknowledging. ## Email notifications for the same events [#email-notifications-for-the-same-events] The same activity also exists as organization-wide email notifications (**Settings → Notifications**): "Document uploads" and "Filing status changes", both on by default. The toggles control email only — webhook delivery is never affected. * **API integrations** usually want these **off** once webhooks are live, so your users aren't emailed about events your systems already handle. * **Dashboard partners** without an API integration usually want them **on** — email is how their users hear about filings and documents. --- # API Reference (https://docs.fileforms.com/api-reference) The endpoint reference pages are rendered from the OpenAPI schema and are not included here. Use the OpenAPI 3.1 schema directly: https://api.fileforms.com/v1/openapi.json