Type reference (Python)

from typing import Any, Dict, List, Literal, Union
from typing_extensions import NotRequired, TypedDict

class Account(TypedDict, total=False):
    """The API customer. Top-level identity owning tokens, portfolios, and entities."""
    id: str
    object: Literal["account"]
    legal_name: str
    billing_email: NotRequired[str]
    billing_address: NotRequired["Address"]
    default_jurisdiction: NotRequired["Jurisdiction"]
    default_registered_agent_provider: NotRequired[Literal["matter", "external"]]
    default_signing_method: NotRequired[Literal["matter_native", "docusign", "adobe_sign", "dropbox_sign"]]
    tier_max: NotRequired[int]
    active_agent_policy_id: NotRequired[Any]
    portfolio_ids: NotRequired[List[str]]
    primary_principal_user_id: NotRequired[Any]
    soc2_attestation_status: NotRequired[Literal["not_started", "in_progress", "attested", "lapsed"]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class AgentPolicy(TypedDict, total=False):
    """Versioned governance record of what agent tokens may do. Authorizations are"""
    id: str
    object: Literal["agent_policy"]
    name: str
    tier_max: int
    version: int
    active: bool
    allowed_endpoints: NotRequired[List[str]]
    denied_endpoints: NotRequired[List[str]]
    resources: NotRequired[List[str]]
    conditions: NotRequired[Dict[str, Any]]
    require_human_signature_for: NotRequired[List[str]]
    standing_acknowledgements: NotRequired[List["AcknowledgementSlug"]]
    spend_limit_per_period: NotRequired[Dict[str, Any]]
    escalation_email: NotRequired[str]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class AuditEntry(TypedDict, total=False):
    """Immutable record of a state-changing action. One per transition. Signature-producing"""
    id: str
    object: Literal["audit_entry"]
    entity_id: Any
    actor: Dict[str, Any]
    action: str
    before: NotRequired[Any]
    after: NotRequired[Dict[str, Any]]
    request_id: NotRequired[str]
    ip: NotRequired[str]
    occurred_at: int
    livemode: bool

class Authorization(TypedDict, total=False):
    """First-class async pause. When a tier-3 action requires human signature, the API"""
    id: str
    object: Literal["authorization"]
    token_id: str
    action: str
    payload_hash: str
    status: Literal["pending", "approved", "denied", "expired"]
    expires_at: int
    signature_url: NotRequired[str]
    approved_by_stakeholder_id: NotRequired[Any]
    approved_at: NotRequired[Any]
    denied_reason: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class BankAccount(TypedDict, total=False):
    """Deposit account for an entity. Opened via `createBankAccount`,"""
    object: Literal["bank_account"]
    id: str
    entity_id: str
    status: Literal["pending", "pending_kyb", "kyb_pending", "kyb_held", "active", "frozen", "closing", "closed"]
    account_type: Literal["checking", "savings"]
    nickname: str
    balance_usd_cents: int
    provider: NotRequired[Literal["column", "mercury", "brex", "chase", "ramp", "other"]]
    account_number: NotRequired[str]
    routing_number: NotRequired[Any]
    account_number_last_4: NotRequired[Any]
    kyb_decision: NotRequired[Literal["approved", "held_for_review", "declined", "not_applicable"]]
    kyb_decided_at: NotRequired[str]
    column_account_id: NotRequired[str]
    sub_agent_session_id: NotRequired[str]
    partner_bank: NotRequired[Literal["column"]]
    authorized_signer_stakeholder_ids: NotRequired[List[str]]
    created_at: NotRequired[str]
    activated_at: NotRequired[Any]

class BenefitPlan(TypedDict, total=False):
    """Linkage record for an entity's benefit plan or insurance policy."""
    object: Literal["benefit_plan"]
    id: str
    entity_id: str
    regime: Literal["medical", "dental", "vision", "life_disability", "retirement_401k", "retirement_403b", "hra", "fsa", "hsa", "other"]
    provider_kind: Literal["benefits_administrator", "retirement_record_keeper", "insurance_carrier"]
    provider_name: NotRequired[Any]
    external_account_id: NotRequired[Any]
    linkage_attestation_document_id: NotRequired[Any]
    adoption_resolution_id: NotRequired[Any]
    termination_resolution_id: NotRequired[Any]
    plan_administrator_stakeholder_id: NotRequired[Any]
    status: Literal["linked", "terminating", "terminated"]
    opened_at: NotRequired[int]
    terminating_at: NotRequired[Any]
    terminated_at: NotRequired[Any]
    created: int
    updated: int
    livemode: bool

class BillingAlert(TypedDict, total=False):
    """A billing tripwire. Alerts notify — via `billing.alert.fired` events and an"""
    id: str
    object: Literal["billing_alert"]
    account_id: str
    metric: Literal["balance_below_cents", "budget_percent", "usage_unit_threshold", "spend_velocity_cents_per_hour"]
    threshold_value: int
    unit: NotRequired[Any]
    recurrence: Literal["once", "per_period"]
    status: Literal["active", "disabled"]
    is_default: bool
    last_fired_at: NotRequired[Any]
    webhook_endpoint_id: NotRequired[Any]
    created: int
    updated: int
    livemode: bool

class BrowserAgentRun(TypedDict, total=False):
    """A read-only summary of one fill-no-submit browser-agent run preparing a"""
    id: str
    object: Literal["browser_agent_run"]
    entity_id: str
    filing_kind: str
    submitted: Any
    state: Literal["pending", "running", "deferred", "prepared", "blocked"]
    perception_mode: NotRequired[Literal["recipe", "assisted"]]
    region: NotRequired[str]
    computed_fee_usd: NotRequired[Any]
    observed_fee_usd: NotRequired[Any]
    proof_bundle_id: NotRequired[Any]
    content_hash: NotRequired[Any]
    render_hash: NotRequired[Any]
    blocker: NotRequired[Union["Blocker", Any]]
    stopped_at: NotRequired[Any]
    created: int

class Budget(TypedDict, total=False):
    """A per-period spend fence over an org, portfolio, or token. A `block` budget"""
    id: str
    object: Literal["budget"]
    scope_kind: Literal["org", "portfolio", "token"]
    scope_id: NotRequired[Any]
    period: Literal["day", "month"]
    cap: "MonetaryAmount"
    action: Literal["block", "warn"]
    created_by_user_id: NotRequired[Any]
    created_by_token_id: NotRequired[Any]
    created: int
    updated: int
    livemode: bool

class CapTableSnapshot(TypedDict, total=False):
    """Materialized point-in-time cap table, pinned at meaningful moments (priced"""
    id: str
    object: Literal["cap_table_snapshot"]
    entity_id: str
    as_of: int
    reason: Literal["priced_round", "valuation", "board_approval", "fiscal_year_close", "manual"]
    cap_table: "CapTable"
    document_id: NotRequired[Any]
    valuation_id: NotRequired[Any]
    actor_id: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    livemode: bool

class CorporateTransaction(TypedDict, total=False):
    """M&A envelope — merger, acquisition, asset sale, stock sale, conversion, or"""
    id: str
    object: Literal["corporate_transaction"]
    kind: Literal["merger", "acquisition", "asset_sale", "stock_sale", "conversion", "reorganization", "acquihire", "charter_amendment"]
    parties: List[Dict[str, Any]]
    stage: Literal["loi", "due_diligence", "definitive", "regulatory_review", "closing", "closed", "cancelled", "terminated"]
    consideration: NotRequired[Dict[str, Any]]
    consideration_breakdown: NotRequired[Dict[str, Any]]
    authorizing_resolution_id: NotRequired[Any]
    effective_date: NotRequired[Any]
    signing_date: NotRequired[Any]
    closing_date: NotRequired[Any]
    treatment: NotRequired[Dict[str, Any]]
    hsr_required: NotRequired[bool]
    regulatory_approvals: NotRequired[List[Dict[str, Any]]]
    section_280g_analysis: NotRequired[Dict[str, Any]]
    document_ids: NotRequired[List[str]]
    escrow_ids: NotRequired[List[str]]
    earn_out_ids: NotRequired[List[str]]
    indemnity_claim_ids: NotRequired[List[str]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class CourtOrder(TypedDict, total=False):
    """A court order recorded against a `CourtPetition`. Captures the"""
    object: Literal["court_order"]
    id: str
    court_petition_id: str
    entity_id: str
    order_kind: Literal["dissolution_security_determination", "distribution_plan_approval", "extension", "other"]
    court_approved_security_amount_cents: int
    approved_distribution_plan: Dict[str, Any]
    effective_date: str
    order_document_id: str
    chancery_docket_number: NotRequired[Any]
    appealable_until: NotRequired[Any]
    judge: NotRequired[Any]
    recorded_at: int
    created: int
    updated: NotRequired[int]
    livemode: bool
    metadata: NotRequired["Metadata"]

class CourtPetition(TypedDict, total=False):
    """Verified petition filed with a court of competent jurisdiction in"""
    object: Literal["court_petition"]
    id: str
    entity_id: str
    petition_kind: Literal["dgcl_280_dissolution", "dgcl_278_post_dissolution"]
    status: Literal["draft", "filed", "docketed", "under_review", "granted", "rejected_by_court", "withdrawn"]
    claims_summary: List[Dict[str, Any]]
    contingent_reserves_schedule: List[Dict[str, Any]]
    proposed_distribution_plan: Dict[str, Any]
    affidavit_document_ids: List[str]
    authorizing_resolution_id: NotRequired[Any]
    court: NotRequired[Any]
    chancery_docket_number: NotRequired[Any]
    court_docket_url: NotRequired[Any]
    filed_with_matter_at: NotRequired[Any]
    filed_with_court_at: NotRequired[Any]
    created: int
    updated: int
    livemode: bool
    metadata: NotRequired["Metadata"]

class CreditorClaimsWindow(TypedDict, total=False):
    """Statutory creditor-notice window run during dissolution under DGCL"""
    object: Literal["creditor_claims_window"]
    id: str
    entity_id: str
    procedure: Literal["default_281", "long_form_280", "short_form_282"]
    statutory_window_days: NotRequired[int]
    publication_date: NotRequired[Any]
    opened_at: NotRequired[Any]
    closes_at: NotRequired[Any]
    closed_at: NotRequired[Any]
    status: Literal["pending_publication", "open", "closed"]
    known_creditors: NotRequired[List[Dict[str, Any]]]
    publication_records: NotRequired[List[Dict[str, Any]]]
    claims_received: NotRequired[List[Dict[str, Any]]]
    created: int
    updated: int
    livemode: bool

class DataRoom(TypedDict, total=False):
    """Permissioned virtual data room scoped to a corporate transaction. Counterparty"""
    id: str
    object: Literal["data_room"]
    transaction_id: str
    name: str
    status: Literal["active", "expired", "revoked"]
    expires_at: NotRequired[Any]
    watermark_email: bool
    document_ids: NotRequired[List[str]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Director(TypedDict, total=False):
    """Canonical director record. Created by `changeDirector` (action: elect)"""
    id: str
    object: Literal["director"]
    entity_id: str
    stakeholder_id: str
    board_seat: NotRequired[int]
    status: Literal["active", "removed"]
    effective_date: str
    elected_via_resolution_id: NotRequired[str]
    removed_via_resolution_id: NotRequired[str]
    livemode: NotRequired[bool]

class Document(TypedDict, total=False):
    """Legal document. Dual artifact — structured JSON (`GET /documents/{id}`) and rendered"""
    id: str
    object: Literal["document"]
    entity_id: str
    type: Literal["certificate_of_incorporation", "certificate_of_amendment", "certificate_of_dissolution", "restated_certificate_of_incorporation", "bylaws", "operating_agreement", "secretary_certificate", "incorporator_certificate", "action_of_incorporator", "board_consent", "written_consent", "initial_board_resolution", "stockholders_agreement", "stock_certificate", "founder_stock_purchase_agreement", "stock_power", "stock_receipt", "equity_plan", "grant_notice", "83b_election", "indemnification_agreement", "safe", "convertible_note", "pro_rata_side_letter", "side_letter", "stock_purchase_agreement", "investors_rights_agreement", "voting_agreement", "rofr_co_sale_agreement", "management_rights_letter", "legal_opinion", "director_officer_questionnaire", "five_percent_holder_questionnaire", "accredited_investor_questionnaire", "loi", "merger_agreement", "asset_purchase_agreement", "annual_report", "boi_report", "form_966", "cap_table_snapshot", "registered_agent_appointment", "mail_scan", "identification_image", "csa", "mnda", "psa", "pilot_agreement", "design_partner_agreement", "software_license", "marketplace_terms", "reseller_agreement", "end_user_agreement", "online_cloud_terms", "independent_contractor_agreement", "advisor_agreement", "employment_agreement", "offer_letter", "ciiaa", "officer_change_consent", "director_change_consent", "trademark_application", "plan_of_dissolution", "notice_of_dissolution", "creditor_publication_record", "safe_release", "convertible_release", "ein_deactivation_letter", "ein_deactivation_acknowledgement", "records_retention_plan", "liquidating_distribution_statement", "final_form_966", "certificate_of_withdrawal", "form_1099_c", "settlement_agreement", "baa_termination_notice", "phi_return_destruction_attestation", "dpa_termination_notice", "cobra_qualifying_event_notice", "cobra_general_notice", "cobra_election_form", "cobra_termination_notice", "insurance_policy_termination_notice", "benefits_carrier_termination_acknowledgement", "payroll_provider_attestation", "benefit_plan_attestation", "cofounder_agreement", "cofounder_ip_assignment", "banking_authorization_certificate", "baa", "subprocessor_baa", "mfn_amendment", "separation_agreement", "eighty_three_b_amendment", "cobra_dissolution_honored_coverage_attestation", "chancery_court_order", "share_certificate_cancellation_declaration", "280g_cleansing_vote_disclosure_statement", "280g_excise_tax_assessment", "separation_agreement_with_mutual_release", "spousal_consent", "indemnity_carve_out_release", "pro_rata_release", "rd_credit_study", "transfer_agent_engagement_letter", "chancery_court_petition", "custom"]
    provenance: NotRequired[Literal["matter_generated", "counterpart_received", "user_uploaded"]]
    status: Literal["draft", "final", "signed", "filed", "efiled", "void"]
    execution_status: Literal["draft", "sent", "partially_signed", "executed", "void", "superseded", "terminated"]
    lifecycle_class: NotRequired[Literal["agreement", "tax_filing", "acknowledgement", "checklist", "counterpart_received"]]
    upstream_provenance: NotRequired[Any]
    terminated_at: NotRequired[Any]
    terminated_reason: NotRequired[Any]
    clause_toggles: NotRequired[List[Dict[str, Any]]]
    clause_toggle_changes: NotRequired[List[Dict[str, Any]]]
    internal_notes: NotRequired[Any]
    structured_clauses: NotRequired[List[Dict[str, Any]]]
    efile_metadata: NotRequired[Any]
    attaches_to: NotRequired[Any]
    attachment_kind: NotRequired[Any]
    related_documents: NotRequired[List[Dict[str, Any]]]
    cover_page_fields: NotRequired[Any]
    equity_promise: NotRequired[Any]
    standard_terms_template_id: NotRequired[Any]
    template_id: NotRequired[Any]
    template_version: NotRequired[Any]
    current_version_id: NotRequired[Any]
    entity_snapshot: NotRequired[Dict[str, Any]]
    payload: NotRequired[Dict[str, Any]]
    pdf_url: NotRequired[Any]
    sha256: str
    proof: NotRequired[Any]
    version: int
    parent_document_id: NotRequired[Any]
    signatures: NotRequired[List[Dict[str, Any]]]
    envelope_id: NotRequired[Any]
    sensitivity: NotRequired[Literal["standard", "restricted"]]
    disclaimer: NotRequired["Disclaimer"]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class DocumentAccessGrant(TypedDict, total=False):
    """Permissioned access to a document for a specific grantee (typically scoped to"""
    id: str
    object: Literal["document_access_grant"]
    document_id: str
    data_room_id: NotRequired[Any]
    grantee_email: str
    grantee_stakeholder_id: NotRequired[Any]
    permissions: List[Literal["view", "download", "comment"]]
    status: Literal["active", "expired", "revoked"]
    expires_at: NotRequired[Any]
    last_accessed_at: NotRequired[Any]
    access_count: NotRequired[int]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class DocumentVersion(TypedDict, total=False):
    """Immutable point-in-time snapshot of a `Document`. Each regenerate, sign,"""
    id: str
    object: Literal["document_version"]
    document_id: str
    version: int
    status: Literal["draft", "final", "signed", "filed", "void"]
    sha256: str
    payload: NotRequired[Dict[str, Any]]
    pdf_url: NotRequired[Any]
    proof: NotRequired[Any]
    actor_id: NotRequired[Any]
    change_kind: NotRequired[Literal["generated", "regenerated", "signed", "voided", "amended"]]
    previous_version_id: NotRequired[Any]
    created: int
    livemode: NotRequired[bool]

class EarnOut(TypedDict, total=False):
    """Contingent post-closing consideration tied to performance metrics. Common in"""
    id: str
    object: Literal["earn_out"]
    corporate_transaction_id: str
    metric: Literal["revenue", "ebitda", "gross_margin", "customer_count", "milestone_completion", "other"]
    target: "MonetaryAmount"
    max_payout: NotRequired["MonetaryAmount"]
    periods: NotRequired[List[Dict[str, Any]]]
    true_up_mechanic: NotRequired[Literal["period_only", "cumulative", "catch_up"]]
    formula: NotRequired[Any]
    current_status: NotRequired[Literal["active", "satisfied", "extinguished"]]
    payout_schedule: NotRequired[List[Dict[str, Any]]]
    status: Literal["active", "completed", "expired", "disputed"]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Entity(TypedDict, total=False):
    """A legal entity — the central object of the Matter API. Entities flow through the"""
    id: str
    object: Literal["entity"]
    status: Literal["draft", "submitted", "registered", "active", "suspended", "in_transaction", "dissolving", "winding_down", "tax_cleared", "dissolved", "acquired", "merged", "sold", "rejected", "cancelled"]
    type: Literal["c_corp", "s_corp", "llc", "benefit_corp", "nonprofit", "lp", "llp"]
    jurisdiction: "Jurisdiction"
    legal_name: str
    aliases: NotRequired[List[str]]
    formed_at: NotRequired[Any]
    dissolved_at: NotRequired[Any]
    acquired_at: NotRequired[Any]
    merged_at: NotRequired[Any]
    sold_at: NotRequired[Any]
    workspace_id: NotRequired[Any]
    corporate_transaction_id: NotRequired[Any]
    principal_address: NotRequired["Address"]
    mailing_address: NotRequired["Address"]
    registered_agent_id: NotRequired[str]
    incorporator_stakeholder_id: NotRequired[str]
    tax_profile_id: NotRequired[str]
    stakeholder_ids: NotRequired[List[str]]
    cap_table_id: NotRequired[str]
    equity_plan_ids: NotRequired[List[str]]
    qualifications: NotRequired[List["Qualification"]]
    compliance: NotRequired[Dict[str, Any]]
    intent_id: NotRequired[Any]
    incorporator_receipt_id: NotRequired[Any]
    portfolio_id: NotRequired[Any]
    governing_documents: NotRequired[Dict[str, Any]]
    formation_packet_status: NotRequired[Literal["not_started", "pending", "incorporator_action_complete", "bylaws_adopted", "initial_resolutions_executed", "founder_stock_issued", "83b_window_open", "indemnification_signed", "ein_obtained", "complete"]]
    external_status: NotRequired[Literal["pending", "registered", "failed", "prepared", "blocked"]]
    active_browser_agent_run_id: NotRequired[Any]
    browser_agent_run: NotRequired[Union["BrowserAgentRun", Any]]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class EntityTemplateOverride(TypedDict, total=False):
    """Entity-scoped overlay. Same shape as `OrgTemplateCustomization`,"""
    object: Literal["entity_template_override"]
    id: str
    entity_id: str
    org_id: str
    template_id: str
    mode: Literal["live", "sandbox", "test"]
    compatible_revisions_min: str
    compatible_revisions_max: str
    clause_overlays: List[Dict[str, Any]]
    field_default_overlays: List[Dict[str, Any]]
    signer_role_overrides: List[Dict[str, Any]]
    attachments: List[Dict[str, Any]]
    authored_against_revision_id: NotRequired[Any]
    deleted_at: NotRequired[Any]
    created: NotRequired[str]
    updated: NotRequired[str]

class EquityPlan(TypedDict, total=False):
    """Authorized option pool or stock plan. Grants are drawn from a plan."""
    id: str
    object: Literal["equity_plan"]
    entity_id: str
    name: str
    type: Literal["stock_plan", "option_pool"]
    authorized_shares: int
    reserved_shares: NotRequired[int]
    granted_shares: int
    available_shares: NotRequired[int]
    effective_date: str
    board_resolution_id: NotRequired[str]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Escrow(TypedDict, total=False):
    """Holdback of consideration at closing for indemnity, working-capital, or special-"""
    id: str
    object: Literal["escrow"]
    corporate_transaction_id: str
    amount: "MonetaryAmount"
    percent_of_consideration_basis_points: NotRequired[int]
    period_months: int
    agent: NotRequired[str]
    purpose: NotRequired[List[Literal["indemnity", "working_capital", "special_indemnity", "regulatory"]]]
    status: Literal["funded", "partial_release", "released", "claimed"]
    release_schedule: NotRequired[List[Dict[str, Any]]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Event(TypedDict, total=False):
    """Webhook event. Every state change emits exactly one. Strict per-subject ordering"""
    id: str
    object: Literal["event"]
    type: str
    api_version: str
    created: int
    data: Dict[str, Any]
    sequence: int
    livemode: bool
    pending_webhooks: NotRequired[int]
    request: NotRequired[Dict[str, Any]]
    authorized_by: NotRequired["AuthorizedBy"]

class EvidenceBundle(TypedDict, total=False):
    """Litigation-grade self-contained ZIP artifact produced by"""
    object: Literal["evidence_bundle"]
    id: str
    document_id: str
    archive_uri: str
    content_sha256: str
    manifest: Dict[str, Any]
    chain_signature: str
    created: str

class File(TypedDict, total=False):
    """A byte-level artifact — stakeholder KYC document, cap-table CSV import,"""
    id: str
    object: Literal["file"]
    purpose: Literal["kyc_document", "cap_table_import", "board_attachment", "dd_document", "resolution_attachment", "logo"]
    size: int
    type: str
    filename: NotRequired[Any]
    sha256: str
    linked_resources: NotRequired[List[Dict[str, Any]]]
    expires_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    livemode: bool

class FileLink(TypedDict, total=False):
    """A time-limited signed URL to a `File`'s bytes. Reissue after expiry."""
    id: str
    object: Literal["file_link"]
    file_id: str
    url: str
    expires_at: int
    metadata: NotRequired["Metadata"]
    created: int
    livemode: bool

class Filing(TypedDict, total=False):
    """A state or federal filing. Polymorphic — `payload` is discriminated by `type`."""
    id: str
    object: Literal["filing"]
    entity_id: str
    type: Literal["certificate_of_amendment", "annual_report", "franchise_tax", "final_franchise_tax", "boi_report", "boi_update", "boi_closure", "form_966", "form_1120", "form_1120w", "form_941", "form_941_final", "form_6765", "form_d", "blue_sky_notice", "stock_split", "custom", "eighty_three_b_election", "certificate_of_incorporation", "certificate_of_dissolution", "ein_application", "foreign_qualification", "registered_agent_change", "conversion", "certificate_of_merger", "articles_of_merger", "plan_of_merger", "bill_of_sale", "assignment_and_assumption_agreement", "stock_purchase_agreement", "form_8k_m_and_a", "ca_statement_of_information_final", "ca_form_100_final", "ca_ftb_tax_clearance_request", "ca_ftb_tax_clearance_certificate", "ca_certificate_of_surrender", "ny_franchise_tax_final", "ny_dot_consent_to_dissolution", "ny_certificate_of_surrender_of_authority", "tx_comptroller_tax_clearance_letter", "tx_certificate_of_withdrawal", "ma_form_355_final", "ma_dor_corporate_tax_clearance", "ma_certificate_of_surrender_foreign_corp", "ca_edd_clearance_request", "ny_dol_clearance_request", "wa_esd_clearance_request", "ma_dor_employer_clearance_request", "il_form_1120_final", "il_dor_tax_clearance_request", "il_dor_tax_clearance_certificate", "il_application_for_withdrawal_foreign_corp", "il_des_employer_clearance_request", "fl_form_f1120_final", "fl_dor_tax_clearance_request", "fl_dor_tax_clearance_certificate", "fl_application_for_withdrawal_foreign_corp", "wa_combined_excise_tax_return_final", "wa_dor_tax_clearance_request", "wa_dor_tax_clearance_certificate", "wa_certificate_of_withdrawal_foreign_corp", "co_form_dr0112_final", "co_dor_tax_clearance_request", "co_dor_tax_clearance_certificate", "co_statement_of_withdrawal_foreign_corp", "ga_form_600_final", "ga_dor_tax_clearance_request", "ga_dor_tax_clearance_certificate", "ga_application_for_certificate_of_withdrawal", "nj_form_cbt100_final", "nj_dot_tax_clearance_request", "nj_dot_tax_clearance_certificate", "nj_certificate_of_withdrawal_foreign_corp", "pa_form_rct101_final", "pa_dor_tax_clearance_request", "pa_dor_tax_clearance_certificate", "pa_application_for_termination_of_authority", "va_form_500_final", "va_dot_tax_clearance_request", "va_dot_tax_clearance_certificate", "va_application_for_certificate_of_withdrawal", "irs_ein_deactivation_request", "irs_form_1099_c", "irs_form_5310", "irs_form_5500_final", "ca_state_withholding_final", "ca_state_unemployment_final", "ny_state_withholding_final", "ny_state_unemployment_final", "wa_state_withholding_final", "wa_state_unemployment_final", "ma_state_withholding_final", "ma_state_unemployment_final", "irs_form_1094c_final", "irs_form_1095c_final", "il_des_employer_account_closure", "il_dor_withholding_account_closure", "ga_dol_employer_account_closure", "ga_dor_withholding_account_closure", "fl_dor_reemployment_account_closure", "co_dor_employer_account_closure", "ca_de_9", "ca_de_9c", "ny_nys_45", "il_ui_3_40", "tx_twc_c3", "tx_public_information_report", "tx_franchise_tax_report", "revival_filing", "form_8x", "irs_audit_response_4470", "boi_closure_foreign_reporting", "chancery_court_petition_filing", "chancery_court_order_recording"]
    jurisdiction: "Jurisdiction"
    status: Literal["preparing", "submitted", "accepted", "rejected", "amended", "cancelled"]
    payload: NotRequired[Union["FilingPayloadCertificateOfAmendment", "FilingPayloadAnnualReport", "FilingPayloadFranchiseTax", "FilingPayloadBoiInitial", "FilingPayloadBoiUpdate", "FilingPayloadForm966", "FilingPayloadFormD", "FilingPayloadCustom"]]
    submitted_at: NotRequired[Any]
    accepted_at: NotRequired[Any]
    rejected_reason: NotRequired[Any]
    state_confirmation_number: NotRequired[Any]
    document_ids: NotRequired[List[str]]
    authorizing_resolution_id: NotRequired[Any]
    authorizing_corporate_transaction_id: NotRequired[Any]
    prerequisite_filings: NotRequired[List[str]]
    depends_on: NotRequired[List[str]]
    final_return: NotRequired[bool]
    post_dissolution_filing: NotRequired[bool]
    fees: NotRequired[Dict[str, Any]]
    cancellation_window_ends_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class FormationSession(TypedDict, total=False):
    """Tracks the multi-step formation flow for a single entity"""
    id: str
    object: Literal["formation_session"]
    entity_id: str
    intent_id: NotRequired[Any]
    mode: Literal["live", "sandbox", "test"]
    status: Literal["started", "entity_created", "docs_signed", "filing_submitted", "ein_received", "bank_opened", "active", "expired"]
    current_step: str
    progress: NotRequired[Any]
    started_at: str
    completed_at: NotRequired[Any]
    version: int
    created_at: str
    updated_at: str

class Grant(TypedDict, total=False):
    """Option, RSU, or restricted-stock grant. The `kind` enum covers both"""
    id: str
    object: Literal["grant"]
    entity_id: str
    stakeholder_id: str
    equity_plan_id: NotRequired[Any]
    kind: Literal["iso", "nso", "rsu", "rsa", "founder_restricted_stock"]
    quantity: int
    strike_price: NotRequired["MonetaryAmount"]
    valuation_id: NotRequired[Any]
    vesting_schedule: NotRequired[Dict[str, Any]]
    acceleration_condition: NotRequired[Any]
    acceleration_events: NotRequired[List[Dict[str, Any]]]
    clawback: NotRequired[Any]
    election_83b: NotRequired[Any]
    founder_restricted_stock_terms: NotRequired[Any]
    amended_from_grant_id: NotRequired[Any]
    amendment_reason: NotRequired[Any]
    grant_date: str
    expiration_date: NotRequired[Any]
    exercised_quantity: NotRequired[int]
    document_id: NotRequired[Any]
    qsbs_eligibility_date: NotRequired[Any]
    pre_409a_grant_pause_until: NotRequired[Any]
    status: NotRequired[Literal["active", "handshake_pending", "vesting", "vested", "exercised", "cancelled"]]
    activated_at: NotRequired[Any]
    documents: NotRequired[Dict[str, Any]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class IncorporatorReceipt(TypedDict, total=False):
    """Immutable cryptographic proof issued at the end of a successful incorporator"""
    object: Literal["incorporator_receipt"]
    id: str
    entity_id: str
    genesis_ceremony_id: str
    audit_chain_root_hash: str
    rekor_inclusion_proof: NotRequired[Any]
    witness_signatures: NotRequired[Any]
    issued_at: str
    created_at: str
    updated_at: str

class IndemnificationAgreement(TypedDict, total=False):
    """Director-and-officer indemnification covenant between an entity and an"""
    id: str
    object: Literal["indemnification_agreement"]
    entity_id: str
    indemnitee_stakeholder_id: str
    role: Literal["director", "officer", "both"]
    authorizing_resolution_id: NotRequired[Any]
    document_id: NotRequired[Any]
    envelope_id: NotRequired[Any]
    effective_date: NotRequired[Any]
    termination_date: NotRequired[Any]
    coverage: NotRequired[Dict[str, Any]]
    status: Literal["draft", "sent", "signed", "terminated", "void"]
    signed_at: NotRequired[Any]
    terminated_at: NotRequired[Any]
    termination_reason: NotRequired[Any]
    carve_outs: NotRequired[List[Dict[str, Any]]]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class IndemnityClaim(TypedDict, total=False):
    """A claim by acquirer (or rarely seller) under the definitive agreement's"""
    id: str
    object: Literal["indemnity_claim"]
    corporate_transaction_id: str
    claimant: str
    amount: "MonetaryAmount"
    basis: str
    fundamental_carveout: NotRequired[bool]
    response_deadline: NotRequired[Any]
    status: Literal["filed", "accepted", "disputed", "paid", "denied", "withdrawn"]
    kind: NotRequired[Any]
    resolution_path: NotRequired[Any]
    release_document_id: NotRequired[Any]
    escrow_id: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Intent(TypedDict, total=False):
    """Customer-facing label: **Incorporation plan** (or, more generally, a"""
    id: str
    object: Literal["intent"]
    goal: Literal["start_company", "hire_worker", "bring_on_advisor", "take_investment", "raise_capital", "expand_equity_pool", "open_bank_account", "send_customer_contract", "make_decision", "refresh_valuation", "stay_compliant", "expand_to_state", "prepare_for_fundraise", "sell_company", "wind_down", "elect_s_corp", "register_dba", "obtain_ein", "form_startup_ready_corporation", "form_llc", "form_benefit_corp", "form_nonprofit", "dissolve_entity", "foreign_qualify", "convert_entity", "issue_priced_round", "issue_safe_round", "refresh_option_pool", "execute_merger", "execute_acquisition", "execute_asset_sale", "execute_stock_sale", "execute_reorganization"]
    parameters: Union["StartCompanyParameters", "HireWorkerParameters", "TakeInvestmentParameters", "MakeDecisionParameters", Dict[str, Any]]
    status: Literal["draft", "resolved", "executing", "completed", "cancelled", "failed"]
    execution_plan: NotRequired["ExecutionPlan"]
    entity_id: NotRequired[Any]
    cost_estimate: NotRequired["MonetaryAmount"]
    completed_at: NotRequired[Any]
    resolved_recommendations: NotRequired[List["Recommendation"]]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class Invoice(TypedDict, total=False):
    """An invoice issued to the account — entity-license subscription invoices and"""
    id: str
    object: Literal["invoice"]
    account_id: str
    number: NotRequired[Any]
    status: Literal["draft", "open", "paid", "void", "uncollectible"]
    total: "MonetaryAmount"
    lines: NotRequired[List[Dict[str, Any]]]
    hosted_invoice_url: NotRequired[Any]
    pdf_url: NotRequired[Any]
    period_start: NotRequired[Any]
    period_end: NotRequired[Any]
    paid_at: NotRequired[Any]
    created: int
    updated: int
    livemode: bool

class JurisdictionVariant(TypedDict, total=False):
    """Per-jurisdiction overrides applied between the platform body"""
    object: Literal["jurisdiction_variant"]
    id: str
    template_revision_id: str
    jurisdiction: str
    clause_overrides: NotRequired[Dict[str, Any]]
    signer_overrides: NotRequired[Dict[str, Any]]
    legal_basis_overrides: NotRequired[Dict[str, Any]]

class LedgerEntry(TypedDict, total=False):
    """One append-only money movement on the account's prepaid ledger. Entries are"""
    id: str
    object: Literal["ledger_entry"]
    account_id: str
    kind: Literal["top_up", "auto_recharge", "usage_debit", "license_debit", "fee_passthrough_debit", "adjustment_credit", "adjustment_debit", "refund_reversal", "promo_credit", "expiry", "sandbox_seed"]
    amount: "MonetaryAmount"
    balance_after: "MonetaryAmount"
    source_type: Literal["payment", "refund", "usage_window", "request", "saga", "manual", "reconciliation", "sandbox"]
    source_id: str
    request_id: NotRequired[Any]
    created: int
    livemode: bool

class LegalOpinion(TypedDict, total=False):
    """Closing-condition legal opinion delivered by counsel. Standard on priced"""
    id: str
    object: Literal["legal_opinion"]
    entity_id: str
    parent: Dict[str, Any]
    issuing_firm: str
    issuing_attorney: NotRequired[Any]
    opinions_covered: NotRequired[List[Literal["corporate_existence", "due_authorisation", "valid_issuance", "non_assessability", "exemption_from_registration", "no_conflict_with_charter", "no_conflict_with_material_contracts", "enforceability_of_transaction_documents", "regulatory_compliance", "title_to_assets", "tax", "custom"]]]
    document_id: NotRequired[Any]
    delivered_at: NotRequired[Any]
    status: Literal["requested", "drafting", "delivered", "withdrawn"]
    qualifications: NotRequired[List[str]]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class MailItem(TypedDict, total=False):
    """One piece of inbound correspondence received by the registered agent on behalf of an"""
    id: str
    object: Literal["mail_item"]
    entity_id: str
    source: Literal["registered_agent_scan"]
    category: Literal["service_of_process", "tax_notice", "state_notice", "court_filing", "bank", "vendor", "junk", "other"]
    status: Literal["received", "acknowledged", "responded", "escalated", "archived"]
    sender: NotRequired[Any]
    return_address: NotRequired[Union["Address", Any]]
    subject: NotRequired[Any]
    ocr_text: NotRequired[Any]
    extracted: NotRequired[Any]
    response_deadline: NotRequired[Any]
    received_at: int
    scanned_at: NotRequired[Any]
    scan_document_id: NotRequired[Any]
    response_document_id: NotRequired[Any]
    related_filing_id: NotRequired[Any]
    escalation_authorization_id: NotRequired[Any]
    forwarding: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class Officer(TypedDict, total=False):
    """Canonical officer record. Created by `changeOfficer` (action: appoint)"""
    id: str
    object: Literal["officer"]
    entity_id: str
    stakeholder_id: str
    title: Literal["ceo", "president", "coo", "cto", "cfo", "secretary", "treasurer"]
    status: Literal["active", "removed"]
    effective_date: str
    appointed_via_resolution_id: NotRequired[str]
    removed_via_resolution_id: NotRequired[str]
    removed_at: NotRequired[str]
    livemode: NotRequired[bool]

class OrgTemplateCustomization(TypedDict, total=False):
    """Org-scoped overlay — applies to every entity in the org. Per"""
    object: Literal["org_template_customization"]
    id: str
    org_id: str
    template_id: str
    mode: Literal["live", "sandbox", "test"]
    compatible_revisions_min: str
    compatible_revisions_max: str
    clause_overlays: List[Dict[str, Any]]
    field_default_overlays: List[Dict[str, Any]]
    signer_role_overrides: List[Dict[str, Any]]
    attachments: List[Dict[str, Any]]
    authored_against_revision_id: NotRequired[Any]
    deleted_at: NotRequired[Any]
    created: NotRequired[str]
    updated: NotRequired[str]
    created_by_token_id: NotRequired[Any]
    updated_by_token_id: NotRequired[Any]

class ParachuteAnalysis(TypedDict, total=False):
    """Structured §280G analysis attached to a `CorporateTransaction`. Identifies"""
    id: str
    object: Literal["parachute_analysis"]
    corporate_transaction_id: str
    analysis_kind: Literal["pre_close", "post_close_recharacterization", "revised"]
    status: Literal["draft", "computed", "disclosed", "voted_passed", "voted_failed", "extinguished"]
    disqualified_individuals: List[Dict[str, Any]]
    parachute_payments_breakdown: List[Dict[str, Any]]
    disclosure_document_id: NotRequired[Any]
    cleansing_vote_resolution_id: NotRequired[Any]
    tax_counsel_firm: NotRequired[Any]
    override_assumptions: NotRequired[Any]
    computed_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class Portfolio(TypedDict, total=False):
    """Venture-studio grouping. First-class resource — safer than implicit header-based"""
    id: str
    object: Literal["portfolio"]
    mode: Literal["live", "sandbox", "test"]
    name: str
    shared_registered_agent_id: Any
    shared_compliance_calendar: bool
    entity_ids: List[str]
    version: int
    metadata: "Metadata"
    created_at: str
    updated_at: str

class Qualification(TypedDict, total=False):
    """A foreign qualification — registration of an entity in a non-home jurisdiction."""
    id: str
    object: Literal["qualification"]
    entity_id: str
    jurisdiction: "Jurisdiction"
    status: Literal["qualifying", "qualified", "withdrawing", "withdrawn"]
    qualified_at: NotRequired[Any]
    registered_agent_id: NotRequired[Any]
    compliance_track: NotRequired[Dict[str, Any]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Questionnaire(TypedDict, total=False):
    """Structured questionnaire collected from a stakeholder. Used as a closing"""
    id: str
    object: Literal["questionnaire"]
    entity_id: str
    kind: Literal["director_officer", "five_percent_holder", "accredited_investor", "kyc"]
    subject_stakeholder_id: str
    related_round_id: NotRequired[Any]
    related_corporate_transaction_id: NotRequired[Any]
    responses: NotRequired[Union["QuestionnaireResponseDirectorOfficer", "QuestionnaireResponseFivePercentHolder", "QuestionnaireResponseAccreditedInvestor", "QuestionnaireResponseKyc"]]
    document_id: NotRequired[Any]
    envelope_id: NotRequired[Any]
    signed_at: NotRequired[Any]
    status: Literal["draft", "sent", "completed", "signed", "void"]
    verification: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class RegisteredAgent(TypedDict, total=False):
    """Registered agent of record in a jurisdiction. Required by every state. Swapping a"""
    id: str
    object: Literal["registered_agent"]
    entity_id: str
    jurisdiction: "Jurisdiction"
    provider: Literal["matter", "external"]
    external_provider_name: NotRequired[Any]
    address: "Address"
    effective_date: str
    terminated_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class ReportRun(TypedDict, total=False):
    """An async report run. Starts in `pending`, advances through `running` to"""
    id: str
    object: Literal["report_run"]
    report_type: Literal["portfolio_compliance_coverage", "cap_table_snapshot", "audit_log_export", "filing_history"]
    status: Literal["pending", "running", "succeeded", "failed"]
    parameters: Dict[str, Any]
    format: NotRequired[Literal["csv", "json", "jsonl", "xlsx"]]
    result: NotRequired[Any]
    error: NotRequired[Any]
    started_at: NotRequired[Any]
    finished_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: NotRequired[int]
    livemode: bool

class Request(TypedDict, total=False):
    """Record of a single API request. Retained 7 days by default (extensible per plan)."""
    id: str
    object: Literal["request"]
    method: Literal["GET", "POST", "DELETE", "PATCH", "PUT"]
    path: str
    status: int
    idempotency_key: NotRequired[Any]
    actor: NotRequired[Dict[str, Any]]
    authorized_by: NotRequired["AuthorizedBy"]
    request_body: NotRequired[Any]
    response_body: NotRequired[Any]
    occurred_at: int
    livemode: bool

class Resolution(TypedDict, total=False):
    """Board meeting or written consent authorizing entity actions."""
    id: str
    object: Literal["resolution"]
    entity_id: str
    kind: Literal["board_meeting", "written_consent", "bylaws_adoption", "officer_election", "bank_account_authorisation", "share_issuance_authorisation", "option_plan_adoption", "indemnification_form_approval", "registered_agent_appointment", "safe_issuance", "priced_round_authorisation", "merger_approval", "stockholder_consent_merger", "acquisition_approval", "asset_sale_approval", "stock_sale_approval", "transaction_authorisation", "plan_of_dissolution", "dissolution_authorisation", "dissenters_rights_waiver", "benefit_plan_adoption", "benefit_plan_termination", "benefit_plan_administrator_designation", "state_employer_account_closure", "amend_founder_grants", "authorize_share_repurchase", "authorize_distribution", "founder_stock_repurchase_authorization", "officer_change", "officer_reslate_after_departure", "separation_agreement_authorization", "cleansing_vote", "280g_recharacterization_acknowledgement", "court_supervised_dissolution_authorisation", "acquihire_authorisation", "share_repurchase_authorisation"]
    subject: str
    resolved_at: NotRequired[Any]
    variant: NotRequired[Any]
    signatories: NotRequired[List[Dict[str, Any]]]
    officer_changes: NotRequired[List[Dict[str, Any]]]
    document_id: NotRequired[Any]
    authorizes_filings: NotRequired[List[str]]
    authorizes_agreements: NotRequired[List[str]]
    authorizes_grants: NotRequired[List[str]]
    authorizes_share_reservations: NotRequired[List[str]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Round(TypedDict, total=False):
    """Priced-round envelope. Owns the multi-week negotiation between term-sheet entry"""
    id: str
    object: Literal["round"]
    entity_id: str
    name: str
    kind: Literal["seed_priced", "series_a", "series_b", "series_c", "series_d", "series_e_plus", "bridge_priced", "recap"]
    stage: Literal["term_sheet", "drafting", "signed", "closed", "cancelled"]
    pre_money: NotRequired["MonetaryAmount"]
    investment: NotRequired["MonetaryAmount"]
    post_money: NotRequired["MonetaryAmount"]
    price_per_share: NotRequired["MonetaryAmount"]
    option_pool_refresh_basis_points: NotRequired[int]
    pre_money_pool_shuffle: NotRequired[bool]
    share_class_id: NotRequired[Any]
    share_class: NotRequired[Dict[str, Any]]
    board_reconstitution: NotRequired[Dict[str, Any]]
    investors: NotRequired[List[Dict[str, Any]]]
    mfn_holders: NotRequired[List[str]]
    closing_conditions: NotRequired[List[Dict[str, Any]]]
    governing_documents: NotRequired[Dict[str, Any]]
    post_close_governance: NotRequired[Dict[str, Any]]
    qualified_financing_for_safes: NotRequired[bool]
    authorizing_resolution_id: NotRequired[Any]
    document_ids: NotRequired[List[str]]
    signing_date: NotRequired[Any]
    closing_date: NotRequired[Any]
    partial_closes: NotRequired[List[Dict[str, Any]]]
    pre_close_snapshot_id: NotRequired[Any]
    post_close_snapshot_id: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class ShareClass(TypedDict, total=False):
    """A class of shares authorized for an entity (Common, Series Seed, Series A, etc.)."""
    id: str
    object: Literal["share_class"]
    entity_id: str
    name: str
    kind: NotRequired[Literal["common", "preferred"]]
    series: NotRequired[Any]
    authorized: int
    issued: int
    par_value: "MonetaryAmount"
    liquidation_preference: NotRequired[Any]
    conversion_rights: NotRequired[Dict[str, Any]]
    voting_rights: NotRequired[Dict[str, Any]]
    certificate_of_designations_document_id: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class ShareLedgerEntry(TypedDict, total=False):
    """One entry per equity event. Covers traditional share mutations"""
    id: str
    object: Literal["share_ledger_entry"]
    entity_id: str
    kind: Literal["issuance", "transfer", "cancellation", "repurchase", "founder_repurchase_to_treasury", "safe_grant", "safe_conversion", "note_grant", "note_conversion", "liquidating_distribution", "liquidation_preference_payout", "convertible_cancellation"]
    share_class_id: NotRequired[Any]
    from_stakeholder_id: NotRequired[Any]
    to_stakeholder_id: NotRequired[Any]
    quantity: NotRequired[Any]
    price_per_share: NotRequired["MonetaryAmount"]
    consideration: NotRequired[str]
    certificate_number: NotRequired[Any]
    transaction_date: str
    principal_amount: NotRequired[Union["MonetaryAmount", Any]]
    safe_type: NotRequired[Any]
    safe_money_position: NotRequired[Any]
    safe_variant: NotRequired[Any]
    safe_jurisdiction: NotRequired[Any]
    pro_rata_rights: NotRequired[Any]
    qualifying_financing_threshold_cents: NotRequired[Any]
    mfn: NotRequired[Any]
    mfn_window_months: NotRequired[Any]
    mfn_amendments: NotRequired[List[Dict[str, Any]]]
    interest_rate: NotRequired[Any]
    discount_rate: NotRequired[Any]
    valuation_cap: NotRequired[Union["MonetaryAmount", Any]]
    maturity_date: NotRequired[Any]
    references_entry_id: NotRequired[Any]
    document_ids: NotRequired[List[str]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class SideLetter(TypedDict, total=False):
    """Investor side letter granting individual rights beyond the standard"""
    id: str
    object: Literal["side_letter"]
    entity_id: str
    parent: Dict[str, Any]
    investor_stakeholder_id: str
    clauses: List[Dict[str, Any]]
    document_id: NotRequired[Any]
    envelope_id: NotRequired[Any]
    signed_at: NotRequired[Any]
    status: Literal["draft", "sent", "executed", "terminated", "void"]
    terminated_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class SigningEnvelope(TypedDict, total=False):
    """Coordinates multi-party signing of one or more `Document`s. Per-document"""
    id: str
    object: Literal["signing_envelope"]
    entity_id: str
    subject: NotRequired[str]
    document_ids: List[str]
    signers: List["EnvelopeSigner"]
    routing: Literal["parallel", "sequential"]
    status: Literal["draft", "sent", "completed", "declined", "expired", "voided"]
    sent_at: NotRequired[Any]
    completed_at: NotRequired[Any]
    expires_at: NotRequired[Any]
    last_reminder_at: NotRequired[Any]
    reminder_policy: NotRequired[Dict[str, Any]]
    message: NotRequired[str]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class SigningSession(TypedDict, total=False):
    """Short-lived bearer for human-signature-over-API (Rail 1, Shape 2). Issued via"""
    id: str
    object: Literal["signing_session"]
    target: Dict[str, Any]
    stakeholder_id: str
    human_clerk_user_id: str
    created_at: int
    expires_at: int
    status: Literal["pending", "consumed", "expired", "revoked"]
    signature_token: NotRequired[Any]
    disclosure_packet_hash: NotRequired[str]
    livemode: bool

class Stakeholder(TypedDict, total=False):
    """A person (or another entity) associated with a Matter entity. Roles are an array —"""
    id: str
    object: Literal["stakeholder"]
    entity_id: str
    kind: Literal["natural_person", "entity"]
    name: str
    contact: NotRequired[Dict[str, Any]]
    tax_id: NotRequired[str]
    residency: NotRequired[str]
    date_of_birth: NotRequired[Any]
    residential_address: NotRequired[Union["Address", Any]]
    identification: NotRequired[Any]
    boi_eligibility: NotRequired[Literal["ready", "missing_fields", "not_applicable"]]
    boi_missing_fields: NotRequired[List[Literal["date_of_birth", "residential_address", "identification.type", "identification.number", "identification.jurisdiction", "identification.image_document_id"]]]
    beneficial_owner_percentage: NotRequired[Any]
    voting_percentage: NotRequired[Any]
    cap_table_percentage: NotRequired[Any]
    boi_filing_status: NotRequired[Literal["not_required", "pending", "filed", "exempt", "amended_required"]]
    experience_level: NotRequired[Literal["novice", "technical", "serial"]]
    accredited_investor_status: NotRequired[Literal["unknown", "self_certified", "verified", "not_accredited"]]
    five_percent_holder: NotRequired[bool]
    ip_assignment_scope: NotRequired[Literal["full", "limited", "none", "not_applicable"]]
    consideration_for_initial_shares: NotRequired[Any]
    signed_artifacts: NotRequired[List[Dict[str, Any]]]
    status: NotRequired[Literal["active", "separating", "separated", "separated_to_acquirer"]]
    roles: List[Dict[str, Any]]
    residence_state: NotRequired[Any]
    marital_status: NotRequired[Literal["single", "married", "domestic_partnership_with_cp", "separated", "divorced", "widowed", "unknown"]]
    spouse_id: NotRequired[Any]
    spouse_name: NotRequired[Any]
    spouse_tax_id_token: NotRequired[Any]
    separated_at: NotRequired[Any]
    separation_kind: NotRequired[Any]
    separation_reason: NotRequired[Any]
    transitioned_to_acquirer_id: NotRequired[Any]
    community_property_state_at_grant: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: int
    updated: int
    livemode: bool

class StakeholderPortalSession(TypedDict, total=False):
    """Hosted URL where a stakeholder accepts grants, signs 83(b) elections, downloads"""
    id: str
    object: Literal["stakeholder_portal_session"]
    stakeholder_id: str
    url: str
    return_url: str
    scope: List[Literal["grants", "documents", "vesting", "tax_elections", "cap_table_view"]]
    metadata: NotRequired["Metadata"]
    expires_at: int
    created: int
    livemode: bool

class StateRegistration(TypedDict, total=False):
    """State-level registration filed via the registered-agent partner."""
    object: Literal["state_registration"]
    id: str
    entity_id: str
    registration_kind: Literal["employer", "sales_tax", "dba", "business_license"]
    agency: NotRequired[Any]
    agency_account_kind: NotRequired[Any]
    jurisdiction: Dict[str, Any]
    status: Literal["pending", "confirmed", "lapsed", "closing", "closed", "withdrawn"]
    effective_date: str
    confirmed_at: NotRequired[Any]
    closed_at: NotRequired[Any]
    closure_status: NotRequired[Any]
    state_account_number: NotRequired[Any]
    trade_name: NotRequired[Any]
    trigger: NotRequired[Any]
    registered_agent_partner_id: NotRequired[Any]
    obligations: NotRequired[List[Dict[str, Any]]]

class SubAgentSession(TypedDict, total=False):
    """Async wrapper for a government or partner web interface that doesn't"""
    id: str
    object: Literal["sub_agent_session"]
    status: Literal["pending", "running", "completed", "failed", "cancelled"]
    target_resource: Dict[str, Any]
    agent_kind: Literal["de_sos_filer", "fincen_boir_filer", "irs_mef_filer", "irs_id_me_efiler", "irs_ss4_filer", "mercury_onboarding", "brex_onboarding", "state_sos_qualification"]
    target_url: NotRequired[str]
    created_at: str
    started_at: NotRequired[str]
    completed_at: NotRequired[str]
    outcome: NotRequired[Dict[str, Any]]
    actions_taken: NotRequired[List[Dict[str, Any]]]
    livemode: NotRequired[bool]

class TaxElection(TypedDict, total=False):
    """A tax election filed for an entity (S-Corp, §83(b), check-the-box, late-election"""
    id: str
    object: Literal["tax_election"]
    entity_id: str
    kind: Literal["s_corp", "section_83b", "check_the_box", "late_election_relief", "qsbs_attestation", "accounting_method_change", "consolidated_return_election", "extension_request"]
    status: Literal["pending", "filed", "accepted", "rejected"]
    effective_date: str
    filing_id: NotRequired[Any]
    document_id: NotRequired[Any]
    grant_id: NotRequired[Any]
    share_lot_id: NotRequired[Any]
    qsbs: NotRequired[Any]
    target_classification: NotRequired[Any]
    shareholder_consents: NotRequired[List[str]]
    original_election_kind: NotRequired[Any]
    reason_for_failure: NotRequired[Any]
    rejection_reason: NotRequired[Any]
    accepted_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class TaxProfile(TypedDict, total=False):
    """Tax identifiers and elections for an entity. Election state mirrors filings"""
    id: str
    object: Literal["tax_profile"]
    entity_id: str
    ein: NotRequired[Any]
    state_tax_ids: NotRequired[Dict[str, str]]
    s_corp_election_status: NotRequired[Literal["none", "filed", "accepted"]]
    fiscal_year_end: NotRequired[str]
    accounting_method: NotRequired[Any]
    first_taxable_year_end: NotRequired[Any]
    boi_filing_status: NotRequired[Literal["not_required", "pending", "filed", "exempt", "amended_required"]]
    elections: NotRequired[List["TaxElection"]]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class Template(TypedDict, total=False):
    """Metadata for a Matter-authored document template that"""
    object: Literal["template"]
    template_id: str
    name: str
    kind: str
    category: Literal["formation", "financing", "commercial", "governance", "tax"]
    version: str
    availability: Literal["preview", "ga", "deprecated", "retired"]
    successor_template_id: NotRequired[Any]
    cover_page_field_schema: NotRequired[Any]
    attachable_to: NotRequired[List[str]]

class TemplateClause(TypedDict, total=False):
    """Content-addressed clause node. The `position` field encodes the"""
    object: Literal["template_clause"]
    id: str
    revision_id: str
    parent_clause_id: NotRequired[Any]
    body_mdx_fragment: str
    position: Dict[str, Any]
    content_sha256: str
    is_attribution_node: NotRequired[bool]
    template_source_id: NotRequired[Any]

class TemplateRenderJob(TypedDict, total=False):
    """Queued render execution. Drained by the existing BackgroundJob +"""
    object: Literal["template_render_job"]
    id: str
    template_id: str
    template_revision_id: str
    entity_id: str
    org_id: str
    jurisdiction: str
    overlay_hash: str
    render_fingerprint: str
    authorizing_token_id: str
    mode: Literal["live", "sandbox", "test"]
    status: Literal["queued", "rendering", "succeeded", "failed"]
    document_id: NotRequired[Any]
    error: NotRequired[Any]
    queued_at: str
    started_at: NotRequired[Any]
    completed_at: NotRequired[Any]
    render_region: NotRequired[str]

class TemplateRevision(TypedDict, total=False):
    """Immutable content-addressed snapshot of a template at a specific"""
    object: Literal["template_revision"]
    id: str
    template_id: str
    version: str
    sha256: str
    manifest: Dict[str, Any]
    availability: Literal["preview", "ga", "deprecated", "retired"]
    visibility: Literal["platform", "org_private", "published"]
    publisher_org_id: NotRequired[Any]
    parent_revision_id: NotRequired[Any]
    mode: Literal["live", "sandbox", "test"]
    source_id: NotRequired[Any]
    created: str
    created_by_token_id: NotRequired[Any]

class TemplateSource(TypedDict, total=False):
    """Upstream-repo provenance for ingested templates. `commit_sha` is"""
    object: Literal["template_source"]
    id: str
    repo_url: str
    commit_sha: str
    license: str
    attribution_text: NotRequired[Any]
    ingested_at: str
    normalizer_version: str

class TestClock(TypedDict, total=False):
    """A simulated wall-clock for test-mode entities. Attach entities via"""
    id: str
    object: Literal["test_clock"]
    name: NotRequired[Any]
    frozen_time: int
    status: Literal["ready", "advancing", "failed"]
    attached_entity_count: NotRequired[int]
    metadata: NotRequired["Metadata"]
    created: int
    updated: NotRequired[int]
    livemode: bool

class Token(TypedDict, total=False):
    """Scoped access token. `sk_live_` / `sk_test_` / `pk_live_` / `pk_test_` are special"""
    id: str
    object: Literal["token"]
    tier: Any
    scopes: NotRequired[List[Dict[str, Any]]]
    principal: Dict[str, Any]
    portfolio_id: NotRequired[Any]
    limits: NotRequired[Dict[str, Any]]
    allowance: NotRequired[Any]
    api_version: str
    revoked_at: NotRequired[Any]
    last_used_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class TopUp(TypedDict, total=False):
    """One prepaid credit purchase. Created in `pending` with a hosted checkout"""
    id: str
    object: Literal["top_up"]
    account_id: str
    amount: "MonetaryAmount"
    status: Literal["pending", "succeeded", "failed", "expired", "refunded"]
    initiator: Literal["human", "auto_recharge", "agent"]
    checkout_url: NotRequired[Any]
    payment_method_type: NotRequired[Any]
    failure_code: NotRequired[Any]
    ledger_entry_id: NotRequired[Any]
    created: int
    updated: int
    livemode: bool

class Trademark(TypedDict, total=False):
    """A USPTO trademark application or registration for a mark used by"""
    object: Literal["trademark"]
    id: str
    entity_id: str
    mark: str
    drawing_kind: NotRequired[Literal["standard_character", "special_form"]]
    drawing_file_id: NotRequired[Any]
    classes: List[Dict[str, Any]]
    jurisdiction: Literal["US"]
    basis_of_filing: Literal["actual_use", "intent_to_use"]
    status: Literal["pending_filing", "filed", "published_for_opposition", "opposed", "notice_of_allowance", "registered", "abandoned", "cancelled", "expired"]
    first_use_date: NotRequired[Any]
    first_use_in_commerce_date: NotRequired[Any]
    specimen_file_id: NotRequired[Any]
    serial_number: NotRequired[Any]
    registration_number: NotRequired[Any]
    filed_at: NotRequired[Any]
    published_at: NotRequired[Any]
    notice_of_allowance_at: NotRequired[Any]
    registered_at: NotRequired[Any]
    related_search_id: NotRequired[Any]
    application_attributes: NotRequired[Dict[str, Any]]
    statement_of_use: NotRequired[Any]
    maintenance_obligations: NotRequired[List[Dict[str, Any]]]
    related_document_id: NotRequired[Any]
    partner_filing_id: NotRequired[Any]

class TrademarkSearch(TypedDict, total=False):
    """A USPTO TESS search snapshot for a proposed mark + class combination."""
    object: Literal["trademark_search"]
    id: str
    entity_id: str
    mark: str
    classes: List[int]
    jurisdiction: Literal["US"]
    search_date: str
    result: Literal["clear", "minor_conflicts", "blocking_conflicts"]
    conflicts: NotRequired[List[Dict[str, Any]]]
    snapshot_url: NotRequired[str]

class Transfer(TypedDict, total=False):
    """Money movement on a BankAccount — outgoing (initiated via"""
    object: Literal["transfer"]
    id: str
    bank_account_id: str
    transfer_kind: Literal["ach_credit", "ach_debit", "domestic_wire", "international_wire", "check_issued", "check_deposited", "ach_received", "wire_received"]
    direction: Literal["incoming", "outgoing"]
    amount_usd_cents: int
    status: Literal["pending", "completed", "failed", "returned"]
    counterparty: NotRequired[Dict[str, Any]]
    memo: NotRequired[Any]
    authorizing_stakeholder_id: NotRequired[Any]
    initiated_at: NotRequired[str]
    completed_at: NotRequired[Any]
    partner_transfer_id: NotRequired[Any]

class TransferAgent(TypedDict, total=False):
    """A third-party transfer agent engaged to manage share certificates,"""
    id: str
    object: Literal["transfer_agent"]
    entity_id: str
    provider: Literal["computershare", "vstock", "ast", "equiniti", "broadridge", "other"]
    provider_external_account_id: str
    engaged_at: str
    disengaged_at: NotRequired[Any]
    status: Literal["engaged", "disengaged", "transitioning"]
    last_reconciliation_audit_id: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created_at: str
    updated_at: str
    livemode: bool

class TransferAgentReconciliationAudit(TypedDict, total=False):
    """The result of a single reconciliation pass between the transfer"""
    id: str
    object: Literal["transfer_agent_reconciliation_audit"]
    transfer_agent_id: str
    entity_id: str
    audit_kind: Literal["routine", "pre_close", "post_close", "dispute"]
    as_of_date: str
    status: Literal["pending", "completed", "discrepancies_found", "failed"]
    discrepancies: List[Dict[str, Any]]
    resolution_completed_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created_at: str
    updated_at: str
    livemode: bool

class Valuation(TypedDict, total=False):
    """409A valuation event. Compliance tracks `expires_at`."""
    id: str
    object: Literal["valuation"]
    entity_id: str
    fair_market_value_per_share: "MonetaryAmount"
    provider: NotRequired[str]
    methodology: NotRequired[str]
    effective_date: str
    expires_at: str
    report_document_id: NotRequired[Any]
    is_safe_harbor_current: NotRequired[bool]
    material_event_triggered_at: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class VestingOverlay(TypedDict, total=False):
    """Retroactive vesting layer applied to previously-issued shares. Created"""
    id: str
    object: Literal["vesting_overlay"]
    entity_id: str
    ledger_entry_id: str
    grant_id: Any
    vesting_schedule: Dict[str, Any]
    authorizing_resolution_id: str
    tax_election_acknowledgement: NotRequired[Dict[str, Any]]
    effective_date: str
    document_id: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class WebhookEndpoint(TypedDict, total=False):
    """A subscription target for events. Pins an `api_version` at creation; payloads never"""
    id: str
    object: Literal["webhook_endpoint"]
    url: str
    description: NotRequired[str]
    enabled_events: List[str]
    api_version: str
    include: NotRequired[List[Literal["data.object"]]]
    portfolio_id: NotRequired[Any]
    signing_secret: NotRequired[str]
    status: Literal["enabled", "disabled"]
    last_delivery: NotRequired[Any]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool

class WindDownReserve(TypedDict, total=False):
    """DGCL §281(b)(iii) reserve. Cash set aside during a wind-down to cover"""
    object: Literal["wind_down_reserve"]
    id: str
    entity_id: str
    creditor_claim_id: str
    creditor_claims_window_id: NotRequired[str]
    kind: NotRequired[Literal["general_reserve", "creditor_settlement_buffer", "insolvency_security"]]
    court_petition_id: NotRequired[Any]
    held_amount_usd: float
    released_amount_usd: NotRequired[float]
    status: Literal["held", "partially_released", "closed"]
    authorizing_resolution_id: NotRequired[str]
    opened_at: NotRequired[int]
    closed_at: NotRequired[Any]
    created: int
    updated: int
    livemode: bool

class Workspace(TypedDict, total=False):
    """Pre-entity container — created BEFORE the entity exists. Holds the document vault,"""
    id: str
    object: Literal["workspace"]
    name: str
    status: Literal["provisioning", "ready", "active", "archived"]
    archived_at: NotRequired[Any]
    entity_ids: List[str]
    metadata: NotRequired["Metadata"]
    created: NotRequired[int]
    updated: NotRequired[int]
    livemode: bool