Help & User Guide

Everything you need to know about using XBRL2JSON — from your first upload to the REST API.

---

1. Overview

XBRL2JSON converts XBRL and Inline XBRL (iXBRL) financial filings into clean, structured JSON. It uses the Arelle open-source engine to parse filings and extract every reported fact — including its value, unit, reporting period, context reference, and dimensional qualifiers — into a flat, easy-to-consume format.

You can use XBRL2JSON through the web interface (upload, explore, download) or programmatically via the REST API and MCP server.

2. Getting Started

1. Create a free account — Register here. No credit card is required.
2. Upload a filing — go to the Upload page and select an XBRL or iXBRL file.
3. Wait for processing — the file is virus-scanned and parsed automatically. Most filings complete in under 30 seconds.
4. Explore the results — view extracted facts in the Fact Explorer, preview the raw JSON, or download it for use in your own tools.

3. Step-by-Step Walkthrough

a) Uploading a File

1. Navigate to Upload in the navigation bar.
2. Click the file input and select your XBRL or iXBRL document (see Supported File Formats below).
3. Click Upload & Parse.
4. The system will:
   • Validate the file type and size against your plan limits.
   • Quarantine the file and run an antivirus scan.
   • Enqueue a background parse job using the Arelle engine.
5. You are redirected to the Result page, which updates automatically as processing completes.

b) Viewing Your Parse Result

Once parsing completes, the Result page shows:

• File information — original file name, extension, size, and upload timestamp.
• Parse job details — status (Queued, Processing, Succeeded, Failed), duration, and parser engine version.
• Extracted data summary — total number of facts, distinct contexts, and distinct units found in the filing.
• Raw JSON preview — a truncated preview of the JSON output with a download button for the full file.

If the parse failed, an error banner displays the reason (e.g. invalid file format, Arelle engine error).

c) Using the Fact Explorer

Click Explore Facts on the Result page to open the Fact Explorer. This interactive table displays every extracted fact and lets you:

• Search — free-text search across concept names and values.
• Filter by concept — prefix-match on the XBRL concept name (e.g. ifrs-full:).
• Filter by unit — e.g. iso4217:GBP or pure.
• Filter by context — match on the original contextRef identifier.
• Filter by date range — restrict to facts whose period falls within a date window.
• Numeric only — toggle to show only numeric facts.
• Sort — click any column header (Concept, Value, Unit, Context) to sort ascending or descending.

Summary cards at the top show totals for facts, numeric facts, distinct units, and distinct contexts.

Exporting facts

Use the CSV or JSON export buttons above the table to download the currently filtered facts. Exports respect all active filters, so you can narrow down to exactly the data you need before downloading. CSV export requires the Starter plan or above.

d) Downloading JSON

You can download the full raw JSON output from the Result page by clicking Download JSON. This is the complete parser output — not a truncated preview. All plans include JSON download.

e) Managing Your Files

The My Files page lists every file you have uploaded. From here you can:

• View the upload status (Uploaded, Scanning, Clean, Infected, etc.).
• Navigate to the latest parse result for each file.
• Delete files you no longer need (this frees up your storage quota).

f) Viewing Your Conversions

The My Conversions page shows a history of all parse jobs. You can filter by status and search by file name. Each row links to the Result page and the Fact Explorer (for successful conversions).

4. Understanding the JSON Output

The JSON output produced by XBRL2JSON is a flat, fact-centric structure. This is an important design choice and differs from the raw XBRL specification.

Top-level structure

{
  "parser": {
    "engine": "Arelle",
    "generatedUtc": "2025-01-15T10:30:00Z"
  },
  "facts": [
    { ... },
    { ... }
  ]
}

Field	Description
parser.engine	The parsing engine used (currently always "Arelle").
parser.generatedUtc	ISO 8601 timestamp of when the parse was performed.
facts	Array of fact objects. Every non-nil fact in the filing appears here.

What this means in practice

• Facts — every non-nil fact from the filing is extracted. Nil facts (those flagged as xsi:nil="true") are excluded.
• Context data — rather than being extracted as standalone context objects, context information is denormalized onto each fact. Each fact includes its contextRef, periodStart/periodEnd (for duration periods), instantDate (for instant periods), and entityIdentifier. You do not need to join against a separate contexts collection.
• Units — the unit reference is resolved to its human-readable text (e.g. iso4217:GBP, pure, shares) and placed directly on each fact in the unit field. Units are not extracted as separate objects.

This flat design makes the JSON immediately usable — you can iterate the facts array and every piece of information you need is on the fact itself. It is particularly well suited for feeding into AI / LLM prompts, data pipelines, spreadsheets, and databases.

5. Fact Structure Reference

Each object in the facts array has the following fields:

{
  "name": "ifrs-full:Revenue",
  "valueText": "1234567",
  "valueDecimal": 1234567.0,
  "unit": "iso4217:GBP",
  "decimals": "-3",
  "contextRef": "ctx-2024-FY",
  "entityIdentifier": "0001234567",
  "periodStart": "2024-01-01",
  "periodEnd": "2024-12-31",
  "instantDate": null,
  "dimensionsJson": null
}

Field	Type	Description
name	string	Fully-qualified XBRL concept name including the namespace prefix (e.g. ifrs-full:Revenue, uk-bus:EntityCurrentLegalOrRegisteredName).
valueText	string?	The raw fact value as a string. null when the fact element carried no value.
valueDecimal	number?	The parsed numeric value when the fact is numeric. null for non-numeric (textual) facts.
unit	string?	Resolved unit of measure (e.g. iso4217:GBP, pure, shares). null for non-numeric facts that do not carry a unit. This is the resolved text, not a reference to a separate units collection.
decimals	string?	Precision indicator as reported in the filing (e.g. -3, INF, 2).
contextRef	string?	The original XBRL context reference identifier from the filing.
entityIdentifier	string?	The entity identifier from the context (e.g. a company registration number or CIK).
periodStart	string?	ISO 8601 date for the start of a duration period. null for instant contexts.
periodEnd	string?	ISO 8601 date for the end of a duration period. null for instant contexts.
instantDate	string?	ISO 8601 date for instant (point-in-time) periods. null for duration contexts.
dimensionsJson	string?	Serialized JSON carrying dimensional qualifiers (segment/scenario explicit and typed members). null when no dimensions are present. Reserved for future enhancement.

6. Supported File Formats

Extension	Format	Description
.xbrl	XBRL	Standard XBRL instance document (XML-based).
.xml	XBRL	XBRL instance documents that use the .xml extension.
.xhtml	Inline XBRL	iXBRL filings using the XHTML extension (common in ESEF, UK Companies House).
.zip	Archive	ZIP archives containing XBRL/iXBRL documents. The system will attempt to detect and extract the filing from within the archive.

7. Plans & Quotas

XBRL2JSON offers three plans. You can view your current usage on the Billing & Plans page.

8. Using the REST API

The REST API lets you automate XBRL conversions programmatically. API access requires the Starter or Pro plan.

1. Create an API key on the API Keys page.
2. Submit a job — send a POST to /api/v1/jobs with your file as multipart/form-data:

curl -X POST https://xbrl2json.co.uk/api/v1/jobs \
  -H "X-API-KEY: your_key" \
  -F "file=@filing.xbrl"

Optional form fields: idempotencyKey (prevent duplicate submissions), webhookUrl (receive a callback on completion).

3. Poll for status — GET /api/v1/jobs/{jobId} returns the current status (Queued, Processing, Succeeded, Failed).
4. Get the result — once the status is Succeeded, call GET /api/v1/jobs/{jobId}/result for the full parse result, or GET /api/v1/jobs/{jobId}/facts for paginated extracted facts.

For full endpoint details, parameters, and response schemas, see the API Documentation page or the interactive Swagger UI.

9. Using MCP (Model Context Protocol)

XBRL2JSON exposes a Model Context Protocol (MCP) server that lets AI agents and LLM-powered tools interact with the conversion engine directly. You can submit filings, check job status, and retrieve facts through MCP tools without writing HTTP integration code.

For connection details and available tools, see the API Documentation page (section: MCP).

10. Billing & Subscriptions

• Payments are processed securely via Stripe.
• You can upgrade, downgrade, or cancel your plan at any time from the Billing & Plans page.
• When you cancel, you retain access until the end of your current billing period.
• Downgrades take effect at the start of the next billing period.
• Your current quota usage (uploads remaining, storage used, API calls) is visible on the Dashboard.

11. Troubleshooting

Still stuck? Contact us and we'll be happy to help.