Financial API workflows

Follow complete request flows from ticker lookup to standardized values, reported tables, and filing evidence.

Use these workflows when you want an integration path rather than an endpoint inventory. Each request was exercised against the Rangler contract. The response excerpts use real Access Holdings records available during verification; later filings can change values and latest-period selection.

Choose a workflow

Goal	Start with	Keep for later requests
Load selected financial metrics	Ticker financials	`company.id`, `catalog_version`
Build a company history	Company-ID financials	company ID and your query parameters
Show the issuer's printed statement	Statement table index	`filing_id`, `table_id`, `value_id`
Explain a standardized value	Financials with source references	`filing_id`, `cell_id`, page
Refresh after new results	`financials.published` event	event ID and company ID

Company-first financials

Start with the ticker route. Restrict the response to the metrics and periods your product needs.

curl -sG "https://api.rangler.co/v1/financials/statements" \
  -H "X-API-Key: $RANGLER_API_KEY" \
  --data-urlencode "ticker=ACCESSCORP" \
  --data-urlencode "country_code=NG" \
  --data-urlencode "statement_type=income_statement,cash_flow" \
  --data-urlencode "metric=interest_income,net_interest_income,profit_after_tax,operating_cash_flow" \
  --data-urlencode "period_family=annual" \
  --data-urlencode "latest_only=true" \
  --data-urlencode "include_sources=true" \
  --data-urlencode "source_detail=reference" \
  --data-urlencode "include_metadata=false"

import os
import requests

response = requests.get(
    "https://api.rangler.co/v1/financials/statements",
    headers={"X-API-Key": os.environ["RANGLER_API_KEY"]},
    params={
        "ticker": "ACCESSCORP",
        "country_code": "NG",
        "statement_type": "income_statement,cash_flow",
        "metric": "interest_income,net_interest_income,profit_after_tax,operating_cash_flow",
        "period_family": "annual",
        "latest_only": "true",
        "include_sources": "true",
        "source_detail": "reference",
        "include_metadata": "false",
    },
    timeout=30,
)
response.raise_for_status()
financials = response.json()

const query = new URLSearchParams({
  ticker: 'ACCESSCORP',
  country_code: 'NG',
  statement_type: 'income_statement,cash_flow',
  metric: 'interest_income,net_interest_income,profit_after_tax,operating_cash_flow',
  period_family: 'annual',
  latest_only: 'true',
  include_sources: 'true',
  source_detail: 'reference',
  include_metadata: 'false',
});

const response = await fetch(`https://api.rangler.co/v1/financials/statements?${query}`, {
  headers: { 'X-API-Key': process.env.RANGLER_API_KEY },
});
if (!response.ok) throw new Error(`Rangler request failed: ${response.status}`);
const financials = await response.json();

The successful response resolved the ticker, returned one annual period, and preserved the distinction between directly reported and calculated line items:

{
  "company_id": "efa534f5-3b01-4f12-a33b-3c797b05beee",
  "company": {
    "id": "efa534f5-3b01-4f12-a33b-3c797b05beee",
    "name": "ACCESS HOLDINGS PLC",
    "ticker": "ACCESSCORP",
    "exchange": "NGX",
    "country_code": "NG"
  },
  "scope": "consolidated",
  "scope_label": "Group",
  "catalog_version": "sha256:3cc5f5800e5c13fe45a636979d7e5c3fd39e444d7e3d24adfa62c0275f607a95",
  "reported_currency": "NGN",
  "display_currency": "NGN",
  "periods": [
    {
      "period_id": "fy_2025-12-31",
      "period_end_date": "2025-12-31",
      "calendar_year": 2025,
      "calendar_quarter": 4,
      "fiscal_year": 2025,
      "fiscal_quarter": null,
      "reporting_period": "FY 2025",
      "period_type": "FY",
      "duration_months": 12,
      "is_derived_period": false,
      "is_restated": false,
      "restated_metrics": [],
      "income_basis": "12M",
      "reported_currency": "NGN",
      "display_currency": "NGN",
      "metrics": {
        "profit_after_tax": 743045000000.0,
        "net_interest_income": 1356891000000.0,
        "interest_income": 3546335000000.0,
        "operating_cash_flow": 886217000000.0
      },
      "metric_origins": {
        "interest_income": "derived_line_item",
        "net_interest_income": "reported",
        "operating_cash_flow": "reported",
        "profit_after_tax": "reported"
      },
      "sources": {
        "profit_after_tax": {
          "cell_id": "c6955b10-1531-51fd-ae30-bba80f90e2a7",
          "page": 86,
          "filing_id": "58a5c0c4-9955-4292-85ed-0da998dae339"
        },
        "interest_income": {
          "cell_id": null,
          "page": null,
          "filing_id": "58a5c0c4-9955-4292-85ed-0da998dae339",
          "derivation": {
            "operation": "linear_combination",
            "operands": [
              {
                "metric_key": "interest_income_effective_interest_rate",
                "value": 3273511000000.0,
                "coefficient": 1.0,
                "source": {
                  "cell_id": "c1b3d8ce-e170-57df-9a9c-d7bca5dc4548",
                  "page": 86,
                  "filing_id": "58a5c0c4-9955-4292-85ed-0da998dae339"
                }
              },
              {
                "metric_key": "interest_income_fvtpl",
                "value": 272824000000.0,
                "coefficient": 1.0,
                "source": {
                  "cell_id": "0be4e3c8-c47a-5401-b7b5-65e8dce7f3e0",
                  "page": 86,
                  "filing_id": "58a5c0c4-9955-4292-85ed-0da998dae339"
                }
              }
            ]
          }
        }
      }
    }
  ],
  "trailing_periods": []
}

The excerpt omits unchanged top-level unit conventions and the two other requested source references to keep it readable. It does not replace omitted values with fabricated placeholders.

The interest_income example has no single cell_id because Rangler calculated it from two filing-backed components. Follow the operand sources; do not display one operand as the source of the total.

Reuse the company and catalog IDs

Store company.id after the first ticker lookup. Subsequent reads can avoid ticker resolution:

GET /v1/companies/efa534f5-3b01-4f12-a33b-3c797b05beee/statement-financials

Cache the metric catalog under catalog_version:

curl -s "https://api.rangler.co/v1/financials/metric-catalog" \
  -H "X-API-Key: $RANGLER_API_KEY"

The verified catalog response contained six unit classes, 140 metric definitions, and 56 ratio definitions. Counts can grow; use the returned maps rather than hard-coding those counts.

Reported-table-to-source flow

First list filing-level statement options without loading every row:

curl -sG "https://api.rangler.co/v1/companies/efa534f5-3b01-4f12-a33b-3c797b05beee/statement-table-index" \
  -H "X-API-Key: $RANGLER_API_KEY" \
  --data-urlencode "statement_type=income_statement" \
  --data-urlencode "limit=2"

{
  "company_id": "efa534f5-3b01-4f12-a33b-3c797b05beee",
  "items": [
    {
      "filing_id": "20414188-1ffa-4940-8701-4c5260095bdd",
      "filing_title": "46924_ACCESS_HOLDINGS_PLC-_QUARTER_1_-_FINANCIAL_STATEMENT_FOR_2026_FINANCIAL_STATEMENTS_MAY_2026.pdf",
      "filing_published_at": "2026-05-01T01:16:16Z",
      "statement_type": "income_statement",
      "first_page_number": 4,
      "primary_period_end_date": "2026-03-31",
      "primary_period_basis": "3M",
      "source_label": "31 Mar 2026 financial statements",
      "context_label": "31 Mar 2026 · Group / Company · NGN millions · page 4",
      "is_latest_filing": true
    }
  ]
}

Then request the selected filing's table:

curl -sG "https://api.rangler.co/v1/companies/efa534f5-3b01-4f12-a33b-3c797b05beee/statement-tables" \
  -H "X-API-Key: $RANGLER_API_KEY" \
  --data-urlencode "filing_id=20414188-1ffa-4940-8701-4c5260095bdd" \
  --data-urlencode "statement_type=income_statement"

A returned cell keeps both the printed value and its standardized base-unit value:

{
  "value_id": "cf90e85d-5b67-5694-b4cb-4d3160e94656",
  "raw_text": "824,754",
  "raw_numeric_value": 824754.0,
  "scaled_numeric_value": 824754000000.0,
  "display_unit": "currency",
  "display_currency": "NGN",
  "statement_cell_id": "7bedde51-616c-518b-a5aa-e794f231f410",
  "source_region": {
    "row_index": 1,
    "page_number": 4,
    "column_index": 2,
    "source_artifact_id": "98496f91-7f04-4c91-a1a1-2b750cdc8b0f"
  }
}

Use value_id to retrieve the source crop:

curl -s "https://api.rangler.co/v1/companies/efa534f5-3b01-4f12-a33b-3c797b05beee/statement-table-values/cf90e85d-5b67-5694-b4cb-4d3160e94656/source?dpi=150" \
  -H "X-API-Key: $RANGLER_API_KEY" \
  --output source.png

The tested source endpoints returned 200 image/png. Geometry is a separate capability and can return 404 when Rangler can render the source row but cannot safely locate the exact value rectangle.

Refresh after published results

Subscribe to financials.published. On delivery:

Deduplicate the event by id.
Read its company_id.
Re-fetch the exact financial query your application stores.
Compare period IDs, restatement flags, and values before replacing local records.
Acknowledge the webhook quickly and process the refresh asynchronously.

Use GET /v1/events?type=financials.published to find updates if a webhook is missed.