Use the Create a report endpoint to create a report. Each report type can be filtered by required and optional parameters to generate the exact data you need. The start_date and end_date parameters must be in UTC timezone, and the API supports a maximum reporting window of 90 days per request.
When the run completes with status of successful, the response to Retrieve a report will include a URL where you can download your results. Alternatively, you can also specify the report to be delivered via email or the pre-configured SFTP location.
Create a report
This endpoint allows you to create a report based on specified filters provided in the request body. You can choose one of the supported report types, and select how you'd like to receive the report—via URL, email, or SFTP. The report generation process is asynchronous, and you’ll receive a report ID to track the status.
For example, you can create a Mandates report for April 2024 for 2 of your business applications in CSV format, to be delivered via email:
POST /v2/reports
{
"start_date": "2024-04-01T00:00:00Z",
"end_date": "2024-04-30T23:59:59Z",
"mode": "live",
"scoped_resources": {
"type": "business_application",
"scope": [
"app_id_1",
"app_id_2"
]
},
"file_format": "csv",
"delivery_config": [
{
"email": "merchant@example.com",
"type": "email_delivery"
}
],
"report_specific_filters": {
"type": "mandate_report"
}
}
The response includes a report_id with status = "pending":
{
"start_date": "2024-04-01T00:00:00Z",
"end_date": "2024-04-30T23:59:59Z",
"mode": "live",
"file_format": "csv",
"report_specific_filters": {
"type": "mandate_report"
},
"delivery_config": [
{
"type": "email_delivery",
"email": "merchant@example.com"
},
],
"report_id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
"timestamp": "2024-10-24T21:24:58.059Z",
"scoped_resources": {
"type": "business_application",
"scope": [
"app_id_1",
"app_id_2"
]
},
"status": "pending"
}
Retrieve Report
Retrieve the current status of a report by its report_id. If the report is complete, it’ll return with status = “successful”. Depending on the delivery option you’d specified, you’ll either receive a download URL or confirmation of delivery via email or SFTP.
For example, if you were to retrieve the above report after it completes using GET /v2/reports/{report_id}, the response would look like this:
{
"start_date": "2024-04-01T00:00:00Z",
"end_date": "2024-04-30T23:59:59Z",
"mode": "live",
"file_format": "csv",
"report_specific_filters": {
"type": "mandate_report"
},
"delivery_config": [
{
"type": "email_delivery",
"email": "merchant@example.com"
},
],
"report_id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
"timestamp": "2024-10-24T22:46:14.235Z",
"url": "string",
"scoped_resources": {
"type": "business_application",
"scope": [
"app_id_1",
"app_id_2"
]
},
"status": "successful"
}
In rare occasion when a report request or processing encounters an error, it’ll return with status = failed and the corresponding error object:
{
"start_date": "2024-04-01T00:00:00Z",
"end_date": "2024-04-30T23:59:59Z",
"mode": "live",
"file_format": "csv",
"report_specific_filters": {
"type": "mandate_report"
},
"delivery_config": [
{
"type": "email_delivery",
"email": "merchant@example.com"
},
],
"report_id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
"timestamp": "2024-10-24T22:46:14.235Z",
"error": {
"code": "invalid",
"source": {
"parameter": "invalid"
},
"title": "invalid credentials or bad request"
},
"scoped_resources": {
"type": "business_application",
"scope": [
"app_id_1",
"app_id_2"
]
},
"status": "failed"
}
Download Report
If you’d opted for the requested report to be delivered via URL, you can download the report by the report_id:
GET /v2/reports/75d6d371-5cff-474a-b49b-aaf639446447/download
A successfully generated report shall remain available for retrieval for 30 days.