API · Create · Entities
Submit entity.
Advances a draft entity to submitted by transmitting the Certificate of Incorporation to the secretary of state. The named incorporator (entity.incorporator_stakeholder_id) signs the cert here — either through a signing envelope (Rail 1) or under standing UETA §14 consent via incorporator_signature_authorized on a tier-3 or tier-4 token (Rail 2). See legal basis and the incorporator protocol.
Idempotent. Calling this on an entity already in submitted, registered, or any later state returns 200 OK with the current entity (no-op). Calling on a cancelled or rejected entity returns 409 invalid_state_transition.
POST /v1/entities continues to auto-cascade through this step for back-compat; the explicit /submit verb is the recommended path for agent flows that want a clean disclosure-and-confirm boundary between draft creation and irreversible submission.
Returns 202 Accepted with an AsyncResult. The entity.state_changed → submitted event fires synchronously; filing.accepted and incorporator_receipt.issued follow as the SOS responds.
Last updated
Query Parameters
dry_runbooleanOptionalIf true, simulate the mutation and return the would-be resource, any cascaded
resources, and a fee estimate — without side effects. Available on every mutation.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
acknowledgementsarray<object>RequiredPer-action informed acknowledgements. Required slugs are listed on
x-matter-required-acknowledgements. Bound to the natural-person
stakeholder named at entity.incorporator_stakeholder_id. See
acknowledgements.
slugstringRequiredTyped identifier for a class of risk the customer is affirming awareness of. Each
slug has canonical plain-English text and a version, fetched via GET /v1/acknowledgements.
Acknowledgements are bound to natural-person stakeholders and expire 90 days after
acceptance; ToS-version supersession invalidates open acknowledgements under the
prior version. See acknowledgements.
One of
"not_legal_advice""not_tax_advice""agent_action_binds_principal""tier_4_standing_authority_acknowledged""incorporator_signature_authorized""formation_is_legally_binding""formation_creates_tax_obligations""83b_election_strict_30_day_deadline""equity_grant_is_securities_issuance""dissolution_is_irreversible""service_of_process_must_reach_human""late_filing_penalty_accepted"versionstringRequiredVersion of the canonical text the stakeholder affirmed. Mismatch → invalidates the acknowledgement.
accepted_by_stakeholder_idstringRequiredThe natural-person stakeholder who affirmed this acknowledgement.
accepted_atintegerRequiredUnix timestamp (seconds since epoch) when the stakeholder typed/clicked the acknowledgement affordance.
ipstringOptionalIP address of the affirming human at acceptance time. Captured for audit.
user_agentstringOptionalUser agent of the affirming human at acceptance time. Captured for audit.
disclosure_packet_hashstringOptionalSHA-256 of the DisclosurePacket returned from the most recent
?dry_run=true call. Optional but recommended — when present, the
server confirms the disclosure shown to the principal matches the
one in effect at submission time. Mismatch returns
422 disclosure_changed_resign_required.
Response Body
application/json
application/json
application/problem+json
application/problem+json
Request
curl -X POST "https://api.mattermode.com/v1/entities/{id}/submit" \ -H "Content-Type: application/json" \ -d '{ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "string", "accepted_at": 0 } ] }'const body = JSON.stringify({ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "string", "accepted_at": 0 } ]})fetch("https://api.mattermode.com/v1/entities/{id}/submit", { method: "POST", headers: { "Content-Type": "application/json" }, body})package mainimport ( "fmt" "net/http" "io/ioutil" "strings")func main() { url := "https://api.mattermode.com/v1/entities/{id}/submit" body := strings.NewReader(`{ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "string", "accepted_at": 0 } ] }`) req, _ := http.NewRequest("POST", url, body) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body))}import requestsheaders = { "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc", "Matter-Version": "2026-06-10", "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = { "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "example", "accepted_at": 1 } ]}resp = requests.post( "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit", headers=headers, json=payload,)resp.raise_for_status()print(resp.json())import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "string", "accepted_at": 0 } ]}""");HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder() .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/submit")) .header("Content-Type", "application/json") .POST(body) .build();try { HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString()); System.out.println("Status code: " + response.statusCode()); System.out.println("Response body: " + response.body());} catch (Exception e) { e.printStackTrace();}using System;using System.Net.Http;using System.Text;var body = new StringContent("""{ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "string", "accepted_at": 0 } ]}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/submit", body);var responseBody = await response.Content.ReadAsStringAsync();curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit' \ --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \ --header 'Matter-Version: 2026-06-10' \ --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \ --header 'Content-Type: application/json' \ --data '{ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "example", "accepted_at": 1 } ]}'const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit", { method: "POST", headers: { "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc", "Matter-Version": "2026-06-10", "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b", "Content-Type": "application/json", }, body: JSON.stringify({ "acknowledgements": [ { "slug": "not_legal_advice", "version": "2026-04-01", "accepted_by_stakeholder_id": "example", "accepted_at": 1 } ] }),});if (!response.ok) { throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);Response
application/json{
"id": "ent_Nq3KcAbc",
"object": "entity",
"status": "draft",
"type": "c_corp",
"jurisdiction": "US-DE",
"legal_name": "Waypoint Systems, Inc.",
"aliases": [
"string"
],
"formed_at": 0,
"dissolved_at": 0,
"acquired_at": 0,
"merged_at": 0,
"sold_at": 0,
"workspace_id": "string",
"corporate_transaction_id": "string",
"principal_address": {
"line1": "string",
"line2": "string",
"city": "string",
"county": "string",
"region": "string",
"postal_code": "string",
"country": "US"
},
"mailing_address": {
"line1": "string",
"line2": "string",
"city": "string",
"county": "string",
"region": "string",
"postal_code": "string",
"country": "US"
},
"registered_agent_id": "string",
"incorporator_stakeholder_id": "string",
"tax_profile_id": "string",
"stakeholder_ids": [
"string"
],
"cap_table_id": "string",
"equity_plan_ids": [
"string"
],
"qualifications": [
{
"id": "string",
"object": "qualification",
"entity_id": "string",
"jurisdiction": "US-DE",
"status": "qualifying",
"qualified_at": 0,
"registered_agent_id": "string",
"compliance_track": {
"annual_report_due_on": "2019-08-24",
"franchise_tax_due_on": "2019-08-24"
},
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
}
],
"compliance": {
"health": "healthy",
"next_deadline": 0,
"open_obligations_count": 0
},
"intent_id": "string",
"incorporator_receipt_id": "string",
"portfolio_id": "string",
"governing_documents": {
"certificate_of_incorporation_id": "string",
"restated_certificate_of_incorporation_id": "string",
"bylaws_id": "string",
"action_of_incorporator_id": "string",
"secretary_certificate_id": "string",
"initial_board_consent_id": "string"
},
"formation_packet_status": "not_started",
"external_status": "pending",
"active_browser_agent_run_id": "string",
"browser_agent_run": {
"id": "string",
"object": "browser_agent_run",
"entity_id": "string",
"filing_kind": "formation",
"submitted": false,
"state": "pending",
"perception_mode": "recipe",
"region": "us_east",
"computed_fee_usd": 0,
"observed_fee_usd": 0,
"proof_bundle_id": "string",
"content_hash": "string",
"render_hash": "string",
"blocker": {
"reason": "PORTAL_MARKUP_DRIFT",
"message": "string",
"resume_token": "string",
"partial_field_dump": {}
},
"stopped_at": 0,
"created": 0
},
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
}{
"resource": null,
"intent": {
"id": "string",
"object": "intent",
"goal": "start_company",
"parameters": {
"proposed_name": "string",
"founder": {
"name": "string",
"email": "user@example.com",
"home_state": "string"
},
"founding_team": [
{
"name": "string",
"email": "user@example.com",
"equity_percent": 0,
"title": "string"
}
],
"description": "string",
"preferences": {
"entity_kind": "c_corp",
"jurisdiction": "auto",
"authorised_shares": 0,
"par_value_usd": 0,
"registered_agent": "matter",
"founder_vesting": "none",
"sector": "general",
"sector_attributes": {
"profession": "medicine",
"owner_license_numbers": {
"property1": "string",
"property2": "string"
},
"will_sell_taxable_goods": true,
"first_hire_expected_months": 0,
"principal_address_is_residential": true,
"facility_type": "string",
"aum": 0,
"public_benefit_statement": "string",
"smart_contract_identifier": "string",
"projected_annual_receipts": 0,
"total_assets": 0,
"solicitation_states": [
"string"
]
},
"county": "string",
"management_structure": "member",
"nonprofit_class": "c3_public_charity",
"operating_states": [
"string"
],
"directors": 1,
"expand_governance": true,
"include_s_election": true,
"completed_by_date": "2019-08-24"
}
},
"status": "draft",
"execution_plan": {
"steps": [
{
"operation": "string",
"depends_on": [
0
],
"estimated_duration_seconds": 0,
"cost_estimate": {
"amount": 50000,
"currency": "usd"
},
"requires_human_signature": false,
"status": "pending",
"output_resource_ids": [
"string"
],
"defaulted_fields": [
{
"field": "string",
"value": null,
"rationale": "string",
"rationale_source": "discovery_input",
"overridable": true,
"basis": "nvca_standard",
"citations": [
"string"
]
}
],
"phase": "formation",
"gate": {
"owner": "founder",
"expected_duration_days": [
0,
0
],
"evidence": [
"string"
]
},
"deadline": {
"due": {},
"hard": true
},
"entity_ref": "string",
"fee_cents": 0
}
],
"compliance_calendar": [
{
"name": "string",
"due": {},
"fee_cents": 0,
"cadence": "one_time",
"source": "jurisdiction",
"hard": true,
"notes": "string",
"jurisdiction": "string"
}
],
"jurisdiction_support": {
"tier": "first_class",
"notes": "string"
},
"recipe": {
"name": "venture_de_c_corp",
"basis": "nvca_standard",
"rationale": "string"
},
"plan_version": "string"
},
"entity_id": "string",
"cost_estimate": {
"amount": 50000,
"currency": "usd"
},
"completed_at": 0,
"resolved_recommendations": [
{
"field": "string",
"recommended_value": null,
"basis": "matter_signature_default",
"rationale": "string",
"override_paths": [
{
"endpoint": "string",
"field": "string",
"context": "intent_parameters"
}
],
"document_merge_fields": [
{
"document_kind": "string",
"merge_field": "string"
}
],
"confidence": "default",
"citations": [
{
"authority": "string",
"url": "http://example.com"
}
]
}
],
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
},
"execution_plan": {
"steps": [
{
"operation": "string",
"depends_on": [
0
],
"estimated_duration_seconds": 0,
"cost_estimate": {
"amount": 50000,
"currency": "usd"
},
"requires_human_signature": false,
"status": "pending",
"output_resource_ids": [
"string"
],
"defaulted_fields": [
{
"field": "string",
"value": null,
"rationale": "string",
"rationale_source": "discovery_input",
"overridable": true,
"basis": "nvca_standard",
"citations": [
"string"
]
}
],
"phase": "formation",
"gate": {
"owner": "founder",
"expected_duration_days": [
0,
0
],
"evidence": [
"string"
]
},
"deadline": {
"due": {},
"hard": true
},
"entity_ref": "string",
"fee_cents": 0
}
],
"compliance_calendar": [
{
"name": "string",
"due": {},
"fee_cents": 0,
"cadence": "one_time",
"source": "jurisdiction",
"hard": true,
"notes": "string",
"jurisdiction": "string"
}
],
"jurisdiction_support": {
"tier": "first_class",
"notes": "string"
},
"recipe": {
"name": "venture_de_c_corp",
"basis": "nvca_standard",
"rationale": "string"
},
"plan_version": "string"
},
"authorization": {
"id": "string",
"object": "authorization",
"token_id": "string",
"action": "string",
"payload_hash": "string",
"status": "pending",
"expires_at": 0,
"signature_url": "http://example.com",
"approved_by_stakeholder_id": "string",
"approved_at": 0,
"denied_reason": "string",
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
},
"pending_filings": [
{
"id": "string",
"object": "filing",
"entity_id": "string",
"type": "certificate_of_amendment",
"jurisdiction": "US-DE",
"status": "preparing",
"payload": {
"amendments": [
{
"section": "string",
"change_type": "add",
"previous_value": null,
"new_value": null
}
],
"effective_date": "2019-08-24"
},
"submitted_at": 0,
"accepted_at": 0,
"rejected_reason": "string",
"state_confirmation_number": "string",
"document_ids": [
"string"
],
"authorizing_resolution_id": "string",
"authorizing_corporate_transaction_id": "string",
"prerequisite_filings": [
"string"
],
"depends_on": [
"string"
],
"final_return": false,
"post_dissolution_filing": false,
"fees": {
"platform": {
"amount": 50000,
"currency": "usd"
},
"passthrough": {
"amount": 50000,
"currency": "usd"
}
},
"cancellation_window_ends_at": 0,
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
}
],
"cascaded_documents": [
{
"id": "string",
"object": "document",
"entity_id": "string",
"type": "certificate_of_incorporation",
"provenance": "matter_generated",
"status": "draft",
"execution_status": "draft",
"lifecycle_class": "agreement",
"upstream_provenance": null,
"terminated_at": "2019-08-24",
"terminated_reason": null,
"clause_toggles": [
{
"clause_id": "string",
"current_value": null,
"default_value": null,
"override_basis": null,
"set_at": 0,
"set_by_stakeholder_id": "string"
}
],
"clause_toggle_changes": [
{
"clause_id": "string",
"previous_value": null,
"new_value": null,
"override_basis": null,
"changed_at": 0,
"changed_by_stakeholder_id": "string",
"note": "string"
}
],
"internal_notes": "string",
"structured_clauses": [
{
"clause_id": "string",
"value_type": "integer",
"value": null,
"source_section": "string",
"extracted_at": 0
}
],
"efile_metadata": {
"rail": "irs_id_me_portal",
"irs_confirmation_number": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"form_15620_document_id": "string",
"sub_agent_session_id": "string"
},
"attaches_to": "string",
"attachment_kind": null,
"related_documents": [
{
"document_id": "string",
"relation_kind": "co_executed_with",
"note": "string",
"established_at": "2019-08-24T14:15:22Z"
}
],
"cover_page_fields": {},
"equity_promise": {
"kind": "iso",
"shares_promised": 0,
"strike_price_status": "pending_409a",
"derived_from_valuation_id": "string",
"fixed_strike_price_usd": 0,
"vesting_schedule_promised": {
"total_months": 0,
"cliff_months": 0,
"commencement_anchor": "start_date",
"acceleration": null,
"expected_grant_date": "2019-08-24"
},
"board_approval_status": "pending",
"realized_grant_id": "string"
},
"standard_terms_template_id": "string",
"template_id": "string",
"template_version": "string",
"current_version_id": "string",
"entity_snapshot": {},
"payload": {},
"pdf_url": "http://example.com",
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"proof": {
"algorithm": "Ed25519",
"value": "string",
"signing_key_fingerprint": "string"
},
"version": 1,
"parent_document_id": "string",
"signatures": [
{
"stakeholder_id": "string",
"signed_at": 0,
"signature_method": "esign",
"legal_basis": "wet_signature",
"consent_record": {
"consent_id": "string",
"ip": "string",
"user_agent": "string",
"accepted_at": 0,
"esra_disclosure_version": "2026-04-01"
},
"agent_authority": {
"token_id": "string",
"authorization_id": "string",
"principal_human_id": "string",
"agent_id": "string",
"acknowledgements": [
{
"slug": "not_legal_advice",
"version": "2026-04-01",
"accepted_by_stakeholder_id": "string",
"accepted_at": 0,
"ip": "string",
"user_agent": "string"
}
],
"standing_policy_id": "string"
},
"intent_text": "string"
}
],
"envelope_id": "string",
"sensitivity": "standard",
"disclaimer": {
"text": "string",
"version": "2026-04-01",
"source": "ueta_matter_v1",
"marketing_disclosure_url": "http://example.com"
},
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
}
],
"cascaded_resolutions": [
{
"id": "string",
"object": "resolution",
"entity_id": "string",
"kind": "board_meeting",
"subject": "Approval of 2026 Equity Plan and initial pool of 2,000,000 shares",
"resolved_at": 0,
"variant": "sole_director",
"signatories": [
{
"stakeholder_id": "string",
"signed_at": 0,
"role": "string",
"signing_capacity": "director"
}
],
"officer_changes": [
{
"stakeholder_id": "string",
"change_kind": "appoint",
"title": "string",
"effective_date": "2019-08-24",
"previous_title": "string"
}
],
"document_id": "string",
"authorizes_filings": [
"string"
],
"authorizes_agreements": [
"string"
],
"authorizes_grants": [
"string"
],
"authorizes_share_reservations": [
"string"
],
"metadata": {
"customer_id": "cus_7Hpx9WxY",
"portfolio_tag": "y-combinator-w26"
},
"created": 0,
"updated": 0,
"livemode": true
}
],
"events_emitted": [
"string"
],
"applied_defaults": [
"string"
],
"next_steps": [
{
"endpoint": "POST /v1/entities/ent_Nq3KcAbc/tax_elections",
"reason": "Founder restricted-stock issuances require 83(b) within 30 days.",
"deadline": 0
}
]
}nullnull