API · Webhooks
filing.deadline_at_risk
An independent statutory-deadline watchdog determined a filing's hard deadline is approaching or passed while the obligation is still open — emitted out of band at T-7 days and T-0, independent of any run's progress (it fires even if the run blocked before arming its own timer). Drives the attention badge on the inbox surface.
Last updated
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
idstringRequiredTyped resource ID. Prefix encodes the resource type (e.g. ent_ Entity, flg_ Filing, doc_ Document). Stable across API versions.
objectstringRequiredDiscriminator string equal to the resource type name in snake_case (e.g. entity, filing). Useful when you receive a polymorphic event payload and need to dispatch on type.
"event"typestringRequired"filing.deadline_at_risk"api_versionstring<date>RequiredAPI version this event was serialized against.
createdintegerRequiredUnix timestamp (seconds since epoch) when this resource was first created. Immutable.
dataobjectRequiredobjectobjectOptionalA legal entity — the central object of the Matter API. Entities flow through the
lifecycle state machine described in /concepts/lifecycle.
idstringRequiredTyped resource ID. Prefix encodes the resource type (e.g. ent_ Entity, flg_ Filing, doc_ Document). Stable across API versions.
objectstringRequiredDiscriminator string equal to the resource type name in snake_case (e.g. entity, filing). Useful when you receive a polymorphic event payload and need to dispatch on type.
"entity"statusstringRequiredHome-jurisdiction lifecycle state. Foreign qualifications track independently via qualifications[].
Terminal states split by exit shape: dissolved for self-initiated wind-down; acquired, merged,
or sold when a CorporateTransaction closes. in_transaction is a live M&A hold set when a
CorporateTransaction advances past definitive.
"draft""submitted""registered""active""suspended""in_transaction""dissolving""winding_down""tax_cleared""dissolved""acquired""merged""sold""rejected""cancelled"typestringRequired"c_corp""s_corp""llc""benefit_corp""nonprofit""lp""llp"jurisdictionstringRequiredISO 3166-2 subdivision code. For US entities, this is the formation state
(US-DE, US-CA). For entities in other countries, top-level jurisdiction code.
legal_namestringRequiredaliasesarray<string>OptionalDBAs and prior names.
formed_atintegerOptionalUnix timestamp of entity birth. Null until registered.
dissolved_atintegerOptionalacquired_atintegerOptionalSet when the entity transitions to acquired on close of an acquisition CorporateTransaction.
merged_atintegerOptionalSet when the entity transitions to merged on close of a merger CorporateTransaction.
sold_atintegerOptionalSet when the entity transitions to sold on close of an asset-sale CorporateTransaction.
workspace_idstringOptionalThe Workspace this entity was formed inside, if any. Set when the entity is
created from inside a workspace's chat surface (the canonical onboarding flow);
null for entities created directly via POST /v1/entities without a workspace
context (the SDK-first / batch-create paths).
corporate_transaction_idstringOptionalThe CorporateTransaction that produced this entity's terminal or in_transaction state. Null
for entities that exited via self-initiated dissolution or are still operating.
principal_addressobjectOptionalStructured address.
line1stringRequiredline2stringOptionalcitystringRequiredcountystringOptionalCounty, parish, or borough. Optional for most addresses but required
in the registered-agent block of certain state filings (DE Certificate
of Incorporation per 8 Del. C. §131; analogous fields in NY and MD,
parishes in LA). When omitted, the recommendation engine derives the
county from line1 + region against the @repo/jurisdictions data
— populated automatically for Matter-provided registered agents.
regionstringRequiredState, province, or region code (e.g. DE, CA, NY).
postal_codestringRequiredcountrystringRequiredISO 3166-1 alpha-2.
mailing_addressobjectOptionalStructured address.
line1stringRequiredline2stringOptionalcitystringRequiredcountystringOptionalCounty, parish, or borough. Optional for most addresses but required
in the registered-agent block of certain state filings (DE Certificate
of Incorporation per 8 Del. C. §131; analogous fields in NY and MD,
parishes in LA). When omitted, the recommendation engine derives the
county from line1 + region against the @repo/jurisdictions data
— populated automatically for Matter-provided registered agents.
regionstringRequiredState, province, or region code (e.g. DE, CA, NY).
postal_codestringRequiredcountrystringRequiredISO 3166-1 alpha-2.
registered_agent_idstringOptionalincorporator_stakeholder_idstringOptionalThe natural-person stakeholder named as incorporator on the Certificate of
Incorporation. Required at POST /entities. Must reference a Stakeholder
with kind = "natural_person". Matter never signs as incorporator — the
customer's named founder does, either directly via a signing envelope (Rail 1)
or through their electronic agent under UETA §14 standing consent (Rail 2).
See legal basis and the
incorporator protocol.
tax_profile_idstringOptionalstakeholder_idsarray<string>Optionalcap_table_idstringOptionalComputed view key (cap_table is not a stored resource).
equity_plan_idsarray<string>Optionalqualificationsarray<object>OptionalForeign qualifications. Each carries its own state and compliance track.
idstringRequiredTyped resource ID. Prefix encodes the resource type (e.g. ent_ Entity, flg_ Filing, doc_ Document). Stable across API versions.
objectstringRequiredDiscriminator string equal to the resource type name in snake_case (e.g. entity, filing). Useful when you receive a polymorphic event payload and need to dispatch on type.
"qualification"entity_idstringRequiredjurisdictionstringRequiredISO 3166-2 subdivision code. For US entities, this is the formation state
(US-DE, US-CA). For entities in other countries, top-level jurisdiction code.
statusstringRequired"qualifying""qualified""withdrawing""withdrawn"qualified_atintegerOptionalregistered_agent_idstringOptionalcompliance_trackobjectOptionalPer-jurisdiction compliance cadence.
annual_report_due_onstring<date>Optionalfranchise_tax_due_onstring<date>OptionalmetadataobjectOptionalCaller-owned map<string, string> for arbitrary application context. Up to 50 keys, 40 chars per key, 500 chars per value. The matter_ key prefix is platform-reserved. Never store secrets here. See metadata.
createdintegerOptionalUnix timestamp (seconds since epoch) when this resource was first created. Immutable.
updatedintegerOptionalUnix timestamp (seconds since epoch) when this resource was last mutated. Bumps on every state transition. Use as the If-Match ETag input for optimistic concurrency.
livemodebooleanRequiredtrue when this resource exists in the live (production) dataset; false for test mode. Determined by the credential that created it; immutable thereafter. See test mode.
complianceobjectOptionalRolled-up compliance snapshot across home + qualifications.
healthstringOptional"healthy""attention""lapsed"next_deadlineintegerOptionalopen_obligations_countintegerOptionalintent_idstringOptionalThe intent that originated this entity, if any.
incorporator_receipt_idstringOptionalportfolio_idstringOptionalgoverning_documentsobjectOptionalCurated pointers to the entity's foundational documents. Eliminates the N+1
query against GET /documents?type=… for the documents callers reach for
constantly. Each pointer is null until the document is generated; populated
in step with the formation packet cascade and refreshed on every charter
amendment.
certificate_of_incorporation_idstringOptionalrestated_certificate_of_incorporation_idstringOptionalbylaws_idstringOptionalaction_of_incorporator_idstringOptionalsecretary_certificate_idstringOptionalinitial_board_consent_idstringOptionalformation_packet_statusstringOptionalSub-state of the Day-0 formation packet cascade emitted by
POST /entities/{id}/formation_packet. Surfaces the implicit progression
today inferred only from filings and document types. Webhook
entity.formation_packet_status.changed fires on every transition.
"not_started""pending""incorporator_action_complete""bylaws_adopted""initial_resolutions_executed""founder_stock_issued""83b_window_open""indemnification_signed""ein_obtained""complete"external_statusstringOptionalOutcome of the state/federal filing-office interaction for this entity's
formation or initial report — distinct from the home-jurisdiction
lifecycle status. prepared means a browser-agent run filled and
validated every field, reconciled the fee, captured tamper-evident
proof, and stopped at the pre-submit screen without submitting;
blocked means the run raised a structured Blocker (see
browser_agent_run.blocker). Null until a filing interaction starts.
"pending""registered""failed""prepared""blocked"active_browser_agent_run_idstringOptionalThe in-flight or most-recent browser-agent run preparing a filing for
this entity, if any. Null when no run is attached. The run is keyed to
the entity (formation is an entity lifecycle, not a Filing row).
browser_agent_runobject | nullOptionalExpanded summary of active_browser_agent_run_id. Present only when
requested via expand[]=browser_agent_run; otherwise null. Read-only.
metadataobjectOptionalCaller-owned map<string, string> for arbitrary application context. Up to 50 keys, 40 chars per key, 500 chars per value. The matter_ key prefix is platform-reserved. Never store secrets here. See metadata.
createdintegerRequiredUnix timestamp (seconds since epoch) when this resource was first created. Immutable.
updatedintegerRequiredUnix timestamp (seconds since epoch) when this resource was last mutated. Bumps on every state transition. Use as the If-Match ETag input for optimistic concurrency.
livemodebooleanRequiredtrue when this resource exists in the live (production) dataset; false for test mode. Determined by the credential that created it; immutable thereafter. See test mode.
filing_kindstringOptionalstatutory_deadline_atintegerOptionalUnix timestamp of the hard statutory deadline.
severitystringOptionalurgent once the deadline is at or past T-0; attention at T-7d.
"attention""urgent"sequenceintegerRequiredMonotonically increasing integer scoped to the subject resource. Enables strict per-entity ordering on the consumer side.
livemodebooleanRequiredtrue when this resource exists in the live (production) dataset; false for test mode. Determined by the credential that created it; immutable thereafter. See test mode.
pending_webhooksintegerOptionalEndpoints that haven't yet received this event.
requestobjectOptionalidstringOptionalidempotency_keystringOptionalauthorized_byobjectOptionalDual attribution envelope. Present on Events, AuditEntries, and error responses originating from agent-initiated actions.
human_principal_idstringRequiredID of the human principal who authorized the action.
agent_idstringOptionalID of the agent that actually performed the action, if any.
Response Body
Example Requests
/filing.deadline_at_risk