How do I generate reports via the API?

This article will guide you through using the reports API for generating reports.

In addition to the KOR Reporting UI, the KOR Trade Repository Reports can be generated by APIs directly. All API details are documented in an OpenAPI specification:

IMPORTANT: In order to generate a report, you must first have a report definition. The report definition contains the fixed report parameters. Report definitions can be used to trigger a report job with additional parameters and will in turn generate an actual report.

While report definition creation is supported through the API, we strongly recommend creating the report definition using the KOR Reporting UI as it is the most user-friendly way.

Create a report definition

KOR strongly recommends creating a report definition using the KOR Reporting UI. The created report definition can then be used in subsequent automated API calls.

In the KOR Reporting UI, click the "Reports"-tab on the left-hand side and open the report definition flyout by clicking the "New Report Definition"-button on the top-right.



Choose a report type and a name for the report definition. Fill out any report filters. And, if required, select a period.

Click the "Save New Definition"-button to save your new report definition.

Opening the details of the newly created report definition allows you to retrieve the ID of the report definition. The report definition ID will be utilized in the other report-related APIs.

Generate a report

Generate a new report via the API:

POST /clients/{entityId}/definitions/{definitionId}/jobs

Fill out the `entityId` placeholder with your KOR entity ID as found in your client details in KOR Central. Fill out the `definitionId` with the ID of an existing report definition (For the example above, this will be `74949901-81B6-9AFD-C8A234AC3D7A`).

The response of the API call will contain a job ID, which you can use to query the report's status.

Consult the status of the report via the API:

GET /definitions/{definitionId}/jobs/{jobId}?entityId={entityId}

In the response you will find the status and other details:

{
    "id": "D703C60D-041E-49FF-89DD-F2477CED1796",
    "entityId": "...",
    "subjectId": "...",
    "definition": {
      "definitionId": "8C388004-541A-4CED-9F90-41D576953150",
      "definitionName": "My report by date range",
      "typeId": "D3C3E84A-2774-11ED-A261-0242AC120002",
      "typeName": "messageReportByDateRange",
      "typeGroup": "KOR",
      "parameterDefinitions": [
        ...
      ]
    },
    "start": "2022-10-06T16:08:47.803675951Z",
    "end": "2022-10-06T16:08:52.310Z",
    "status": "SUCCESS"
}

Generate a report and overwrite parameters

In some cases, you will want to override some of the parameters already defined within the definition. For example, a report might require a `messageId` parameter you want to change only for the job you are launching.

Requesting the report using the API does not require you to provide a payload, but you might however wish to provide the parameters to overwrite:

POST /clients/{entityId}/definitions/{definitionId}/jobs
{
    "parameters": [
        {
            "name": "messageId",
            "fields": [
                "messageId"
            ],
            "operator": "EQUALS",
            "values": [
                "136CF29F-CC6E-4798-82E1-0246C1BA21DF"
            ]
        },
        { 
            "name": "messageSubmittedTimestamp", 
            "fields": [
                "messageSubmittedTimestamp"
            ], 
            "operator": "BETWEEN",
            "values": [ 
                "1663797600000", 
                "1663883999999"
            ]
        }
    ]
}

The definitions endpoint can give you a bit more information on which parameters, fields, and operators are available for a specific definition:

GET /definitions/{definitionId}

Timestamps are supplied as a string containing the milliseconds since epoch.

Render and download a report

Render the report via the following API call:

GET /definitions/{definitionId}/jobs/{jobId}/report?entityId={entityId}&format={format}

The report can be rendered in different formats:

• JSON
• CSV

In the response you will find a temporary link to download the report:

{
    "reportDownloadLink": "https://..."
}

Access the link from the previous step to download the report.

Scheduling jobs

For now, KOR supports ad-hoc generation of reports. Scheduling of reports through KOR is an upcoming feature but the KOR APIs can already be integrated within your own scheduling logic.