Reporter API quick start

Get Reporter running in minutes: upload your first template, generate a report, and download the finished output with cURL against the Reporter API.

This guide is intended for developers. If you’re looking for a business-level overview of what Reporter does, see What is Reporter?.

Get Reporter running in minutes. This guide walks you through the complete journey, from uploading your first template to downloading a generated report.

Before you begin

---

You need:

• A running Reporter instance
• A valid authentication token (if Access Manager is enabled)
• A .tpl template file ready to upload

All examples use cURL. Replace $TOKEN with your authentication token and https://reporter.example.com with your Reporter URL.

Step 1: Upload a template

---

Upload a .tpl file that defines the structure and content of your report. The template content must match the selected output format: HTML for HTML and PDF, XML for XML, CSV for CSV, and non-empty text for TXT. The uploaded file itself must have a .tpl extension.

API reference: Upload template

cURL

curl -X POST "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN" \
 -F "template=@account_summary.tpl" \
 -F "outputFormat=PDF" \
 -F "description=Daily account summary report"

{
  "id": "0196b270-a315-7137-9408-3f16af2685e1",
  "outputFormat": "pdf",
  "description": "Daily account summary report",
  "fileName": "0196b270-a315-7137-9408-3f16af2685e1.tpl",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}

Save the template id. You will use it to generate reports.

Supported output formats

Format	Use case
CSV	Data exports and spreadsheet integration
XML	Structured data and regulatory submissions
HTML	Browser-viewable reports
PDF	Print-ready and shareable documents
TXT	Plain text and legacy system integration

Step 2: Verify the template

---

List your templates to confirm the upload was successful.

API reference: List templates

cURL

curl -X GET "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN"

Step 3: Generate a report

---

Submit a report generation request with the template ID and the required filters object. Add filters to narrow the data, or send {} when no filtering is needed.

API reference: Create report

cURL

curl -X POST "https://reporter.example.com/v1/reports" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
   "filters": {
     "midaz_onboarding": {
       "account": {
         "created_at": {
           "between": ["2026-03-01", "2026-03-05"]
         }
       }
     }
   }
 }'

{
  "id": "0196c5c0-5044-724f-95f3-4b32076e7ad7",
  "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
  "templateOutputFormat": "pdf",
  "templateDescription": "Daily account summary report",
  "filters": {
    "midaz_onboarding": {
      "account": {
        "created_at": {
          "between": ["2026-03-01", "2026-03-05"]
        }
      }
    }
  },
  "status": "Processing",
  "metadata": null,
  "completedAt": null,
  "createdAt": "2026-03-05T10:05:00Z",
  "updatedAt": "2026-03-05T10:05:00Z",
  "deletedAt": null
}

Save the report id for the next steps.

Filter structure

Filters follow the path: data source > table > field > operator > values.

Operator	Description	Example
eq	Equal to	{ "eq": ["active"] }
gt / gte	Greater than / greater or equal	{ "gte": ["2026-01-01"] }
lt / lte	Less than / less or equal	{ "lt": [1000] }
between	Value within a range	{ "between": ["2026-03-01", "2026-03-31"] }
in / nin	Value in / not in a list	{ "in": ["active", "pending"] }

The filters field is required. To generate a report without filtering, pass an empty object: "filters": {}.

Step 4: Check report status

---

Report generation is asynchronous. Poll the status endpoint until the report is ready.

API reference: Check report status

cURL

curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7" \
 -H "Authorization: Bearer $TOKEN"

Status	Meaning
Processing	Reporter is querying data and rendering the template
Finished	The report is ready for download
Partial	Some data sections succeeded and others failed; the report’s metadata carries per-section error codes
Error	An error prevented the report from being generated.

Wait for Finished before proceeding to download.

Step 5: Download the report

---

Once the report is finished, download the generated file.

API reference: Download report

cURL

curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7/download" \
 -H "Authorization: Bearer $TOKEN" \
 -o account_summary.pdf

The file is returned with Content-Disposition headers indicating the filename and format.

Step 6: Explore data sources

---

To understand what data is available for your templates, list the configured data sources. Then use GET /v1/data-sources/{dataSourceId} to inspect the schema of one data source.

API reference: List data sources | Retrieve data source

cURL

curl -X GET "https://reporter.example.com/v1/data-sources" \
 -H "Authorization: Bearer $TOKEN"

The list response identifies each data source. The detail response includes its available tables and fields, which you can reference in your templates using the {{ datasource.table.field }} syntax.

Next steps

---

What is Reporter?

Full overview of template syntax, tags, and filters.

Template formats

Practical examples for HTML, XML, and TXT templates.

Using Reporter

Detailed guide on templates, storage, and data source configuration.

Error handling

Complete list of error codes and how to resolve them.