Finoview API documentation

A JSON REST API to connect your software with Finoview in both directions: read your companies' data and import companies into Finoview. API-key authentication, isolated per account. Base: https://api.finoview.com/api/v1.

Introduction

There are two ways to integrate; pick the one you need:

Quickstart

1. Generate an API key in Finoview (Profile → Developers / API). To import, tick "allow write".

2. Read your companies:

curl https://api.finoview.com/api/v1/companies \
  -H "Authorization: Bearer fv_live_…"

3. (Optional) Import a company:

curl -X POST https://api.finoview.com/api/v1/companies \
  -H "Authorization: Bearer fv_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name":"ACME SL","cif":"B12345678","source":"MI_SOFTWARE",
        "years":[{ "year":2025,"accounts":{ "700":1500000 } }] }'

Authentication

Send the API key with every request:

Authorization: Bearer fv_live_xxxxxxxxxxxx

The X-API-Key: fv_live_… header is also accepted. Each key has one permission:

Treat the key like a password. You can revoke it at any time; it stops working instantly.

Conventions

• Version in the path (/api/v1); breaking changes will go in /v2.
• JSON in request and response. Labels in ?lang=es (default) or ?lang=en.
• Per-account isolation: a key only sees/writes its owner's data.
• Source (source): each company carries its origin. When importing, you state your software; the internal INFONIF/EDGAR/BORME/HOLDED values are reserved.
• Idempotency: a company is identified by (account, CIF, source) and each year by its number. Re-sending updates, never duplicates.
• Limits: there is a request limit per key (429 when exceeded) and a maximum of 50 fiscal years per import.

Companies

GET https://api.finoview.com/api/v1/companies
Authorization: Bearer fv_live_…

{ "data": [
  { "id": "6a1c…", "companyName": "ACME SL", "cif": "B12345678",
    "source": "MI_SOFTWARE", "years": [2023, 2024, 2025] }
] }

A single company: GET /api/v1/companies/{id} (404 if it is not in your account).

Financial statements

Line items (items) and ratios (ratios) per fiscal year, with readable names.

GET https://api.finoview.com/api/v1/companies/<ID>/financials?year=2025&lang=es
Authorization: Bearer fv_live_…

• No year → all years. ?year=2025 → that fiscal year. ?year=latest → the most recent one.

{ "companyId": "6a1c…", "lang": "es", "data": [
  { "year": 2025, "source": "MI_SOFTWARE",
    "items":  [ { "key": "item01", "label": "Importe neto de la cifra de negocios", "value": 1500000 } ],
    "ratios": [ { "key": "r1", "label": "ROE (%)", "value": 18.4 } ] }
] }

Data catalog

To know which key to use for linking, list everything available grouped by statement (public, no key needed):

GET https://api.finoview.com/api/v1/catalog?lang=es

Returns sections (Information, Assets, Liabilities + Equity, Income Statement, Cash Flow, Ratios), each with its { key, label }. In your BI: link by key (stable) and display the label.

Importing data (write)

Requires a key with write permission (otherwise 403).

Create/retrieve a company (idempotent by CIF+source) and, optionally, load fiscal years:

POST https://api.finoview.com/api/v1/companies
Authorization: Bearer fv_live_…

{ "name":"ACME SL", "cif":"B12345678", "source":"MI_SOFTWARE",
  "years":[ { "year":2024, "accounts":{ "700":1500000, "430":250000 } } ] }

Load/update years of an existing company (idempotent per year):

POST https://api.finoview.com/api/v1/companies/<ID>/financials
{ "years":[ { "year":2025, "accounts":{ "700":1720000 } } ] }

Two ways to send each year (pick one):

Rules so it doesn't fail: don't pre-compute the sign; don't sum the parents; a single format per year; numeric values; your own source (not a reserved one). Unrecognised accounts are ignored and returned in unmappedAccounts.

Automatic normalisation and validation. We accept trial balances open or closed: if you send it open (without the profit-and-loss account and with groups 6-7), Finoview posts the year's result to Equity (account 129) and the Balance Sheet balances by itself. If you already send 129, it is left untouched. Each year in the response includes a validation report:

"validation": {
  "balanced": true,                 // the Balance Sheet balances (Assets = Liabilities + Equity)
  "imbalance": 0,                    // residual imbalance
  "result": 680750,                 // result for the year
  "resultImputedToEquity": 680750,  // posted to Equity; null if not needed
  "signWarning": "…"                // only if the result doesn't balance (sign / unmapped accounts)
}

Integrator guide (partners)

Who issues the key (bring-your-own-key): 1 API key ↔ 1 account ↔ 1 data silo. The key is always issued by the Finoview account that receives the data; your app is the consumer. You don't need to register your app: in your UI add a "paste your Finoview API key" field and the user generates it in their profile.

Account-native contract: one trial balance per fiscal year in accounts, with balance = Σdebit − Σcredit (natural sign). Finoview applies the sign, sums the parents and computes the ratios.

Critical rules: (1) balance = debit − credit; (2) one trial balance per year (not the journal, not a cumulative P&L); (3) genuine data, no round-trip (don't re-export companies that came from Finoview); (4) your own source.

Onboarding protocol: 1 real company with a CIF → POST → check with GET …/financials that it balances → scale up → build the button into your UI last.

Connecting from Power BI / Excel

The API returns JSON, so any BI tool can read it, no coding required.

1. Power BI: Get data → Web → Advanced. URL: https://api.finoview.com/api/v1/companies/<ID>/financials?year=latest.
2. Under "HTTP request header parameters" add Authorization = Bearer fv_live_….
3. Expand data → items / ratios (each row: key, label, value).

Excel: Data → Get Data → From Web → same URL and same header.

OpenAPI / Postman

The full contract is available as OpenAPI 3.0 (public, no key needed):

GET https://api.finoview.com/api/v1/openapi.json

Import it into Postman or paste it into editor.swagger.io to explore it and generate clients.

Errors

Ready to get started? Create your free account and generate your API key.