Get reports through the API

Use the Reporting API to get Aera reports into your own systems, such as your finance system, ERP or data warehouse, without downloading them from the Aera portal.

You don't need to check for new reports. When a report is ready, Aera sends a webhook (a request to a URL in your system). You then fetch the report data as CSV. Exact fields for each request are in the API Reference: Get report data and New report webhook.

How it works

---
config:
  theme: base
  themeVariables:
    primaryColor: "#FFFFFF"
    primaryBorderColor: "#CFD4DC"
    primaryTextColor: "#1D2939"
    secondaryColor: "#F2F4F7"
    tertiaryColor: "#F8F9FB"
    lineColor: "#98A2B3"
    clusterBkg: "#F7F6FE"
    clusterBorder: "#D6D0F7"
    titleColor: "#3E2F93"
    edgeLabelBackground: "#FFFFFF"
  flowchart:
    curve: basis
    padding: 14
    nodeSpacing: 36
    rankSpacing: 44
---
sequenceDiagram
  participant A as Aera
  participant Y as Your system
  A->>A: Report is ready
  A->>Y: Webhook with the report's file IDs
  Y->>Y: Check the API key and signature
  Y->>A: Get access token
  A-->>Y: Access token
  Y->>A: Get report data (file ID)
  A-->>Y: 200 OK with the report as CSV

1. Aera creates a report, for example the daily transaction report.
2. Aera sends a webhook to the URL you registered. It contains the report type and one file ID per batch, not the data itself.
3. Your system checks that the webhook comes from Aera.
4. Your system gets an access token, then fetches each file with Get report data.

Report types

The webhook's reportType tells you which report is ready. The CSV columns are the same as in the report described on each page.

The frequency field says how often the report is made: DAILY, MONTHLY or CUSTOM.

Before you start

1. Get access: ask Aera for Reporting API credentials.
2. Set up Authentication: every request needs your API key and an access token from Get access token for reporting.
3. Check that webhooks and responses come from Aera. See Signatures and security.

Use https://api-staging.aerahost.com for testing and https://api.aerahost.com in production.

Example

The daily transaction report for a merchant is ready. It is split into two batches, so the webhook lists two file IDs:

POST /your-webhook-url HTTP/1.1
Content-Type: application/json
Signature: <Aera's signature>
x-api-key: <the API key you got when you registered>

{
  "event": "NEW_REPORT",
  "timeStamp": "2026-03-11T17:45:30Z",
  "reportType": "TRANSACTION",
  "frequency": "DAILY",
  "merchantId": "PAM012345",
  "chainRef": "00",
  "report": [
    { "fileId": "01JP5Q8X4K7M2N9R3T6V8W0YZA", "batchNumber": 1 },
    { "fileId": "01JP5Q8X4K7M2N9R3T6V8W0YZB", "batchNumber": 2 }
  ]
}

Your system then fetches both files with Get report data. All fields are described in New report webhook.

Step 1: Create an endpoint

Create a URL in your system that:

• can be reached from the internet over HTTPS
• accepts a POST request with a JSON body

Step 2: Register your URL with Aera

Give Aera your webhook URL. In return, you get an API key (x-api-key). Aera sends it with each webhook, so you can check who the request comes from.

Step 3: Check every request

Before you trust a webhook, check both:

1. The API key matches the one Aera gave you for this webhook.
2. The signature in the Signature header is valid. Check it with Aera's public key for the environment. See Verify signatures.

Reject the request if either check fails.

Step 4: Get the report data

For each entry in report, call Get report data with its fileId.

Reports in batches

A large report is split into batches. Each batch is a separate file with its own fileId, and batchNumber tells you which batch it is. Fetch every file in the report list to get the whole report.

Respond to webhooks

We recommend that your endpoint:

• Answers quickly with 200 OK, and fetches the report data afterwards, not while Aera waits for your answer.
• Handles the same file ID twice without importing the data twice, for example by saving the file IDs you have already fetched.

Troubleshooting

Get report data returns 10000

10000 means no report has this file ID, or your API client has no access to it. Check that you use the credentials for the same environment (staging or production) as the webhook, and that your API client has access to the merchant or chain in the webhook.

The data is incomplete

The report may be split into batches. Check that you fetched every fileId in the webhook's report list.

Next steps