Quickstart
Create a user, form a company, and receive a webhook — the whole integration in three requests.
This walkthrough places a real order end to end in the test environment. You'll need a sk_test_ API key (create one here).
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
Every company and order belongs to one of your users — typically your customer.
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
Do this before ordering so you see the filing progress. The signing secret is returned only once — store it.
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 for verifying the FileForms-Signature header.
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:
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 for a complete example.)
The response returns the new companyId and one item per product ordered:
{
"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). A 402 means your test balance needs topping up.
4. Receive webhooks
As the filing progresses, your endpoint receives filing.status_changed events — and when documents arrive, document.uploaded:
{
"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 to exercise your consumer.
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:
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.