Hosted sessions

Last updated Jun 14, 2026

Matter's API handles machine-scale work — intents, filings, documents-as-data. The parts that genuinely require a human in front of a browser — identity verification, signature capture, grant acceptance — run on Matter-hosted URLs you redirect to.

You keep your integration in code; Matter hosts the human-facing UI.

Formation Session

The hosted path from "I have API keys" to "I have a registered entity with a signed Action of Incorporator." Handles:

• Founder ID verification (KYC).
• Signature capture on the Action of Incorporator.
• 83(b) election submission (optional per founder).
• Stakeholder invites (optional).

POST /v1/formation_sessions

{
  "intent_id": "int_Nq3KcAbc",
  "return_url": "https://your-app.com/formation-complete",
  "cancel_url": "https://your-app.com/formation-cancelled",
  "collect": ["kyc", "signatures", "eighty_three_b", "stakeholder_invites"]
}

Response:

{
  "id": "fsn_Pq5xW8tY",
  "object": "formation_session",
  "status": "open",
  "url": "https://formation.mattermode.com/s/fsn_Pq5xW8tY",
  "expires_at": 1745338800,
  "intent_id": "int_Nq3KcAbc",
  "entity_id": null
}

Redirect the founder to url. When they return, entity_id is populated and the session status is complete.

Webhook progression

The session emits webhooks at each milestone:

Subscribe to formation_session.* to drive your own state machine — you don't need to poll.

Prerequisites: an Intent

A session fulfils an Intent. Create it first with execute: false, then pass its ID to the session. The intent captures the what (Delaware C-Corp, founders, share structure); the session collects the human artifacts required to execute.

# 1. Define the intent (no side effects)
POST /v1/intents
{
  "kind": "form_company",
  "execute": false,
  "type": "c_corp",
  "jurisdiction": "US-DE",
  "legal_name": "Waypoint Systems, Inc.",
  "founders": [ /* ... */ ]
}
# → { "id": "int_Nq3KcAbc", ... }

# 2. Start the hosted session
POST /v1/formation_sessions
{
  "intent_id": "int_Nq3KcAbc",
  "return_url": "https://your-app.com/done"
}

White-label branding

Platforms embedding formation can render the session in their own chrome:

{
  "branding": {
    "logo_url": "https://your-app.com/logo.png",
    "accent_color": "#E85112",
    "product_name": "YourCo Formation"
  }
}

Expiring a session

Need to abort? POST /v1/formation_sessions/{id}/expire invalidates the URL. No-op on already-terminal sessions.

Stakeholder Portal Session

Hosted URL per stakeholder for grant acceptance, 83(b) signing, document download, and vesting visibility.

POST /v1/stakeholder_portal_sessions
{
  "stakeholder_id": "stk_Qw5xY2bR",
  "return_url": "https://your-app.com/dashboard"
}

Response:

{
  "id": "sps_T8kPqNc2",
  "object": "stakeholder_portal_session",
  "url": "https://portal.mattermode.com/p/sps_T8kPqNc2",
  "expires_at": 1745335200,
  "scope": ["grants", "documents", "vesting", "tax_elections"]
}

Redirect the stakeholder. They land in a panel of their own holdings — no configuration on your side beyond creating the session.

Scoping what the stakeholder sees

Default scope is everything that stakeholder owns. Narrow if needed:

{
  "stakeholder_id": "stk_Qw5xY2bR",
  "return_url": "https://your-app.com/dashboard",
  "scope": ["grants", "documents"]
}

Omit cap_table_view — which it isn't in by default — for stakeholders who should only see their own holdings, not the full cap table. Add it if they're a board member or an officer with cap-table-read rights.

TTL

Default session lifetime is 1 hour. Max 24 hours via ttl_seconds.

When to use hosted vs. API

The API is always available underneath. Hosted sessions are a layer you can opt into per-flow, not a replacement.