Get started

Last updated Jun 14, 2026

Matter is the REST API for creating, operating, and dissolving real legal entities — Delaware C-Corps, LLCs, foreign qualifications, and the cap table, filings, resolutions, and dissolutions that follow. Authenticate with a bearer token, POST to a resource, and receive 202 Accepted with a pending object; the terminal outcome arrives via signed webhook when the underlying filing completes. Mutations are idempotent on every POST and version-pinned at the key. This page covers authentication, the first request, and async handling in one read.

Matter is the REST API at https://api.mattermode.com/v1 for creating, operating, and dissolving real legal entities. Mutations are async-by-default, idempotent on every POST, and version-pinned per request — the wire conventions are mainstream (RFC 6750 bearer auth, Idempotency-Key draft on POSTs, 202 Accepted for long-running work, RFC 7807 problem documents on errors).

Authentication

Bearer-token auth over HTTPS. Plain HTTP is rejected at the load balancer. Three headers ride on every request — keys and tokens pin an api_version at creation; the Matter-Version header overrides per-request.

Authorization: Bearer sk_test_matter_example_k2pqG7hN8mZxVb4R
Matter-Version: 2026-05-01
Idempotency-Key: 9f8c3a2e-6d4b-4f7a-8e9d-1c2b3a4f5e6d   # POST/PATCH only
Content-Type: application/json

Your first request

One call hits POST /v1/entities and triggers the full Delaware C-Corp formation cascade — Certificate of Incorporation, IncorporatorReceipt, EIN application, governance docs, founder share issuances, 83(b) elections.

curl https://api.mattermode.com/v1/entities \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Matter-Test-Speed: fast" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c_corp",
    "jurisdiction": "US-DE",
    "legal_name": "Waypoint Systems, Inc.",
    "founders": [
      {"name": "Jane Doe", "role": "CEO", "equity_percent": 80, "email": "jane@example.com"},
      {"name": "Michael Smith", "role": "CTO", "equity_percent": 20, "email": "michael@example.com"}
    ],
    "registered_agent": {"provider": "matter"},
    "tax": {"apply_for_ein": true},
    "governance_docs": true
  }'

import Matter from "@matter/sdk";

const matter = new Matter({ apiKey: process.env.MATTER_KEY });

const entity = await matter.entities.create({ // [!code focus:12]
  type: "c_corp",
  jurisdiction: "US-DE",
  legal_name: "Waypoint Systems, Inc.",
  founders: [
    { name: "Jane Doe", role: "CEO", equity_percent: 80, email: "jane@example.com" },
    { name: "Michael Smith", role: "CTO", equity_percent: 20, email: "michael@example.com" },
  ],
  registered_agent: { provider: "matter" },
  tax: { apply_for_ein: true },
  governance_docs: true,
});

console.log(entity.id, entity.status); // ent_Nq3KcAbc draft

import matter

m = matter.Client(api_key=os.environ["MATTER_KEY"])

entity = m.entities.create( 
    type="c_corp",
    jurisdiction="US-DE",
    legal_name="Waypoint Systems, Inc.",
    founders=[
        {"name": "Jane Doe", "role": "CEO", "equity_percent": 80, "email": "jane@example.com"},
        {"name": "Michael Smith", "role": "CTO", "equity_percent": 20, "email": "michael@example.com"},
    ],
    registered_agent={"provider": "matter"},
    tax={"apply_for_ein": True},
    governance_docs=True,
)
print(entity.id, entity.status)

With the Matter MCP server installed, any agent can form a company directly:

> Form a Delaware C-Corp called "Waypoint Systems, Inc." with two founders:
> Jane Doe (CEO, 80%) and Michael Smith (CTO, 20%). Apply for an EIN and
> generate governance docs.

The agent calls matter_form_company under the hood. Tier-3 + human signature
required — the dashboard surfaces an Authorization for the human to sign.

The response is 202 Accepted with the pending entity. Every resource carries the envelope fields id, object, created, updated, livemode, metadata. X-Request-Id is mirrored in Problem.request_id on errors — log it for triage.

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Request-Id: req_2c1a4d9f8b

{
  "id": "ent_Nq3KcAbc",
  "object": "entity",
  "status": "draft",
  "legal_name": "Waypoint Systems, Inc.",
  "jurisdiction": "US-DE",
  "livemode": false,
  "created": 1713686400,
  "updated": 1713686400,
  "metadata": {}
}

Handling async

The call returned a draft entity. Behind the scenes Matter runs the formation cascade asynchronously: resolves the Intent → files with Delaware → issues an IncorporatorReceipt → transfers authority → applies for EIN → generates governance docs → issues founder shares.

Subscribe to webhooks for any flow that crosses a few seconds. Polling burns rate limits and you'll miss out-of-order events. Webhook delivery is HMAC-SHA256 signed, retried with backoff to 72h, and ordered per-entity via a strict sequence field.

POST /v1/entities   →   202 Accepted   →   entity.state_changed   →   entity.active
                                              (via webhook)

Below is a virtual-clock simulation of exactly that — the cascade plays out in ~10 seconds with the webhook log accumulating on the right. Pause, scrub, or retry to study state transitions.

What next

FAQ