# Finbar Docs > Finbar is an AI-powered investment research platform combining proprietary fundamental financial data, company reports and research tools. Analysts can research companies and build financial models in the web app or Excel add-in; developers and AI assistants can access Finbar data through the REST API and MCP. # Introduction Welcome to Finbar's documentation. Source: Finbar is an AI-powered platform for investment research. Finbar offers a high-quality proprietary fundamental dataset covering thousands of companies worldwide, as well as a suite of AI research tools used by several of the largest hedge funds in the world. - [Web app](https://docs.finbar.com/web/introduction.md): Access Finbar's suite of AI investment research tools and datasets. - [Excel add-in](https://docs.finbar.com/excel/introduction.md): Bring Finbar data and AI capabilities directly into your models and spreadsheets. - [API and MCP](https://docs.finbar.com/api-mcp/introduction.md): Use Finbar data in your own software or an AI assistant. - [Getting help](https://docs.finbar.com/overview/help.md): Reach out to us any time if you need further assistance. **Open Finbar** Click here to open Finbar's web platform and access the complete, AI-native investment research platform. Interactive content: [View on the website](https://docs.finbar.com/overview/introduction). --- # Your account Manage access, sign-in, plan details, and account support. Source: ## Registering To use Finbar, you need an account registered for you. This is typically handled by your Finbar representative or your organization administrator. After registration, you should receive sign-in instructions. If you are using a temporary password, sign in to [the app](https://app.finbar.com/) and complete the required password change before using the Excel add-in. ## Account details The account area in the web app lists your available account details, plan information, and usage information where enabled. > **Need changes?** > > Account details are usually managed by Finbar or your organization administrator. Contact your Finbar representative if you need access, plan, billing, or profile changes. ## Support If support tickets are enabled for your plan, use [Support](https://docs.finbar.com/web/support.md) in the web app or the support button in the Excel add-in to send issue details and diagnostics. --- # Getting help Reach out to us any time if you need further assistance. Source: > **Paid and enterprise customers** > > If you have a paid account, we suggest [filing a support ticket](https://docs.finbar.com/web/support.md) for a faster response. Enterprise clients can also reach out to their dedicated account manager. This documentation should take you through many of the core workflows of our platform. We're constantly upgrading our features, so please let us know if it appears our documentation doesn't align with your experience in the platform. If you require further assistance you're welcome to reach out to us via our [support page](https://finbar.com/help) at any time, regardless of your customer status. **Support & feedback** Reach out to us any time if you need further assistance. Interactive content: [View on the website](https://docs.finbar.com/overview/help). --- # Web app Use the Finbar web app as the main research workspace. Source: The Finbar web app is the main place to browse companies, open documents, extract data, run AI-assisted research, manage watchlists, and track support requests. - [Basics](https://docs.finbar.com/web/workspace.md): Learn how to navigate and customize the workspace. - [Analyze companies](https://docs.finbar.com/web/organizations.md): Get up to speed on thousands of companies worldwide. - [Fundamental data](https://docs.finbar.com/web/extract-data.md): Quickly extract and compare datapoints across millions of financial reports. - [AI-powered research](https://docs.finbar.com/web/chat.md): Use AI with fully-integrated data, spreadsheet, charting, and report-writing tools to accelerate your investment research. --- # Workspace basics Setting up and customising your workspace. Source: Finbar's web app is a single unified workspace, organised into panels. You can freely move and resize panels to best suit your needs. ## Customising layout Tabs are stored in panel groups. You can reorder tabs within a group, or move it to another group, by dragging the tab. Groups can be resized by hovering your mouse in the gap between groups and then dragging the handle that appears. ![Workspace split view with the resize handle visible between Home and Workbook panels.](https://docs.finbar.com/generated/screenshots/workspace-resize-handle.png) Hover between two panel groups to reveal the resize handle, then drag it to adjust the split. To create new panel locations, either click the triple-dot menu at the corner of an existing panel group, or simply drag a tab to the right or bottom of an existing panel. This will let you split up an existing panel view, giving you extra locations to locate tabs. ## Adding tabs Click on the '+' icon in any panel to add a new tab. Each tab represents a view onto some data or feature, like a company, document, chart, etc. --- # Spreadsheets Create and edit spreadsheets directly in Finbar. Source: Finbar includes an in-built custom spreadsheet engine, accessible in the "Worksheet" tab. Familiar spreadsheet tools like selection, styling, formulas, and charting are built-in, as well as several custom features designed specifically for financial research and AI-assisted workflows. ![Blank workbook tab showing the workspace tab header, spreadsheet toolbar, formula bar, and empty grid.](https://docs.finbar.com/generated/screenshots/spreadsheet-blank-workbook.png) ## Getting started You can use keyboard shortcuts or the toolbar to interact with the spreadsheet. By default, only one row of tools are shown in the toolbar - click the triple-dots on the toolbar to expand and see the full list. The platform supports import and export of `.xlsx` files. Be aware that, although extensive effort has been put into making this process compatible with external programs, the interface may not always exactly replicate data. The Finbar spreadsheet engine is custom-built to better support financial workflows. This includes - special data-tracing capabilities to open the original document source of any fundamental datapoint from Finbar's database; custom charting and financial modelling features (used in our pre-built models); and fully native AI integration (see more in the AI section). ## Finbar data formulas Use dedicated functions to fetch company names, entity IDs, prices, market cap, and expected reports. Start typing `=FINBAR.` or `=FB.` to see available functions; selecting one shows its signature, description, and the argument you are editing. Nested formulas also show a small indented outline with the current function marked. Long outlines use ellipses while keeping the current function visible. When editing an existing formula, arrow keys move through its text. When writing a formula in a blank cell, arrow keys can select cell references. Press **F2** while editing to toggle between these modes. A small tooltip footer shows the mode for existing formulas; for a new blank cell it appears only after you explicitly press F2. With reference mode enabled, place the caret anywhere inside a cell address and use the arrow keys to adjust that address in place. Absolute `$` markers, sheet names, and the rest of the formula are preserved. | Formula | Returns | | ----------------------------------------- | ------------------------------------------------------------------- | | `=FINBAR.NAME(A2)` | Stored Finbar company name for the matched identifier. | | `=FINBAR.ID(A2)` | Matched Finbar entity ID. | | `=FINBAR.PRICE(A2)` | Latest available daily close, adjusted when supplied by the source. | | `=FINBAR.PRICE_CLOSE(A2,DATE(2026,10,1))` | Close on an exact trading date. | | `=FINBAR.PRICE_OPEN(A2,$B$1)` | Opening price on the date in B1. | | `=FINBAR.MARKET_CAP(A2)` | Current market cap in the listed currency. | | `=FINBAR.NEXT_REPORT_PERIOD(A2)` | Expected reporting period, such as `2026Q3`. | | `=FINBAR.NEXT_REPORT_DATE(A2)` | Expected report date, usable in date arithmetic. | Every function also accepts the shorter `FB.` prefix, for example `=FB.PRICE(A2)`. Names are case-insensitive. `PRICE` and `PRICE_CLOSE` are equivalent. All three price functions accept an optional date; omit it for the latest available daily observation. Name, ID, market cap, and report functions accept only the company identifier. Use `=FINBAR.NAME(A2)` and `=FB.ID(A2)` to check which company an input resolves to: they use the same identifier lookup as the other functions. In these examples, A2 contains an unambiguous company identifier such as `AAPL US` or a Finbar organisation ID. Company names and fuzzy matching are not supported. Keep identifiers with leading zeroes as text. Dates may be spreadsheet dates, `DATE(...)`, or quoted `"YYYY-MM-DD"` text. A requested date must match an available trading date: weekends and missing observations return `#N/A`. Prices are daily observations, not intraday quotes, and no currency conversion is performed. Lookups are grouped into batches, so large sheets fill in as each batch completes. `#LOADING` means a lookup is pending, `#N/A` means data is unavailable, and `#VALUE!` means invalid arguments. Use the **Refresh Finbar data** icon beside **Open source** in the toolbar to refresh the workbook's lookups; there is no background polling. The former `FINBAR(metric, identifier)` syntax has been removed. Saved workbooks and XLSX exports preserve formula text and cached results. Neither namespace is registered as a native Excel custom function, so exported formulas cannot be expected to recalculate in Excel. --- # Writing notes Draft research reports, including charts and spreadsheet data. Source: Finbar's platform includes a dedicated report-writing editor - essentially, a specialised word processor that integrates with its spreadsheet, charting, and AI capabilities. ## Getting started You can access the text editor under the **Text** tab. The AI tab is also capable of editing or writing into this editor (see more in the relevant documentation). You can use keyboard shortcuts or the toolbar to interact with the editor. You can implement styling and document layout changes using this toolbar. The toolbar also lets you insert spreadsheet snippets and charts. Chart styling can be edited in-line but all data for charts and spreadsheet snippets must link to the open workbook. If you want to make changes to the data, do so in the Workbook tab. > **tip** > > If you're making complex edits to data that feeds into your report, you might find it convenient to open the Text and Worksheet editors in side-by-side panels. --- # AI-powered research Use Finbar as an AI researcher to power your research workflows. Source: One of Finbar's flagship AI interface designed specifically for financial research work. It interfaces directly with the platform's spreadsheet, charting, and report-writing suite, leveraging Finbar's proprietary fundamental and market datasets. ## Use cases The AI interface can be used for almost any financial research workflow. Some examples include: - Building financial models: will create a spreadsheet with every historical datapoint fully traceable back to the original document. - Benchmarking relative company performance: will pull together datapoints across different companies into one sheet, with options to further analyze or chart this data. - Writing research reports: can load necessary data, run calculations in the spreadsheet, then draft a research report include data and charts. ## Getting started The AI interface is loaded by default under the 'AI' tab in the workspace. Type any request or message into the chat to start interacting with the chat. It will have context of your workspace, including any selection you've made in the workbook, or document you're currently reading. ![AI Chat and Workbook tabs side by side, with the chat context showing the selected workbook range.](https://docs.finbar.com/generated/screenshots/chat-workbook-selection.png) The AI Chat tab tracks the active workbook selection, so prompts can refer to selected cells without restating the range manually. The AI has access to a highly-specialised set of tools, including: - Searching and extracting data across all the universe of documents and datapoints on the Finbar platform - Access to price and market data - Editing tools for the in-app spreadsheet and writing tools - Web search ## Advanced configuration Next to the chat input bar at the bottom, there are several extra options to configure the chat. **Resume chat**: this keeps a list of recent prior chats you've made. Click on any to restore that chat and resume from where you left off. Note that if changes were made to workbooks or reports via the previous chat that no longer exist, these won't be reapplied unless you specifically ask it to recreate it's edits. **Overwrite warnings**: this allows you to control how often Finbar should warn you before making changes to your spreadsheet. Click to switch between the options: - Warn on all: every spreadsheet edit requires manual approval - Warn on overwrite: every spreadsheet edit that would modify existing data requires manual approval - Auto-approve all: all edits are automatically executed If approval is required, a subwindow in the chat will show a visualisation of what the AI is proposing to change. ## Billing Finbar's AI tooling is subject to usage limits. Different tiers will have different limits per month, represented by credits. Credits can be used for any AI or other execution-heavy workflow. --- # Analyzing companies Finding and analyzing companies. Source: Most data in Finbar is associated with an organization (typically, a company). Finbar covers 1000s of companies globally. ## Finding an organization To find a company, you can use the company search bar. You can search by company name, ticker, ISIN, and other supported identifier types. The company search bar can be accessed from multiple places: - The 'Home' tab - The overall Finbar header - click the 'bar' and type. `Ctrl+K` also jumps to this search bar - Opening a new 'Company' tab in the workspace. ![Finbar header search showing Apple organization results.](https://docs.finbar.com/generated/screenshots/organization-search.png) You can search for companies directly from the 'finbar' header. > **tip** > > If you cannot find an organization, it may not have been onboarded yet. Contact your Finbar representative to request priority onboarding. ## Viewing an organization Once you've found the organization you're looking for, it will open in a new workspace tab. This display is the main hub for an overview of the company. Here, you can see: - A summary of what the organization is, their products, and history - An interactive and customisable price chart - Available documents as published by the company, organised by reporting period and document type. ![Finbar company panel showing summary text, price chart, and available documents.](https://docs.finbar.com/generated/screenshots/organization-company-panel.png) A company panel combines the company summary, price chart, and available filings in one workspace view. --- # Reports & filings Working with financial reports, presentations, filings, datapacks, and more. Source: Finbar maintains a highly-curated database of financial documents for thousands of companies across the globe. These are sourced from many locations, primarily individual company websites but also public exchanges and others. Every document is preprocessed to extract all fundamental datapoints. This forms the basis of many of our products, like our financial models, data streams, and client-directed commands like Excel model updates and AI-driven benchmarking requests. Every fundamental datapoint on the Finbar platform is always traceable back to its original document, which can be viewed on the web platform. ## Document types Finbar uses a unified classification system so documents are easier to compare across companies and markets. These include; - **Full financial report**: a complete financial report, such as an annual report, 10-K, 10-Q, or registration document. - **Press release**: a scheduled release associated with an earnings event. - **Presentation**: a scheduled presentation associated with an earnings event. - **Transcript**: a transcript associated with an earnings event. - **Partial financial report**: a document containing financial information when distinct from the full report and press releases. - **ESG report**: ESG disclosure when distinct from the full report and press releases. - **Additional data**: supplementary disclosure or data files. ## Viewing documents Open any document to view the original source. Finbar currently supports documents published as: PDFs, Excel files, and web filings. The document header gives quick options like switching to another period or filing, or exporting the underlying file. ## Document tools Opening a document also opens the 'Document tools' tab. This is a set of tools designed to help you quickly extract the information you need from a document. Clicking on any table in a document will enable the 'Inspect' sub-tab. This lets you copy and extract the data contained in that table in a cleaned format. Document tools also expose more advanced cross-document data tools. These are explained in a separate section of these docs. --- # Extracting data Extract tables, compare filings, and trace data back to source. Source: Finbar is designed to make financial data extraction efficient and traceable. When you select a table or datapoint, tools help you copy, compare across time, build time series, and return to the original source. ## Table data Click a table in a document to enable the 'Inspect' tool, which displays a cleaned mini-spreadsheet version of the table. You can copy individual cells, rows, columns, or the whole table into another workflow. The example below shows Apple's FY2025 full-year income statement from the company's annual report. ![Apple FY2025 consolidated income statement rendered in the table inspection view.](https://docs.finbar.com/generated/screenshots/table-viewer.png) The Inspect view renders the selected source table in a spreadsheet-style format. ## Finding similar tables across time Selecting a table also enables the 'Similar tables' and 'Time series' workflows. These tools help you quickly find equivalent data reported over multiple periods. For example, if you start from a company's income statement, Finbar can search nearby annual and quarterly reports for matching income statement tables before you build a time series. Click 'Similar tables' to first run a search for similar tables to the current selection, across a predefined period. ![Similar income statement tables for Apple annual and quarterly filings from FY2023 to FY2025.](https://docs.finbar.com/generated/screenshots/similar-tables.png) Similar table results group equivalent source tables by reporting period so they can be reviewed before extraction. ## Building fundamental time series Clicking 'Time series' after searching for similar tables allows you to transform this list of tables into a fully compiled time series, which accounts for subtleties like restatements and differing lengths of period. The initial screen will ask you to select which cells in the table you're interested in pulling equivalent data for. Drag to make a selection. What matters is which line items you're interested in. For example, if you're interested in seeing a company's cash position over time, you could select the 'Cash and cash equivalents' cell from the balance sheet. Once it compiles, you should see a time series of your selected line items. ![Generated Apple income statement time series showing quarterly and annual reported periods across columns.](https://docs.finbar.com/generated/screenshots/time-series.png) Time series views support original-versus-restated analysis. ## Tracing data All fundamental datapoints in Finbar are always traceable back to their original document source. Right-clicking on a cell in a table, time series, or other worksheet will show you the option to open the original source. This will open the original document in a new tab, jumping to the exact spot where that data was reported. ![Apple source filing displayed beside a generated income statement time series with the Show source context menu open.](https://docs.finbar.com/generated/screenshots/source-trace.png) Show source opens the filing beside the time series and highlights the underlying reported cell. --- # Watchlists Track groups of companies and reuse them across research workflows. Source: Watchlists are saved groups of organizations. Use them for coverage universes, peer sets, priority earnings names, or any research workflow where the same companies need to be revisited together. Each Finbar user has their own watchlist collection. Finbar automatically saves changes to your account as you edit. ![Watchlist panel showing a selected list of public companies.](https://docs.finbar.com/generated/screenshots/watchlists-populated.png) A selected watchlist shows its companies. Editing and workflow actions are available in the submenu. ## Create a list To see your watchlists, open the Watchlists tab from the web app workspace or sidebar. To create a new list, either click **Create new** if no lists currently exist, or open the list menu and choose **New list**. ## Managing watchlists Use **Add company** to search for a single organization and append it to the selected list. Like in regular company search, you can use tickers, names, or other identifiers. Use **Import list** when you already have a list of names or tickers. Paste one company per line, review the suggested matches, change or remove any undesired matches, and then import the selected organizations. Existing companies in the watchlist are skipped. Other watchlist management options are accessed from the Watchlists header. You can rename, edit, reorder or delete lists from this menu. ## Using watchlists Watchlists also act as shortcuts into other Finbar workflows. When a selected list contains companies, the header can open an earnings calendar scoped to those organizations. Where available, the list menu can open a live feed for document and filing events across the same companies. ## Use lists through the API or MCP The [REST API and MCP](https://docs.finbar.com/api-mcp/watchlists.md) use the same lists as the web app. Renaming a list keeps its ID, members, and email preference. You can also [subscribe to new documents](https://docs.finbar.com/api-mcp/webhooks.md) for its companies to start an unattended job. Set up subscriptions through the REST API. ## Email alerts Enable email alerts from a watchlist’s menu to receive emails when new documents finish processing for its companies. Finbar checks every five minutes and groups available documents into emails. Documents for the same reporting period may wait for related documents to finish processing. Email alerts and webhooks share the same age limits. They exclude reporting years before 2023 and documents at least two reporting years behind the latest available document for that company, across all document types. For example, if the latest year is 2026, documents from 2024 and earlier are excluded. The reporting period year takes precedence over the report date; documents without a usable year are excluded. Failed emails are retried for up to 24 hours. Disabling alerts or removing a company from the watchlist stops its queued notifications. An email may arrive more than once if delivery succeeds but Finbar cannot record the result. > **tip** > > Enable email alerts to get notified during earnings days when a new set of documents and data is available for a company in a watchlist. ![Watchlist options menu open with Email alerts enabled.](https://docs.finbar.com/generated/screenshots/watchlists-email-alerts-menu.png) Email alerts are enabled from the watchlist options menu. ![Example watchlist email notification showing newly processed documents grouped by watchlist and company.](https://docs.finbar.com/generated/screenshots/watchlist-email-notification.png) You will receive emails whenever a new batch of documents is published for a company and ready on Finbar. We aim to provide data within minutes of market publication. --- # Support tickets Create and track support requests from the web app. Source: Support tickets give you a central platform to make requests and report issues. > **Note** > > Dedicated support is only available on certain tiers and enterprise agreements. ## Creating tickets You can access the support center by opening the Support tab in the workspace or via the sidebar. You can file tickets for any issue, data request, or feature request. Please use the priority category responsibly. Attach screenshots or files that help reproduce the issue. For Excel add-in issues, the in-addin support button can include diagnostics to help Finbar investigate. Finbar support responses will be visible both in the Support center, and also emailed directly to the user. ## Feedback on any plan Anyone can [send feedback or report an issue](https://finbar.com/help), without signing in. Feedback is reviewed, but a reply is not guaranteed and it does not create a support ticket. --- # Excel add-in Use Finbar from inside Excel. Source: The Finbar Excel add-in brings Finbar's data, modelling and AI-powered research capabilities directly into Excel. > **warning** > > The Finbar Excel plugin is currently in selective early rollout. Reach out for more information. ## Installation Contact your IT department or Finbar representative to have the add-in deployed to your environment. There is currently no public self-serve version. ## Logging in Use the account controls in the taskpane to sign in. If this is your first time signing in, complete web app sign-in at [the app](https://app.finbar.com/) first. --- # Document basics Viewing documents and manually inserting data into your spreadsheet. Source: The 'Insert data' mode is the simplest mode in the Excel addin. Here, you can browse the millions of financial reports, presentations, and datapacks available on Finbar, viewing them directly in your Excel. ## Getting started After selecting an organization, choose 'Document data'. Select a period and document type to show available documents for that organization. These can be opened directly within your Excel. ## Extracting data Click inside the table to open a streamlined view of the data. From this mode you can easily copy any columns / cells into your workbook. ## Tracing data Several features in the Finbar Excel add-in can add fundamental datapoints directly into your spreadsheet (for example, when updating your models via 'Update Model' mode, or performing custom analysis via 'Copilot' mode). All datapoints on the Finbar platform always have direct traceability back to the original report. In the Excel platform, these are often baked into your worksheet by inserting comments into individual cells (note that on the web platform, our custom engine handles this differently to keep your sheets cleaner). The comments on inserted traceable values embed a url link to the exact original source of the data. The easiest way to use this link is to simply click the red/yellow 'target' icon in the upper right of the Excel add-in (which will open the source directly in your add-in), but it is also a valid url that can be inputted into your browser to open the web app. ![Excel add-in header with the source trace target button highlighted and its tooltip visible.](https://docs.finbar.com/generated/screenshots/excel-source-trace-header.png) The target icon enables automatic tracing of any cell in your workbook that includes a Finbar source comment. Moving between cells with your mouse/arrow keys will also automatically update the source display in the addin. --- # Building models Create a new financial model or fill an existing model in Excel. Source: The **Build Model** mode can create a financial model from scratch or fill an existing model in the current worksheet. It uses the company's reported data to build historical periods and forecasts, section by section. > **Note** > > Model building is in public beta, we welcome any feedback. For now, the builder focuses on populating historical values and formulas - forecasting and model drivers are coming soon. ## Start a model 1. **Choose a company.** Search by company name or ticker. 2. **Choose where to start.** Select **Start from scratch** for a new model, or **Use existing data in current sheet** to fill a template or partly completed model. 3. **Review the sections.** For a new model, choose the statements and breakdowns you need and arrange their order. You can add custom sections for any specific areas you want to model. For an existing model, check Finbar will automatically divide your model into sections. You can edit a section or add your own instructions. 4. **Choose the period range.** Set the first historical year and the final forecast year. The latest reported period is selected automatically. 5. **Confirm the plan.** Review your choices, decide whether Finbar may suggest missing rows, and add any final guidance. Then generate the template or start filling the existing model. ## Review and finish When starting from scratch, review the proposed rows before inserting the template. You can edit the rows, ask for changes, or choose where the template should be inserted. Finbar shows a preview before replacing any existing content. Once building begins, the progress screen shows each section separately. You can open a section to see more detail, add further guidance, or retry a section that needs attention. If Finbar asks to add a missing row, review the proposal and choose whether to add it. Completed values can be traced back to their original reports using the source button in the add-in header. See [Document basics](https://docs.finbar.com/excel/basics.md#tracing-data) for details. > **tip** > > Recent model runs appear on the first Build Model screen. Use them to return to work that is still running or needs attention. --- # Updating models Update any financial model for new data within minutes. Source: The 'Update model' mode is a specialized workflow for getting your models updating for newly reported data as quickly as possible. The aim is to have your model updated within 5-10 minutes of a company publishing its data. Model updates can be run in parallel across multiple models, enabling you to have all your models ready even on busy earnings days before market open. **Updating models in Excel** Watch how to update your financial models with Finbar. Interactive content: [View on the website](https://docs.finbar.com/excel/model-update). ## Updating models When you switch to 'Update Model' in the Excel add-in, a wizard will automatically appear. Following its steps will create a new update job. You can reaccess this wizard at any later point by clicking "Configure a new model update" at the top of the screen. 1. **Select the insertion period.** Choose the period you want to add or update in the model. Most commonly this is the latest reporting period, but you can also use this tool for backfills. For specialised use, you can also set the 'As reported' period to a specific period - this is for use iwth restatements where you want to capture e.g. 2025Q1 as reported in 2026Q1. 2. **Choose comparison columns.** This is the most important input for the model update. You should choose a few existing columns in your model that already contain historical data. Finbar will use the values in these rows as the primary basis for its search, taking care to try adapt reported figures to match your styling (e.g. multipliers, rounding, text formatting). 3. **\[Optional] Configure extra options.** The wizard will show extra options that can be used for specific model shapes and use cases. The defaults should work well for most models. 4. **Let Finbar process your model.** You should see your input filled into a unified table. A timer and progress summary will show at the top of the screen, and the table will gradually hydrate with proposed values to insert. Smaller models take 1-2 minutes, complex (>500 row) models typically take \~5 minutes. 5. **Review the output.** There are two ways you can review the output. Before insertion, you can right click on any proposed output in the table and click "View source" to open the value in the original document. Or, you can insert first and then use the 'Open selection source' icon in the add-in header (coloured red/yellow depending on your mode) to view the value's location in the original document. Both render the document and highlight the exact value location directly in the add-in. > **tip** > > We suggest \~4 periods of historical data as your input, although Finbar can work with as little as one. If you're interested in detecting restatements, select the equivalent period one year prior as well as the last full financial year-end period. ## Checking for new line items Finbar can check during model updates whether there are new line items being reported that appear to be missing in your model. Select the "Suggest missing rows" option before starting a model update to enable (note this may require additional usage credits). Proposed line items will appear as a banner on the search screen. Typical proposals are new rows in major reporting tables and breakdowns, as well as new divisional splits. ## Manual update flow For advanced usage, you can click the 'Auto' toggle to switch to manual mode. This allows you to spawn individual search jobs rather than automatically use your entire sheet. Follow the wizard instructions to use, similarly selecting 3-5 periods worth of historical data. Functionality for tracing values back to original source, both pre-insert and post-insert, is the same as in automatic mode. --- # AI Research in Excel Work with Finbar's AI research and data capabilities directly in your Excel. Source: The 'Copilot' tab in your Excel allows you to access Finbar's AI agent directly in your Excel add-in. This is similar to [the web version of the Finbar AI agent](https://docs.finbar.com/web/chat.md), bundling many of the same data and research capabilities, but also has the ability to directly read and edit your Excel workbook. > **tip** > > By default, the chat will ask for confirmation before overwriting any data. You can adjust this behaviour by clicking the button above the user input section. --- # Reset your add-in Clear the Excel add-in cache if Excel is running an old build. Source: If Excel warns that your add-in is out of date, it may be running a cached version. Excel should eventually refresh the add-in, but you can force a reset when needed. > **Note** > > These instructions apply to Excel on Windows desktop. ## Quick reset First try pressing `Ctrl+R` while the add-in taskpane is active. This may reload the latest add-in build. ## Advanced reset In the Start menu or Windows Explorer, navigate to `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\`. You should see a folder named `webview2`. Rename, move, or delete this folder. Excel will retrieve the latest version of the add-in the next time it loads. You may need to close all Office applications first. ![Windows Explorer showing the Office web add-in cache directory.](https://docs.finbar.com/images/reset_excel.png) The Office web add-in cache can be cleared from the Wef directory. > **warning** > > Clearing this cache may reset settings across multiple Office add-ins. You may need to sign in again. --- # API and MCP overview Read company reports and financial data from your software or AI assistant. Source: Finbar provides two ways to access its data outside the web and Excel apps: a REST API for scripts and applications, and an MCP server for AI assistants. Both use your Finbar account's data access and request allowances. ## Choose an interface | | REST API | MCP | | ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | | Used by | Your application or script | An AI assistant, such as ChatGPT or Claude | | How requests work | Your code sends HTTP requests and receives JSON | The assistant calls named Finbar tools and uses the results in its answer | | How you connect | Create a client ID and secret, then request an access token | Add the server URL to your assistant and sign in to Finbar | | Address | `https://api.finbar.com/v1` | `https://mcp.finbar.com/mcp` | | Start here | [API quickstart](https://docs.finbar.com/api-mcp/api.md) | [Connect an assistant](https://docs.finbar.com/api-mcp/mcp.md) | MCP stands for **Model Context Protocol**. It is the interface an assistant uses to discover available tools, send them arguments, and read their results. For example, an assistant can call Finbar's `search_entity` tool to resolve “Apple” to a company before looking up its reports. ## Available data | Data | What it contains | REST API | MCP | | -------------------- | ------------------------------------------------------------------------------------------------------- | ------------------ | ----------------- | | Companies | Names, identifiers, tickers and company information | Yes | Yes | | Company wiki | Saved overview, products, geography, segments and history, with inline citations where available | Yes | Yes | | Documents | Company reports and the paragraphs and tables within them | Yes | Yes | | Build/Update Dataset | Populate caller-supplied historical rows with researched values and source references, using AI credits | Yes | Yes | | Market data | Available price history and market information | No public endpoint | `get_market_data` | | Account usage | Request usage by day | `/usage` | No usage tool | A **document** is source material, such as an annual report. Build/Update Dataset research those documents to populate the rows and historical periods you supply. Their structured results include values, source references and unresolved items. They run asynchronously and consume your account's AI credits. The API and MCP expose company and document reads alongside these dataset runs. Published company dataset discovery and querying are not currently available. ## Account access Your account must have API/MCP access. Available data and request allowances depend on your plan and account permissions. Contact your Finbar representative if you cannot connect or create a credential. ## Find your way through the docs - **Data concepts** explains [reporting periods](https://docs.finbar.com/api-mcp/periods.md). [Build/Update Dataset](https://docs.finbar.com/api-mcp/build-update-datasets.md) describes row definitions, values and sources. - **MCP** covers [connection setup](https://docs.finbar.com/api-mcp/mcp.md) and [tools and research workflows](https://docs.finbar.com/api-mcp/mcp-tools.md). - **REST API** starts with a [first request](https://docs.finbar.com/api-mcp/api.md), then covers authentication, companies, documents, and dataset builds and updates. - [Usage and limits](https://docs.finbar.com/api-mcp/usage.md) explains the allowances shared by both interfaces. --- # Usage and limits Understand shared request allowances and read account usage through the API. Source: REST API and MCP requests share your account's allowances. Connecting another assistant or creating another credential does not add a separate allowance. A single assistant prompt may make several tool calls, each of which is a separate request. ## How limits work Company, document and market-data reads share the data-request limits. Your plan determines the allowed request rate and daily allowance. Daily allowances reset at midnight UTC. A request that passes the limit checks counts toward the allowance even if its later validation or execution fails. A request rejected because the limit has already been reached does not consume another request. | Interface | When a limit is reached | | --------- | -------------------------------------------------------------------------- | | REST API | HTTP `429`; wait for the number of seconds in the `Retry-After` header | | MCP | Tool error with code `rate_limit_exceeded`; wait for `retry_after_seconds` | The retry delay accounts for both short-term rate limits and daily limits. Follow the returned delay instead of immediately repeating the request. ## Watchlists and webhooks Watchlist requests, webhook inbox reads, and webhook management each have a separate account limit of 60 requests per minute, with a burst of 10. They do not use the document-read allowance. Reading a document after receiving an event uses the normal allowance. See [watchlists](https://docs.finbar.com/api-mcp/watchlists.md) and [webhooks](https://docs.finbar.com/api-mcp/webhooks.md) for setup and polling examples. ## Discover document read permissions `GET /v1/account/permissions` and MCP `get_account_permissions` return your effective document read allowances, including customer overrides. Both require `read`. These endpoints report allowances; they do not change permissions. An Enterprise account normally receives: ```json { "document_read": { "max_chunks_per_request": 100, "max_chars_per_chunk": 10000 } } ``` Free and personal plans retain 10 chunks per request. All plans normally cap each chunk at 10,000 Unicode characters, excluding the abbreviation notice. For a previously truncated item whose full text is specifically needed, a direct item read can set `disable_truncate` to true. ## Dataset build and update AI usage [Build Dataset and Update Dataset](https://docs.finbar.com/api-mcp/build-update-datasets.md) consume account AI credits for actual research usage, including work performed before failure or cancellation. Status polling and result retrieval do not incur AI charges. Each dataset run reports its own tokens, charges and billing status. ## Read usage through the REST API ```text GET /v1/usage ``` Use an [access token](https://docs.finbar.com/api-mcp/authentication.md) with `https://api.finbar.com/read` permission: ```bash curl --fail-with-body --silent --show-error --get \ 'https://api.finbar.com/v1/usage' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode 'start_date=2026-09-01' \ --data-urlencode 'end_date=2026-09-07' ``` Both dates are included. A request can cover up to 92 days. The response contains `totals` for the range and `daily` breakdowns, along with `as_of`, the time of the usage read. Recent requests may take a short time to appear. Token requests to `https://auth.finbar.com/oauth2/token` are not included in Finbar request usage, whether they succeed or fail. Authentication failures, scope rejections, unknown routes and requests rejected by rate limits also do not create API usage records. An admitted API operation that later returns a server error does count, including a failed webhook listing. When reconciling usage, compare the requested date range and the response's `as_of` timestamp. There is no equivalent MCP usage tool. Use the REST API when you need to retrieve usage programmatically. ## What the limits endpoint reports `GET /v1/limits` uses the same `read` permission. It reports account AI credits and research-run limits. It does **not** report the number of data requests remaining today. Use the retry delay when a data-request limit is reached. For other failures, see [REST errors](https://docs.finbar.com/api-mcp/errors.md) or [MCP tool errors](https://docs.finbar.com/api-mcp/mcp-tools.md#tool-errors). --- # Build and update datasets Set up your agent to collect and refresh company financial data with sources. Source: Ask your agent to use Finbar to fill in a list of financial metrics or update a dataset you already have. Finbar researches historical company reports and returns values with sources, flagging anything it cannot verify. ## Set up your agent 1. [Connect Finbar to your agent](https://docs.finbar.com/api-mcp/mcp.md) and sign in with an account that has API/MCP access. 2. Enable Finbar in your conversation and make sure your account has AI credits. 3. If your agent supports skills, download the optional [Finbar datasets skill](https://docs.finbar.com/plugins/finbar/1.1.0-preview.6/finbar-datasets.zip) and install it using your agent's skill settings. It guides the agent through preparing a request, waiting for results and saving the complete dataset. The skill is a separate, optional installation that uses your active Finbar connection. You can also use the dataset tools directly through the existing ChatGPT app or Claude connector. ## Build a dataset Give your agent the **company, a clear list of metrics and the periods** you want. You can paste the rows or supply an existing table to populate. Include units and reporting preferences where they matter, such as dollars in millions or GAAP rather than adjusted figures. For example: > Use Finbar's build\_dataset tool for Mastercard. Populate these rows: revenue, > operating income, net income and diluted EPS. Use full-year 2023, 2024 and 2025, > as originally reported under GAAP. Show dollar amounts in millions and EPS in > dollars per share. Include sources, flag missing or calculated values, and save > the complete dataset so I can update it later. For a complete financial statement, first agree on the rows to include. Your agent can propose a list for you to review before asking Finbar to populate it. ## Update a dataset Give your agent the saved dataset and specify which periods to add or refresh: > Use Finbar's update\_dataset tool to add Q1 2026 to this saved Mastercard > dataset. Keep the existing rows and units. Include sources and highlight any > values you could not update. Save the complete updated dataset. ## What to expect - **Allow several minutes.** Ask your agent to check progress and collect the final results. A full progress count can appear before final checks finish; wait for the run to end. Pending values are still being processed. Keep the run ID if you need to resume checking later. - **Runs use AI credits.** Research already performed can incur charges even if a run fails or is cancelled. Checking progress and retrieving results do not use AI credits. Billing updates separately from execution. - **Review gaps and warnings.** Missing values are not zero. If an update cannot verify a new value, it keeps the previous value and flags it. - **Save your results.** Finbar keeps results for seven days after a run ends. Keep a copy of the complete dataset for future updates. If a run fails, ask your agent to retrieve any completed results and explain the issue before retrying. Share the run ID and error message with [support](https://docs.finbar.com/web/support.md) if you need help. ## REST API Use an [access token](https://docs.finbar.com/api-mcp/authentication.md) as `ACCESS_TOKEN`. All paths below are relative to `https://api.finbar.com/v1`. Starting and cancelling runs requires both `read` and `write`; reading status and results requires `read`. | Operation | Method and path | | -------------------- | ------------------------------------- | | Build | `POST /datasets/build` | | Update | `POST /datasets/update` | | Status and usage | `GET /datasets/runs/{run_id}` | | Result page | `POST /datasets/runs/{run_id}/result` | | Complete JSON bundle | `GET /datasets/runs/{run_id}/bundle` | | Cancel | `POST /datasets/runs/{run_id}/cancel` | ### Submit a build or update Save a request as `dataset-request.json`, replacing the illustrative entity ID with an ID from [company search](https://docs.finbar.com/api-mcp/entities.md): ```json { "dataset": { "entity_id": "O-11111111111111111111111111111111", "rows": [ { "id": "revenue", "label": "Revenue", "basis": "GAAP", "scope": "Consolidated", "unit": "USD", "scale": 1000000 } ], "observations": [] }, "target_periods": [{"year": 2025, "period_type": "Y", "period": 0}], "value_version": "original" } ``` Each row needs a unique, stable `id` without a colon, a `label`, `unit` and positive `scale`. In this example, values are in millions of US dollars. Choose explicit historical [fiscal periods](https://docs.finbar.com/api-mcp/periods.md). `original` requests originally reported values; `latest_restated` requests revised values. Optional `instructions` can clarify definitions and reporting conventions. ```bash curl --fail-with-body --silent --show-error \ 'https://api.finbar.com/v1/datasets/build' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: revenue-2025-build-001' \ --data-binary @dataset-request.json ``` HTTP `202` returns `run_id` and `poll_after_seconds`; the `Location` header gives the status URL. Persist the run ID. Reuse the same `Idempotency-Key` and body after a timeout or temporary failure, so a retry does not start another paid run. Changed input needs a new key; conflicting reuse returns `409`. For an update, send the same request shape to `/datasets/update` with the saved dataset and new `target_periods`. Update requires at least one numeric existing observation. Preserve prior observations, their statuses and sources. For a number supplied by you, use an observation such as: ```json { "row_id": "revenue", "period": {"year": 2024, "period_type": "Y", "period": 0}, "value": 800, "status": "provided", "sources": [] } ``` Requests accept up to 200 rows, 40 unique target periods, 2,000 row/period combinations, 8,000 existing observations and 2 MiB of JSON. ### Poll, retrieve and save Set `RUN_ID` to the returned run ID and poll at `poll_after_seconds` intervals: ```bash curl --fail-with-body --silent --show-error \ "https://api.finbar.com/v1/datasets/runs/$RUN_ID" \ --header "Authorization: Bearer $ACCESS_TOKEN" ``` Wait for terminal `status`: `completed`, `failed` or `cancelled`. Progress and current activity describe work in flight; a full progress count alone does not mean the run is complete. Billing can still be pending after execution ends; inspect the returned billing status and usage separately. Retrieve the first result page with an empty body: ```bash curl --fail-with-body --silent --show-error \ "https://api.finbar.com/v1/datasets/runs/$RUN_ID/result" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{}' ``` Continue with `{"cursor":"RETURNED_NEXT_CURSOR"}` until `next_cursor` is absent. Optional `row_id`, exact `period` and `limit` filters must stay unchanged across pages. The default limit is 25; the maximum is 100. A 48 KiB response bound can produce shorter pages. Merge rows by `id` and observations by `row_id` plus `period`, preserving sources, calculations, changes and messages. Alternatively, download the complete result: ```bash curl --fail-with-body --silent --show-error \ "https://api.finbar.com/v1/datasets/runs/$RUN_ID/bundle" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --output dataset-result.json ``` Bundles have a 2 MiB limit. On `413 dataset_bundle_too_large`, use result pages. Save results before `expires_at`, seven days after termination. Expired result content returns `410`. Failed or cancelled runs can retain completed work; retrieve it before deciding whether to submit another paid request. ### Cancel a run ```bash curl --fail-with-body --silent --show-error --request POST \ "https://api.finbar.com/v1/datasets/runs/$RUN_ID/cancel" \ --header "Authorization: Bearer $ACCESS_TOKEN" ``` Cancellation is a request to stop. Continue polling until execution is terminal. Work already performed can incur AI charges. Status checks, result pages and bundle downloads do not incur AI charges; normal API request limits still apply. ## Previously published datasets The company-level `/entities/{entity_id}/dataset`, `/dataset/catalogue` and `/dataset/query` readers were withdrawn in October 2026 pending production readiness. There is currently no supported public read route for a company's already-published dataset. Build and Update are paid research operations using your supplied rows and periods, not replacement reads of those snapshots. Requests to the retired paths return `410 endpoint_retired`; retrying them will not restore access. --- # Reporting periods Distinguish fiscal years, quarters, year-to-date values and point-in-time balances. Source: Financial data is indexed by the company's **fiscal year**, the year it uses for financial reporting. A fiscal year may end in a month other than December. Document filters and dataset values use the same reporting-period conventions, with compact strings for filters and structured objects for dataset calls. > **How Finbar labels fiscal years** > > Finbar standardises reporting periods so the fiscal-year label refers to the calendar year in which the full fiscal year ends. We use this convention even when the company uses a different system, to improve comparability. > > For example, **1Q2026** means the first quarter of the fiscal year ending in 2026. For a company with a March year-end, this is **April–June 2025**. > > The only exception is a fiscal year ending in the **first half of January**, which Finbar treats as a December year-end. For example, a year ending on January 5, 2026 is labelled fiscal year 2025. ## Document periods Document filters use compact strings such as `2025Y` for fiscal year 2025 or `2025Q2` for its second quarter. `start_period` and `end_period` are inclusive: both boundary periods are included. These filters refer to the period a report covers. They do not filter by the date the company published the report. Document results include `period`, `report_date`, and `publish_date` as separate fields. ## Dataset periods Build/Update Dataset uses the shared structured reporting period for targets, existing observations, returned values, calculation references and result filters: ```json {"year": 2025, "period_type": "Q", "period": 2} ``` | Field | Meaning | | ------------- | ---------------------------------------------------------- | | `year` | Finbar fiscal-year label, between 1900 and 2500 | | `period_type` | Reporting-period type from the table below | | `period` | Period number within the fiscal year; 0 for annual periods | | Type | Valid numbers | Meaning | | ---- | ------------- | ------------------------------------------------------------------------ | | `Y` | 0 | Full fiscal year | | `H` | 1–2 | First or second half-year | | `Q` | 1–4 | Discrete fiscal quarter | | `QC` | 1–4 | Cumulative quarters from fiscal-year start; QC3 is the first nine months | | `M` | 1–12 | Month within the fiscal year | | `YT` | 0 | Transitional year when the fiscal year-end changes | | `QT` | 1–4 | Transitional quarter when the fiscal year-end changes | For a March year-end company, `{"year": 2026, "period_type": "Q", "period": 1}` means April–June 2025. Its full year is `{"year": 2026, "period_type": "Y", "period": 0}`. Monthly dataset coordinates are fiscal; monthly document labels follow the separate calendar-month convention used for document filtering. ## Balances, flows and cumulative values The same target period can populate both balance and flow rows. For Q2, revenue covers the second quarter and cash is the balance at that quarter-end. The row definition establishes which meaning applies; describe it explicitly where the label could be ambiguous. There is no separate zero-duration coordinate. Q2 and H1 end at the same point but remain distinct: Q2 revenue covers only the second quarter; H1 revenue covers the first half. The service preserves the exact supplied period type, including QC1/Q1 and QC2/H1, when matching observations and calculation references. Transitional periods require source evidence of the actual reporting interval; the service does not assume a standard duration. ## Choosing periods for Build/Update Dataset Supply 1–40 unique structured `target_periods`. Every target applies to every supplied row, with at most 2,000 row/period targets per request. Unsupported, null or invalid period/type combinations are rejected before paid work starts. There is no automatic latest-period selection. Returned observations identify their row and period and include evidence or an unresolved reason. Match observations by these identifiers when assembling result pages. See [Build/Update Dataset](https://docs.finbar.com/api-mcp/build-update-datasets.md) for the request, result and source formats. --- # Connect an assistant Add Finbar to ChatGPT, Claude or another MCP client. Source: Finbar's MCP server gives an AI assistant tools to find companies, read reports and populate supplied dataset rows using AI credits. You ask a question in the assistant; it calls Finbar and uses the returned data in its answer. ## Connection settings | Setting | Value | | ------------------- | ------------------------------------------------------ | | Server URL | `https://mcp.finbar.com/mcp` | | Authentication | OAuth: sign in with your Finbar account in the browser | | Account requirement | A Finbar account with API/MCP access | OAuth lets you authorize the connection on Finbar's sign-in pages. You do not need a REST API credential or client secret for this connection. ## ChatGPT 1. In ChatGPT, open **Settings → Security and login** and enable **Developer mode**. Availability depends on your account and workspace policy. 2. Open [ChatGPT Plugins](https://chatgpt.com/plugins), select the **plus** button and name the connection **Finbar**. 3. Choose a public server connection and enter `https://mcp.finbar.com/mcp`. 4. If authentication options are shown, choose **OAuth** and **CIMD**. Leave optional client ID and client secret fields empty. 5. Create the connection, complete Finbar sign-in and review the discovered tools. 6. Start a new conversation and add **Finbar** from the tools menu. **CIMD** means *Client ID Metadata Document*. It lets ChatGPT identify itself to Finbar using its published client information, so you do not need to register a client manually. See OpenAI's [MCP authentication guidance](https://developers.openai.com/api/docs/mcp#handle-authentication). These steps follow OpenAI's [connection instructions](https://developers.openai.com/plugins/deploy/connect-chatgpt). ## Claude 1. Open **Customize → Connectors** and choose **Add custom connector**. 2. Name it **Finbar** and enter `https://mcp.finbar.com/mcp` as the remote server URL. Leave optional OAuth client credentials empty. 3. Add the connector, choose **Connect**, and complete Finbar sign-in. 4. Enable Finbar for your conversation through the **+ → Connectors** menu. For Team and Enterprise workspaces, an owner must first add the connector in **Organization settings → Connectors**. See Claude's [custom connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for account-specific setup. ## Other MCP clients Other clients need support for remote MCP servers and browser-based OAuth. Compatibility depends on how the client registers itself with Finbar, as well as its ability to connect to the server. ### OpenCode Add this entry to `mcp` in `opencode.json`: ```json { "mcp": { "finbar": { "type": "remote", "url": "https://mcp.finbar.com/mcp", "oauth": { "scope": "read write" } } } } ``` The `scope` string requests permission to read companies and documents and to run Build/Update Dataset jobs using AI credits. Authenticate and inspect the connection: ```bash opencode mcp auth finbar opencode mcp list ``` Complete sign-in in the browser that opens. See [OpenCode's MCP documentation](https://opencode.ai/docs/mcp-servers/) for client configuration and troubleshooting. ## Approve and test the connection Finbar shows the requesting client's identity and permissions before sign-in. Check that they match the connection you started. **Remember this approval** saves the choice in the same browser for up to 30 days. A different account, changed permissions or cleared browser data can require approval again. After connecting, try: > Use Finbar to find Apple and list its recent financial reports. Include each report's period and document ID. The assistant should call Finbar and return reports from your account's available data. Continue with [MCP tools and workflows](https://docs.finbar.com/api-mcp/mcp-tools.md) for document research and dataset builds and updates. To collect or refresh company financial data, see [Build and update datasets](https://docs.finbar.com/api-mcp/build-update-datasets.md) for example prompts and an optional skill to guide your agent. ## Connection problems | Problem | What to check | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | The client requires a secret | Check that you selected OAuth account sign-in. In ChatGPT, use CIMD when offered. | | Finbar denies access | Sign in with an account that has API/MCP access. | | Approval expired or belongs to another browser | Restart the connection and finish approval and sign-in in the same browser. | | Connected, but Finbar is not used | Enable Finbar in the conversation and explicitly ask the assistant to use it. | | A previously working connection stops authenticating | Reconnect from the assistant's connection settings. | --- # Tools and workflows Understand which Finbar tools your assistant calls and how they work together. Source: Once you [connect Finbar](https://docs.finbar.com/api-mcp/mcp.md), describe the research task in your conversation. The assistant chooses tools, passes arguments and reads the results. You do not need to write HTTP requests or manage access tokens. A **tool** is a named operation, such as `list_documents`. Its **arguments** are the inputs it needs, such as the company's `entity_id`. The tool names below also help you understand the calls shown in your assistant's activity log. ## Company and document tools | Tool | Main arguments | Result | | ------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `get_account_permissions` | None | Effective document read allowances for your account | | `search_entity` | `q`: company name or ticker | Matching companies and their `entity_id` values | | `get_entity` | `entity_id` | Company information and identifiers | | `get_entity_wiki` | `entity_id`; optional `types` | Saved overview, products, geography, segments, and history sections | | `search_entity_wiki` | `query`; optional `types`, `limit`, `cursor` | Keyword discovery across saved company wikis, with section previews and ten-minute pagination | | `list_documents` | `entity_id`; optional document types and period bounds | Reports, their periods and `document_id` values | | `search_document` | `query` and exactly one of `entity_id` or `document_id` | Matching paragraphs and tables with item IDs and previews | | `read_document` | `item_id`, or `document_id` with `start_index` and `limit` | Paragraph or table content | | `get_market_data` | `entity_id`; optional `range` of `2y` or `max` | Available price history and market information | A company record is called an **entity**. A document **item** is a paragraph or table within a report. The assistant should use the IDs returned by earlier calls, rather than guess them from a company name or report title. ### Get a company overview Ask: "Use Finbar's company wiki to explain Apple's business and products." The assistant first calls `search_entity`, then `get_entity_wiki` with `types: ["OVERVIEW", "PRODUCTS"]`. Omitted or empty `types` returns all available sections. This tool requires `read` and reads saved descriptions; it does not generate or refresh them. It preserves inline citations. Reading the cited document content separately requires `read`. ### Research a disclosure > **Example prompt** > > Use Finbar to find Apple and its recent annual reports. Find the discussion of revenue growth, read the relevant passages, and summarize management's explanation with source references. The typical sequence is: 1. `search_entity` finds the company ID. 2. `list_documents` identifies the relevant reports. 3. `search_document` locates matching paragraphs or tables. 4. `read_document` reads the source content behind the search previews. A preview is a short excerpt. Reading the source gives the assistant more context for its answer. Ask it to retain document and item IDs so that you can trace claims back to their sources. ## Watchlists `manage_watchlists` is the single tool for listing, inspecting, creating, renaming and deleting personal watchlists and adding/removing companies. Its `action` argument selects the operation. Reads need `read`; mutations need `read` and `write`. See [watchlist arguments and concurrency](https://docs.finbar.com/api-mcp/watchlists.md). ## Dataset build and update tools `build_dataset` populates a supplied row list; `update_dataset` refreshes explicit historical periods using an existing model. Both start asynchronous work that consumes AI credits. Use `get_dataset_run`, `cancel_dataset_run` and `get_dataset_result` to manage the run and retrieve bounded JSON pages. See [dataset inputs, charges and recovery](https://docs.finbar.com/api-mcp/build-update-datasets.md) before starting work. ## Results that need more calls Tool results are bounded, so one call may not contain all matches or all of a report. If a result contains `next_cursor`, the assistant can repeat the call with that string as `cursor`, keeping the same target and selections. A **cursor** is a continuation value; it should be copied unchanged. Use `get_account_permissions` to discover your effective document read allowance. Free and personal plans allow 10 chunks per call; Enterprise allows 100, subject to account overrides. Responses also include `limits`. Each chunk normally has a 10,000-character cap, excluding the abbreviation notice. For subsequent document windows, use `cursor` instead of `start_index` and keep `limit`. If `is_truncated` is true, some returned content was shortened. A table can be read in a smaller range using `table_subslice`, for example `R0C0:R4C3` for rows 0–4 and columns 0–3. Set `disable_truncate: true` with `item_id` only when you specifically need the full text of a previously truncated item. It defaults to false and cannot be used with document windows. ## Tool errors A failed tool call returns an error with a `code`, `message` and `request_id`. The assistant should use the code to decide what to do next. | Code | Next step | | ---------------------------------------------------------- | -------------------------------------------------------------- | | `validation_failed` | Correct the tool arguments using the returned field issues | | `unauthenticated` | Reconnect to Finbar | | `insufficient_scope` | Check the connection's requested permissions | | `not_found` | Check the ID and whether the data is available to your account | | `rate_limit_exceeded` | Wait for `retry_after_seconds` before another call | | `service_unavailable`, `internal_error`, `gateway_timeout` | Retry the read after a delay | A prompt can trigger several calls, each using your account's shared [request allowance](https://docs.finbar.com/api-mcp/usage.md). For a persistent failure, send the request ID and tool name to [Finbar support](https://docs.finbar.com/web/support.md). Ask: "Find companies whose wiki describes semiconductor manufacturing equipment." The assistant calls `search_entity_wiki`, then `get_entity_wiki` for complete sections and citations. See [wiki search](https://docs.finbar.com/api-mcp/entities.md#search-company-wikis) for filters, ranking, and pagination limits. --- # API quickstart Authenticate and make your first company search request. Source: The REST API accepts HTTPS requests and returns JSON. Its base URL is: ```text https://api.finbar.com/v1 ``` This walkthrough uses `curl` from a terminal. You need a Finbar account with API access and a REST API credential from the web app's **API** panel. ## 1. Get an access token Follow [Authentication](https://docs.finbar.com/api-mcp/authentication.md) to create a credential and exchange its client ID and secret for an access token. Request `read` permission for this example. Set `ACCESS_TOKEN` in your terminal to the returned `access_token`. ## 2. Search for a company ```bash curl --fail-with-body --silent --show-error --get \ 'https://api.finbar.com/v1/entities' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode 'q=Apple' \ --data-urlencode 'limit=5' ``` `GET /entities` searches the companies available to your account. `q` is the search text; `limit` is the requested number of matches. The authorization header supplies your token. **GET /v1/entities — 200 response** Example response. IDs and values are illustrative. ```json { "entities": [ { "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d", "name": "Apple Inc.", "score": 0.98 } ], "next_cursor": "eyJ2IjoxLCJiaW5kaW5nIjoiLi4uIn0" } ``` ## 3. Select the company Check the `name` in the returned `entities` array and save the matching `entity_id`. “Entity” is the API's term for a company record. Its ID is used in subsequent requests; a company name or ticker cannot replace it. If `entities` is empty, no available company matched. Try a different name or ticker. If there are several matches, [read company details](https://docs.finbar.com/api-mcp/entities.md) to confirm the one you need. ## Make the next request | Task | Guide | Additional permission | | ------------------------------------ | -------------------------------------------------------------------------------- | --------------------- | | Read company information | [Companies](https://docs.finbar.com/api-mcp/entities.md) | None | | Read company wiki | [Companies](https://docs.finbar.com/api-mcp/entities.md#read-company-wiki) | None | | Find reports and read their content | [Documents](https://docs.finbar.com/api-mcp/documents.md) | `read` | | Check request usage | [Usage and limits](https://docs.finbar.com/api-mcp/usage.md) | `read` | | Create and maintain company lists | [Watchlists](https://docs.finbar.com/api-mcp/watchlists.md) | `read`, `write` | | Start jobs when new documents arrive | [Webhooks](https://docs.finbar.com/api-mcp/webhooks.md) | `read` and `write` | | Build or update historical rows | [Build/Update Dataset](https://docs.finbar.com/api-mcp/build-update-datasets.md) | `read`, `write` | For additional pages of results and failed requests, see [errors and pagination](https://docs.finbar.com/api-mcp/errors.md). --- # Authentication Create REST API credentials, request tokens and manage permissions. Source: REST API requests use an **access token**, a temporary credential sent with each request. Your application obtains it using a **client ID** and **client secret**, the credential pair you create in Finbar. This is the OAuth **client credentials** flow: the application authenticates using its own credentials without asking a person to sign in for each request. MCP assistants use a separate [browser sign-in flow](https://docs.finbar.com/api-mcp/mcp.md). ## Create a credential 1. Open the **API** panel in the [Finbar web app](https://app.finbar.com/). 2. Select **Create credential**, enter a name and choose **REST API**. 3. Choose **Read only** or **Read & write**. Read/write access also permits paid jobs. 4. Save the **Client ID** and **Client secret**. The secret is shown only when created or replaced. Keep the secret in your application's secret storage. Use it in server-side code or scripts, not browser applications or source control. ## Request an access token The following command assumes `CLIENT_ID` and `CLIENT_SECRET` contain your saved credentials. It requests permission to read companies and documents and to run paid Build/Update Dataset jobs: ```bash curl --fail-with-body --silent --show-error \ --config - \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=https://api.finbar.com/read https://api.finbar.com/write' \ https://auth.finbar.com/oauth2/token < A company record is called an **entity** in the API. Use company search to obtain an `entity_id`, then use that ID to retrieve its information, documents and wiki, or to build a dataset from supplied rows. These endpoints require `read` permission. Examples assume you have an [access token](https://docs.finbar.com/api-mcp/authentication.md) stored as `ACCESS_TOKEN`. ## Search companies ```text GET /v1/entities ``` | Query parameter | Required | Meaning | | --------------- | -------- | ------------------------------------------------------------- | | `q` | Yes | Company name, ticker, or full ISIN to search for | | `limit` | No | Requested page size; default 10, effective maximum 25 | | `cursor` | No | Continuation value from the previous response's `next_cursor` | ```bash curl --fail-with-body --silent --show-error --get \ 'https://api.finbar.com/v1/entities' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode 'q=AAPL' \ --data-urlencode 'limit=5' ``` ISIN searches require the full identifier and ignore letter case. For example, `q=US0378331005` and `q=us0378331005` find the same company when that ISIN is in Finbar. MCP's `search_entity` tool accepts the same queries through `q`. The `entities` array contains `entity_id`, `name` and `score` for each match. `score` measures search relevance; results are ordered with the most relevant first. Search only returns companies available to your account. A strong exact match may be returned on its own. If `next_cursor` is present, pass it as `cursor` with the same `q` to read the next page. An empty array means no available matches. ## Read company information ```text GET /v1/entities/{entity_id} ``` Set `ENTITY_ID` to an ID from search: ```bash curl --fail-with-body --silent --show-error \ "https://api.finbar.com/v1/entities/$ENTITY_ID" \ --header "Authorization: Bearer $ACCESS_TOKEN" ``` The response identifies the company and includes available tickers, security identifiers, investor-relations website and upcoming reporting information. An ISIN is an international identifier for a security; a ticker is its trading symbol. Optional information may be absent. **GET /v1/entities/{entity\_id} — 200 response** Example response. IDs and values are illustrative. ```json { "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d", "name": "Apple Inc.", "ticker": [ "AAPL US" ], "isin": [ "US0378331005" ], "ir_website_url": "https://investor.apple.com", "next_report_date": "2026-10-29T00:00:00Z", "next_report_period": { "year": 2026, "period_type": "Q", "period": 4 } } ``` Use the company's ID to [list its documents](https://docs.finbar.com/api-mcp/documents.md) or [build a dataset from supplied rows](https://docs.finbar.com/api-mcp/build-update-datasets.md). IDs for documents, paragraphs and tables cannot be used in place of an `entity_id`. ## Read company wiki ```text GET /v1/entities/{entity_id}/wiki ``` Retrieve the saved `OVERVIEW`, `PRODUCTS`, `GEOGRAPHY`, `SEGMENTS`, and `HISTORY` sections. Omit `types` to request all sections, or repeat it to select sections: ```bash curl --fail-with-body --silent --show-error --get \ "https://api.finbar.com/v1/entities/$ENTITY_ID/wiki" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode 'types=OVERVIEW' \ --data-urlencode 'types=PRODUCTS' ``` **GET /v1/entities/{entity\_id}/wiki — 200 response** Example response. IDs and values are illustrative. ```json { "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d", "sections": [ { "type": "OVERVIEW", "content": "Apple designs and sells consumer electronics and services [https://www.apple.com]." } ] } ``` The response contains the canonical `entity_id` and a `sections` array of `type` and `content` pairs, ordered overview, products, geography, segments, then history. Duplicate filters are ignored. Types are case-sensitive; use repeated query parameters, not comma-separated or JSON-encoded arrays. Available sections may be missing or contain empty text; a company with no wiki sections returns an empty array. Inline source citations are preserved. Use the document read endpoint with `read` to retrieve cited paragraph or table IDs; web citations remain URLs. Each wiki request uses the shared data-request quota and does not generate new content or incur an AI generation charge. ## Search company wikis ```text POST /v1/wiki-search ``` Find companies by keywords in their saved wiki sections: ```bash curl --fail-with-body --silent --show-error \ 'https://api.finbar.com/v1/wiki-search' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{"query":"semiconductor manufacturing equipment","types":["PRODUCTS","OVERVIEW"],"limit":10}' ``` Search uses English full-text matching, including quoted phrases, `OR`, and minus-prefixed exclusions. Search runs across company wikis. Omitted or empty `types` searches all five section types. Each item in `results` contains `entity_id`, `name`, a relevance `score`, and up to three matching `sections` with `type` and `preview`. Companies appear once, ranked by their best matching section. Previews show the first 500 characters of the saved section; read the full wiki for complete text and citations. `search_mode` is `keyword`. Pages default to 10 companies, with a maximum of 25. When `next_cursor` is present, send it as `cursor` with the same query and filters; `limit` may change. Results remain stable until `expires_at`, ten minutes after the initial search. A cursor is bound to your identity and filters. Invalid or expired cursors return `400`; restart without a cursor. Searches return at most 200 companies and are not exhaustive exports. Each page uses one data request under `read`. --- # Documents List company reports, search their content and read paragraphs or tables. Source: A **document** is a company report. Each document has a `document_id` and contains readable **items**: paragraphs and tables, each with its own ID. Search locates items within documents; reading an item returns its content. All endpoints on this page require `read`. First [find a company](https://docs.finbar.com/api-mcp/entities.md) and set `ENTITY_ID` to its `entity_id`. The examples use an [access token](https://docs.finbar.com/api-mcp/authentication.md) as `ACCESS_TOKEN`. ## List reports ```text GET /v1/entities/{entity_id}/documents ``` ```bash curl --fail-with-body --silent --show-error --get \ "https://api.finbar.com/v1/entities/$ENTITY_ID/documents" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode 'document_types=FULL_FINANCIAL_REPORT' \ --data-urlencode 'limit=5' ``` | Query parameter | Meaning | | ---------------------------- | -------------------------------------------------------------------------- | | `document_types` | Filter by document type; `FULL_FINANCIAL_REPORT` selects financial reports | | `start_period`, `end_period` | Inclusive reporting-period bounds, such as `2024Y` and `2025Y` | | `tags` | Filter by document tags | | `limit` | Reports per page, from 1 to 100; default 50 | | `cursor` | Continuation value from `next_cursor` | The `documents` array includes document IDs, types and reporting periods. Results are ordered by report date, most recent first. Period filters refer to the [period covered by a report](https://docs.finbar.com/api-mcp/periods.md#document-periods), not its publication date. `publish_date` is the publication timestamp, or `null` when unknown. `report_date` is also `null` when unavailable; a reporting `period` can still be known independently. As a temporary safeguard, a stored publication timestamp equal to the report timestamp is returned as `null`: older ingestion can use period-end as a placeholder for publication. This may also hide a genuine publication at that same timestamp. Do not infer a release date from a null value or use period-end as its replacement. **GET /v1/entities/{entity\_id}/documents — 200 response** Example response. IDs and values are illustrative. ```json { "documents": [ { "document_id": "D-d15ec8e059d94a2f8aa352025f57f7bb", "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d", "period": { "year": 2025, "period_type": "Y", "period": 0 }, "publish_date": "2025-10-31T00:00:00Z", "report_date": "2025-09-27T00:00:00Z", "status": "PARSED", "type": "FULL_FINANCIAL_REPORT", "tag": "20F" } ], "next_cursor": "eyJ2IjoxLCJxIjoiLi4uIn0" } ``` ## Search report content ```text POST /v1/document-search ``` Search all available reports for a company: ```bash curl --fail-with-body --silent --show-error \ 'https://api.finbar.com/v1/document-search' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --data "{\"entity_id\":\"$ENTITY_ID\",\"query\":\"revenue growth\",\"limit\":5}" ``` | Body field | Meaning | | ---------------------------- | ----------------------------------------------------------------------- | | `query` | Required search text | | `entity_id` or `document_id` | Required search target; supply exactly one | | `start_period`, `end_period` | Optional inclusive reporting-period bounds; only valid with `entity_id` | | `limit` | Matches per page, from 1 to 20; default 5 | | `cursor` | Continuation value from `next_cursor` | To search one report, replace `entity_id` with its `document_id`. The `results` array contains matching paragraphs and tables. Each has an `id`, `document_id` and `preview`. A preview is an excerpt; read the matching item before using it as evidence for an answer. ## Read a paragraph or table ```text GET /v1/document-items/{item_id} ``` Set `ITEM_ID` to a search result's `id` or a dataset source's `item_id`: ```bash curl --fail-with-body --silent --show-error \ "https://api.finbar.com/v1/document-items/$ITEM_ID" \ --header "Authorization: Bearer $ACCESS_TOKEN" ``` The response's `chunks` array contains rendered text or table content in each chunk's `content` field. A **chunk** is one bounded piece of content returned by a document read. `is_truncated: true` means content has been shortened. For a large table, the optional `table_subslice` query parameter selects a smaller range while retaining header context. For example, `R0C0:R4C3` selects rows 0–4 and columns 0–3; indices start at zero. Use a table ID for this parameter; if a paragraph links to a table, read its returned `table_id` directly. `raw_data=true` requests raw table values where available. ## Read through a report ```text GET /v1/documents/{document_id}/chunks ``` Set `DOCUMENT_ID` to an ID from the document list: ```bash curl --fail-with-body --silent --show-error --get \ "https://api.finbar.com/v1/documents/$DOCUMENT_ID/chunks" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode 'start_index=0' \ --data-urlencode 'limit=5' ``` `start_index` is the zero-based paragraph position at which to start reading. `limit` is required. Free and personal plans accept 1–10 chunks; Enterprise accepts 1–100, subject to account overrides. Discover your effective allowance with `GET /v1/account/permissions` or MCP `get_account_permissions`. Read responses also include `limits`. Each chunk normally contains at most 10,000 Unicode characters, plus an abbreviation notice. To read the full text of a previously truncated item when specifically needed, use `GET /v1/document-items/{item_id}?disable_truncate=true`, or MCP `read_document` with `item_id` and `disable_truncate: true`. Leave this option false or omitted for normal reads. It is unavailable for document windows. For tables, `table_subslice` can select a smaller region instead. To continue a document window, send `cursor` with the returned `next_cursor` in place of `start_index`, keeping `limit`. For lists and searches, also follow `next_cursor` until it is absent. Keep the same target and filters. See [pagination](https://docs.finbar.com/api-mcp/errors.md#pagination) for the common pattern. --- # Watchlists Manage the same personal company lists through the web app, REST and MCP. Source: Watchlists have stable IDs and revisions. The web app, public API and MCP read and update the same lists. Names are display labels, so renaming a list preserves its members, email preference and webhook subscriptions. Duplicate names are allowed; always address a list by its ID. Interactive users access their own lists. A personal machine credential accesses the owner of its billing account; actions remain attributed to the machine. Team machine credentials return `403 watchlist_access_denied`. For team [webhook subscriptions](https://docs.finbar.com/api-mcp/webhooks.md), use explicit entity IDs. ## REST Use `read` for reads. Request `read` and `write` to create or change lists. | Method and path | Input | | ---------------------------------------------------------- | ---------------------------------------------------------------- | | `GET /v1/watchlists` | Optional `cursor`, `limit` (1–100, default 50) | | `GET /v1/watchlists/{watchlist_id}` | Stable UUID | | `POST /v1/watchlists` | `name`, optional `entity_ids`; optional `Idempotency-Key` header | | `PATCH /v1/watchlists/{watchlist_id}` | `name` and current `revision` | | `DELETE /v1/watchlists/{watchlist_id}?revision=...` | Current revision | | `POST /v1/watchlists/{watchlist_id}/members` | `entity_ids` to add | | `DELETE /v1/watchlists/{watchlist_id}/members/{entity_id}` | Member to remove | ```bash curl --fail-with-body --silent --show-error \ 'https://api.finbar.com/v1/watchlists' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: earnings-list-v1' \ --data '{"name":"Earnings automation","entity_ids":["O-YOUR_ENTITY_ID"]}' ``` Creation returns the watchlist with `id`, `name`, `revision`, `entity_ids`, `created_at` and `updated_at`. Names must contain 1–200 characters. Each create or batch membership request accepts up to 1,000 company IDs. Repeated membership additions/removals are safe and preserve the membership state; resolve company IDs through entity search if needed. A stale update/delete revision or a collection change during pagination returns `409 resource_changed`. Fetch the current state before retrying so concurrent web edits and automation do not overwrite each other. Creation idempotency keys retain the original response for 24 hours; reusing a key with different input returns `409 idempotency_conflict`. Watchlist operations share an account limit of 60 requests per minute, burst 10, and do not consume document-read quota. ## MCP: one tool Use `manage_watchlists` with an `action`. Its schema selects the fields allowed for that action; irrelevant arguments are rejected. | Action | Arguments | Required scope | | ---------------- | ------------------------------------------------ | --------------- | | `list` | Optional `cursor`, `limit` | `read` | | `get` | `watchlist_id` | `read` | | `create` | `name`; optional `entity_ids`, `idempotency_key` | `read`, `write` | | `update` | `watchlist_id`, `revision`, `name` | `read`, `write` | | `delete` | `watchlist_id`, `revision` | `read`, `write` | | `add_members` | `watchlist_id`, `entity_ids` | `read`, `write` | | `remove_members` | `watchlist_id`, `entity_ids` | `read`, `write` | Example arguments: ```json {"action":"create","name":"Earnings automation","entity_ids":["O-YOUR_ENTITY_ID"],"idempotency_key":"earnings-list-v1"} ``` The tool returns `watchlist` for individual operations, `items` and an optional `next_cursor` for lists, or `deleted: true` for deletion. Webhook setup uses the REST API; it is independent of watchlist email notifications. --- # Webhooks Start unattended jobs from new documents, using callbacks or a durable event inbox. Source: Finbar creates a `document.published` event when a new eligible document is ready to read. Subscribe to a company, a set of companies, or a [personal watchlist](https://docs.finbar.com/api-mcp/watchlists.md). Use signed HTTP callbacks, poll the event inbox, or combine both. Polling works for an unattended machine without a public endpoint. Subscriptions belong to the billing account and require a paid plan with public API access. Authorized users and clients on that account can manage them. Each account supports up to 1,000 subscriptions. Delivery and inbox reads do not use your document-read quota; reading the document uses the normal allowance. ## Set up an unattended job 1. Create a personal REST API credential with **Read & write** access. See [authentication](https://docs.finbar.com/api-mcp/authentication.md). 2. Create or select a watchlist through REST or the MCP `manage_watchlists` tool. 3. Create a subscription and persist its ID. For a polling machine: ```bash curl --fail-with-body --silent --show-error \ 'https://api.finbar.com/v1/webhooks' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: earnings-watchlist-v1' \ --data '{"watchlist_id":"YOUR_WATCHLIST_UUID","delivery_mode":"poll"}' ``` 4. Poll `/v1/webhooks/{webhook_id}/events`, saving received events and the returned checkpoint atomically before starting work. See the polling contract below. 5. Read the document using its `document_id`, then run your job. Setup requires `read` and `write`. A running poller only needs `read`, including when it reads the published documents. Credentials must already grant requested scopes; rotating a credential does not add permissions. The repository includes a runnable Python receiver, poller and durable job worker in `finbar/manual/webhooks/example/`, including setup commands and restart tests. It groups initial work by company and reporting period and can optionally run follow-up jobs for later documents. ## Select documents and delivery Supply exactly one selector: | Field | Meaning | | -------------- | ------------------------------------------------------------------- | | `entity_id` | One company ID; compatible with existing subscriptions | | `entity_ids` | A fixed set of up to 1,000 company IDs | | `watchlist_id` | A live personal watchlist; new members apply to future publications | A watchlist subscription requires the billing account to belong to the watchlist owner. Personal machine clients use their owner's lists. Team machine clients can subscribe with explicit entity IDs instead. Optionally provide `document_types`, such as `["FULL_FINANCIAL_REPORT"]`. Omitted or empty filters include all document types. See [document types](https://docs.finbar.com/api-mcp/documents.md). Membership removal or a filter change cancels affected pending work. Removing and re-adding a company does not restore old events. Renaming a list preserves its subscription; deleting it permanently disables dependent subscriptions. | `delivery_mode` | Callback URL | Behavior | | ------------------- | ------------ | --------------------------------------------------- | | `webhook` (default) | Required | Signed HTTP delivery and retained inbox | | `poll` | Omit | Inbox only; no signing secret | | `both` | Required | Signed delivery with polling available for recovery | Callbacks must use public HTTPS on port 443. Private addresses, embedded URL credentials and fragments are rejected. Finbar does not follow redirects. For callback modes, creation returns a base64-encoded 32-byte `signing_secret`. Save it securely. Inspect and list endpoints never return secrets. Creation, secret rotation, test delivery and replay accept `Idempotency-Key`: reuse the same key and request on retries for up to 24 hours. Different input with the same key returns `409 idempotency_conflict`. Creation/rotation retries recover the original secret during that window. Keys are scoped to actor, account and operation; use a fresh key for a new operation. ## Publication semantics Each qualifying document produces a separate event. This does not define a single company-level earnings event. To start one initial job, deduplicate by company and reporting period in your own workflow; handle later documents as optional follow-ups. If period information is missing, use document ID. Documents already ready when you subscribe are excluded. Reprocessing and metadata corrections do not produce another event. Email alerts and webhooks exclude documents with a reporting year before 2023, or at least two years behind the latest available document for that entity. The comparison includes all document types and uses the reporting period year, falling back to the report date. Documents without a usable year are excluded. This same existing eligibility check applies to retries, replay and inbox reads. ```json { "id": "962410e0-738c-4479-b90b-85674cc3b350", "type": "document.published", "occurred_at": "2026-10-28T12:00:00Z", "subscription_id": "53948a28-5a7b-4396-84b1-3e4b87d36013", "document": { "document_id": "D-YOUR_DOCUMENT_ID", "entity_id": "O-YOUR_ENTITY_ID", "period": {"year": 2026, "period_type": "Q", "period": 3}, "publish_date": "2026-10-28T00:00:00Z", "report_date": "2026-09-30T00:00:00Z", "status": "PARSED", "type": "FULL_FINANCIAL_REPORT" } } ``` The event contains document metadata, not text or storage URLs. Use [document reads](https://docs.finbar.com/api-mcp/documents.md) for content. Synthetic events have `"test": true` and placeholder document IDs: verify and acknowledge them, but never start production work or try to read their document. New events use the document read contract's nullable dates, including the temporary safeguard for publication timestamps equal to report timestamps. `occurred_at` records when Finbar marked the document ready; it is separate from the issuer's publication date. Events already stored retain their original payloads, including date metadata. ## Poll and recover `GET /v1/webhooks/{webhook_id}/events` returns `items`, `next_cursor`, `has_more` and `retention_days: 30`. Each item has `sequence`, `created_at`, `event`, and an optional `cancelled_reason`. - Start without `cursor` to read the retained inbox. Use `limit` from 1–100 (default 50). - Store events, job intents and `next_cursor` in one durable transaction. Reuse that cursor on the next request, including after an empty page. - Continue immediately while `has_more` is true; otherwise wait before polling. - Skip items with `cancelled_reason` and events marked `test`, while still advancing the checkpoint. Use event ID to deduplicate callback/poll overlap. - A checkpoint older than retained history returns `410 event_retention_gap`. Stop, reconcile missed work against document reads, and explicitly establish a new checkpoint. Do not silently reset it. Cursors are bound to the account and subscription. The sequence follows durable inbox insertion order, so concurrent event creation cannot insert behind a saved checkpoint. It does not imply publication-time ordering. Events remain available for 30 days independently of HTTP delivery success or retry exhaustion. Poll requests share an account limit of 60 per minute, burst 10. Management uses a separate limit of 60 per minute, burst 10. Honor `Retry-After` on `429`, and retry temporary failures with backoff. Keep the last committed checkpoint. ## Verify callbacks Requests include `Webhook-Id` (event ID), `Webhook-Timestamp` (Unix seconds for this attempt), and `Webhook-Signature` (one or more space-separated `v1=` HMAC signatures). Base64-decode the signing secret. Sign the exact bytes of: ```text Webhook-Id + "." + Webhook-Timestamp + "." + raw_request_body ``` Use HMAC-SHA256 and compare hexadecimal digests in constant time. Accept a matching signature from any configured current/overlapping key. Reject timestamps more than five minutes from your clock and keep clocks synchronized. Verify the raw body before trusting any event fields. Each attempt gets a fresh timestamp. After verification, commit the event to durable storage and return `2xx` promptly. Run the job separately. Delivery is at least once; retries, replay and polling can all supply an event you have already processed. A durable event-ID uniqueness constraint prevents duplicate job admission. A stable downstream job key is also needed when a worker crashes after an external action but before recording success. Requests time out after 10 seconds. Network failures and non-`2xx` responses are retried for up to 24 hours, with increasing, jittered delays capped at one hour. Exhaustion marks that delivery failed; later events continue. Manual replay keeps the event ID and attempt history, and starts a fresh 24-hour retry window. It requires a retained, currently eligible event and an active, unpaused callback subscription. Replaying a pending delivery does not create a second delivery. ## Maintain and diagnose Reads require `read`. Request `read` and `write` to create or maintain subscriptions. | Method and path | Purpose | | --------------------------------------------------------- | ----------------------------------------------------------- | | `GET /v1/webhooks` | List account subscriptions | | `GET /v1/webhooks/{webhook_id}` | Inspect settings and health | | `PATCH /v1/webhooks/{webhook_id}` | Change `url`, `document_types`, `paused` or `alert_user_id` | | `DELETE /v1/webhooks/{webhook_id}` | Stop future and queued delivery | | `GET /v1/webhooks/{webhook_id}/deliveries` | Delivery status, cumulative attempts and last failure | | `GET /v1/webhooks/{webhook_id}/events` | Poll retained events | | `GET /v1/webhooks/{webhook_id}/events/{event_id}` | Inspect one retained event | | `POST /v1/webhooks/{webhook_id}/test` | Create a clearly marked synthetic event | | `POST /v1/webhooks/{webhook_id}/events/{event_id}/replay` | Requeue an eligible real event | | `POST /v1/webhooks/{webhook_id}/rotate-secret` | Return a replacement signing secret | Selectors and delivery mode are fixed at creation. Patch a callback URL without recreating the subscription. Pausing suspends HTTP attempts while inbox collection and polling continue; it does not extend an existing retry window. Rotation signs with both old and new keys for 24 hours. Install the returned key on your receiver, then retire the old one after `secret_overlap_until`. A second rotation is rejected during this overlap. Use an idempotency key to recover a lost rotation response. Health includes `last_event_at`, `last_polled_at`, `last_success_at`, `consecutive_failures`, `failure_started_at`, `retention_start`, and on inspect `next_attempt_at` when queued work exists. History excludes response bodies and secrets. Optional `alert_user_id` selects a registered member of the billing account for a sustained-failure email (at least three failures over 15 minutes) and a recovery email. An empty string removes the recipient. Arbitrary email addresses are not accepted. Revoking the creating credential does not delete a subscription. Account eligibility is checked before dispatch; an account interruption does not cause old publications to be delivered after restoration. A request already in flight may complete after a pause, deletion, membership change or loss of account access. --- # Errors and pagination Handle failed REST requests and retrieve results across multiple pages. Source: These conventions apply across the public REST API. Endpoint-specific parameters are documented in the company, document and dataset guides. ## Pagination List and search responses may split their results into **pages**. `limit` controls the requested page size. If there are more results, the response includes `next_cursor`. A **cursor** is a continuation value generated by Finbar. Treat it as opaque: copy the string exactly without decoding, editing or constructing it. 1. Make the first request without `cursor`. 2. Process the returned results. 3. If `next_cursor` is present, repeat the request with that value as `cursor`. 4. Stop when `next_cursor` is absent. Keep the same search target, filters and dataset selections. For `GET` requests, put `cursor` in the query string; for `POST` searches and dataset result pages, put it in the JSON body. When reading document chunks, replace `start_index` with `cursor` for subsequent pages. Do not assume a short page is the last page; check `next_cursor`. Webhook inbox polling keeps returning a cursor, including on empty pages. Continue immediately while `has_more` is true; otherwise wait before polling again with the saved cursor. See [polling and recovery](https://docs.finbar.com/api-mcp/webhooks.md#poll-and-recover). ## Error responses API errors contain an `error` object with these fields: | Field | Meaning | | ------------ | ------------------------------------------------------------------------------- | | `code` | Stable error identifier for application logic | | `message` | Human-readable explanation; its wording can change | | `request_id` | Identifies the request when contacting support; also returned as `X-Request-ID` | | `issues` | Field-level details on validation errors, when present | Use `code` to choose how to handle an error. Keep an HTTP-status fallback for codes your application does not recognize. | HTTP status | Meaning | Action | | ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | Invalid request | Correct the fields, IDs or filters before retrying | | `401` | Missing or invalid authentication | Obtain a new REST API token; check that it was issued for the REST API | | `403` | Insufficient permission or account access | Check the token's scopes and the account's API access | | `404` | Unknown route, or item missing or unavailable to your account | Check the method, path, ID and whether the data is available | | `409` | Conflicting state or idempotency key | For `resource_changed`, fetch current state before retrying. For `idempotency_conflict`, reuse the original input or use a new key for a new operation | | `410` | Retired endpoint or expired retained content | For `endpoint_retired`, see [published datasets](https://docs.finbar.com/api-mcp/build-update-datasets.md#previously-published-datasets). For `dataset_result_expired`, use your saved dataset to start a new run. For `event_retention_gap`, reconcile missed work before starting a new webhook checkpoint | | `429` | Request limit reached | Wait for the number of seconds in the `Retry-After` header | | `500`, `503`, `504` | Server failure, temporary unavailability or timeout | Retry data reads after a delay, increasing the delay if failures continue | Missing and inaccessible items both return `404`; this response does not tell you which case applies. Repeatedly retrying the same `400`, `403` or `404` request will not correct its cause. ## Request limits and support See [usage and limits](https://docs.finbar.com/api-mcp/usage.md) for shared allowances and usage reporting. For a persistent error, send the request ID, time and operation to [Finbar support](https://docs.finbar.com/web/support.md). Do not include access tokens or client secrets. MCP tools use a different error format, described in [MCP tools and workflows](https://docs.finbar.com/api-mcp/mcp-tools.md#tool-errors).