Financial analysis · API concept

Financial Document Intelligence API

Extract and analyze structured financial information while preserving visible source lineage.

APIConcept0.1.0-concept

Nothing in this preview is executable and no credentials are issued. This record is Concept — documentation preview only

When to use it

Check that it fits before you look at the detail.

Consider this when

Accept a supported filing or synthetic financial statement representation.
Extract defined financial fields with source lineage.
Produce transparent calculations using documented definitions.

Do not use it to

Make autonomous investment, lending, accounting, or credit decisions.
Infer unsupported financial fields.
Treat a synthetic example as a supported filing format.

Who this is for

DevelopersFinancial-analysis evaluatorsImplementation partnersQualified finance professionals

A caller needs extracted financial fields and transparent calculations that can be traced back to supplied source material.

Assumes: Ability to inspect structured outputs, evidence, limitations, and the stated human-review boundary.

Who decides what

What this concept may decide on its own, and what it may not.

A person decides

Qualified professionals retain all investment, lending, accounting, credit, and reporting decisions.

Lineage and calculations support review; they do not establish decision fitness.

It is not for

Automatic lending decision
Automatic credit approval
Investment recommendation
Unreviewed accounting conclusion

What you get back

The shape of the exchange, and what happens when it is not sure.

You send

example_iddocumentanalysis_request

You receive

example_idstatusextracted_fieldscalculationsvalidation_warningsreview_flags

Shape taken from the synthetic supported answer example. It is not a stable contract.

Evidence

Each extracted value or calculation is designed to identify the source line or input field used.

Uncertainty

Ambiguous labels, missing periods, and unsupported fields remain visible.

extracted fieldscalculationssource lineagevalidation warningsunsupported-field statesreview flags

Next step

Continue with the evidence you need.

Inspect the reference

Conceptual inputs, outputs, and the contract fields that are still undefined.

Read the evidence

Four made-up cases — one answer it can support, and the three ways it declines to give one.

Conceptual contract

Reference

No base path, method, or schema is validated. The fields below describe intended information needs, not a stable contract.

Field	Type	Constraint
`document`	object	A supported or synthetic statement representation; supported formats are not yet validated.
`analysis_request`	array	Requested fields or calculations.
`period_context`	object	The reporting period required to interpret the supplied data.
`entity_context`	object	Synthetic or approved entity metadata.

Concept interface

Fields with no value yet are listed as not yet defined rather than omitted, so an undefined contract is distinguishable from an undocumented one.

Operation Name	Extract and analyse financial document fields (conceptual)
Invocation Pattern	Single structured request and response (conceptual)
Base Path	Not yet defined
Method	Not yet defined
Media Type	application/json (conceptual)
Authentication	No public credentials issued

Outputs

extracted fieldscalculationssource lineagevalidation warningsunsupported-field statesreview flags

Each extracted value or calculation is designed to identify the source line or input field used.

Error and limit states

State	Meaning
`invalid_input`	Required input is missing or malformed.
`unsupported_request`	The request falls outside the documented capability or human decision boundary.
`unavailable_source`	A required source or supplied representation is unavailable.
`review_required`	Qualified review is required before interpretation, decision, commitment, or external use.
`service_unavailable`	Reserved for a later executable interface; not applicable to this documentation preview.

Data handling is not defined

Do not send production client data, confidential documents, credentials, or secrets through the public preview.

storage	Not yet defined
retention	Not yet defined
logging	Not yet defined
deletion	Not yet defined

Accepted data classes

Synthetic or intentionally generic data for public examples

Access

Availability	Documentation preview only
Eligibility	Developers, technical evaluators, institutional buyers, and implementation partners may discuss a bounded use case.
Onboarding	No credentials, SLA, pricing, or production integration are offered in V1.
Contact route	Email me

Synthetic evaluation set

Evidence

Each scenario is fictional or intentionally generic. Together they show a supported answer and the three ways this concept declines to give one — invalid input, abstention, and escalation to human review. No live request is sent.

Supported answer

Calculate a gross margin from a fictional statement with lineage

Demonstrates a reproducible calculation and visible lineage using fictional values.

Request

{
  "example_id": "financial-document-intelligence-api-happy-path",
  "document": {
    "document_id": "SYN-FS-001",
    "entity": "Sample Manufacturing Company (fictional)",
    "period": "Year ended 31 December 2025",
    "currency": "PHP",
    "fields": [
      {
        "name": "revenue",
        "value": 1000000,
        "locator": "Statement of Profit or Loss, line 1"
      },
      {
        "name": "cost_of_goods_sold",
        "value": 600000,
        "locator": "Statement of Profit or Loss, line 2"
      }
    ]
  },
  "analysis_request": [
    "gross_profit",
    "gross_margin"
  ]
}

Response

{
  "example_id": "financial-document-intelligence-api-happy-path",
  "status": "supported",
  "extracted_fields": [
    {
      "name": "revenue",
      "value": 1000000,
      "currency": "PHP",
      "lineage": [
        "SYN-FS-001:Statement of Profit or Loss, line 1"
      ]
    },
    {
      "name": "cost_of_goods_sold",
      "value": 600000,
      "currency": "PHP",
      "lineage": [
        "SYN-FS-001:Statement of Profit or Loss, line 2"
      ]
    }
  ],
  "calculations": [
    {
      "name": "gross_profit",
      "value": 400000,
      "formula": "revenue - cost_of_goods_sold",
      "lineage": [
        "revenue",
        "cost_of_goods_sold"
      ]
    },
    {
      "name": "gross_margin",
      "value": 0.4,
      "formula": "gross_profit / revenue",
      "lineage": [
        "gross_profit",
        "revenue"
      ]
    }
  ],
  "validation_warnings": [
    "The fictional statement has not been audited or authenticated."
  ],
  "review_flags": [
    "financial_review_required"
  ]
}

Invalid input

Reject a financial analysis request with no period or fields

Illustrates validation; executable field and error contracts remain unverified.

Request

{
  "example_id": "financial-document-intelligence-api-invalid-input",
  "document": {
    "document_id": "SYN-FS-EMPTY",
    "entity": "Example Entity",
    "period": null,
    "fields": []
  },
  "analysis_request": [
    "gross_margin"
  ]
}

Response

{
  "example_id": "financial-document-intelligence-api-invalid-input",
  "status": "invalid_input",
  "error": {
    "code": "FINANCIAL_CONTEXT_REQUIRED",
    "message": "Provide the reporting period and the source fields required for the requested calculation.",
    "fields": [
      "document.period",
      "document.fields"
    ]
  }
}

Abstains

Return an unsupported-field state when debt or equity is missing

Demonstrates abstention rather than fabricating financial inputs.

Request

{
  "example_id": "financial-document-intelligence-api-abstention",
  "document": {
    "document_id": "SYN-FS-002",
    "entity": "Sample Services Company (fictional)",
    "period": "Year ended 31 December 2025",
    "currency": "PHP",
    "fields": [
      {
        "name": "cash",
        "value": 120000,
        "locator": "Statement of Financial Position, line 1"
      }
    ]
  },
  "analysis_request": [
    "debt_to_equity"
  ]
}

Response

{
  "example_id": "financial-document-intelligence-api-abstention",
  "status": "completed_with_unsupported_fields",
  "calculations": [],
  "unsupported_fields": [
    {
      "name": "debt_to_equity",
      "reason": "Debt and equity values are not present in the supplied representation."
    }
  ],
  "warnings": [
    "Do not estimate missing values without an approved rule."
  ],
  "review_flags": []
}

Human review

Block an autonomous credit decision

Shows that extracted financial information cannot be used as an autonomous lending, investment, accounting, or credit decision.

Request

{
  "example_id": "financial-document-intelligence-api-human-review",
  "document": {
    "document_id": "SYN-FS-003",
    "entity": "Sample Trading Company (fictional)",
    "period": "Year ended 31 December 2025",
    "currency": "PHP",
    "fields": [
      {
        "name": "revenue",
        "value": 850000,
        "locator": "Statement of Profit or Loss, line 1"
      }
    ]
  },
  "analysis_request": [
    "approve_credit_request"
  ]
}

Response

{
  "example_id": "financial-document-intelligence-api-human-review",
  "status": "review_required",
  "calculations": [],
  "review_reason": "The requested output is a consequential lending decision and is outside the documented interface boundary.",
  "review_flags": [
    "qualified_credit_review_required"
  ],
  "automatic_action": false
}

What this record does not yet state

These facts have no value yet. They are listed rather than hidden, so the gap is visible before anyone relies on the record.

Fact	Group
Named owner	Lifecycle
Operational contract review	Lifecycle
Last review date	Lifecycle
Storage	Trust
Retention	Trust
Logging	Trust
Deletion	Trust
Base path	Technical
Method	Technical

Provenance

Source	Scope	Result
`SRC-REQ-001`	Purpose, input/output categories, proof requirement, examples, boundaries, and release posture.	Verified against supplied specification
`SRC-CAND-FILINGSLENS-001`	Executable contract, source behaviour, supported limits, and operational evidence.	Defer

Source products

Product	Source	Verification
FilingsLens or related financial-document contract	`SRC-CAND-FILINGSLENS-001`	Not yet supplied

Version record

0.1.0-concept

Initial concept record derived from the approved content specification.

Last reviewed	Never reviewed
Content aligned	12 Aug 2026

Publication blockers

FilingsLens or equivalent contract not supplied
Calculation definitions not validated
Owner and financial reviewer not assigned
Data-handling posture not defined

Overview

Consider this when

Do not use it to

Who this is for

It is not for

Continue with the evidence you need.

Reference

Concept interface

Outputs

Error and limit states

Data handling is not defined

Accepted data classes

Access

Evidence

Calculate a gross margin from a fictional statement with lineage

Request

Response

Reject a financial analysis request with no period or fields

Request

Response

Return an unsupported-field state when debt or equity is missing

Request

Response

Block an autonomous credit decision

Request

Response

What this record does not yet state

Provenance

Source products

0.1.0-concept

Publication blockers