Integrations with External Systems

This document describes the endpoint to submit facts to the system. It accepts data in JSON format and is intended for integration with external systems, scripts, or applications that need to send structured fact records.

Endpoint Overview

Property	Description
Endpoint URL	http://api.my-esg-manager/add-facts
Request Method	POST
Content Type	application/json
Authentication	API key sent in the JSON request body using the key field.

Request Structure

The request body must be sent as a JSON object. The object contains an API key and an array of fact records.

Field	Type	Description
key	String	The API key used to authorize the request.
facts	Array	An array containing one or more fact objects.

Fact Object Structure

Each item in the facts array represents one fact record.

Field	Type	Example	Description
company_plant_code	String	CPL-000003	Code identifying the company plant.
location_code	String	AT	Code identifying the location, such as a country or site code.
date	String, date format YYYY-MM-DD	2025-12-31	The reporting date for the submitted fact.
datapoint_code	String	E1-4_X1	Code identifying the related datapoint.
kpi_code	String	EM-xxxx1__E1-4_X1__1-1-1	Code identifying the KPI to which the value belongs.
qty	Number	10	Quantity value related to the fact.
unit_code	String	cal	Code identifying the measurement unit.
currency_code	String	EUR	Currency code used for monetary values.
amount_currency	Number	20	Monetary amount related to the fact.
amount_percent	Number	30	Percentage amount related to the fact.
amount_text	String	AMT text	Text value related to the fact.
notes	String	NOTES	Additional notes or comments related to the fact.

Example JSON Request

{ "key": "MY_API_KEY", "facts": [ { "company_plant_code": "CPL-000003", "location_code": "AT", "date": "2025-12-31", "datapoint_code": "E1-4_X1", "kpi_code": "EM-xxxx1__E1-4_X1__1-1-1", "qty": 10, "unit_code": "cal", "currency_code": "EUR", "amount_currency": 20, "amount_percent": 30, "amount_text": "AMT text asdfasd", "notes": "NOTES asdfasd" }, { "company_plant_code": "CPL-000003", "location_code": "AT", "date": "2025-12-31", "datapoint_code": "E1-4_X1", "kpi_code": "EN-xxxx1__E1-4_X1__2-1-1", "qty": 100, "unit_code": "cal", "currency_code": "EUR", "amount_currency": 200, "amount_percent": 300, "amount_text": "AMT text asdfasd", "notes": "NOTES asdfasd" } ] }

Example PHP Request

<?php $data = [ 'key' => 'MY_API_KEY', 'facts' => [ [ 'company_plant_code' => 'CPL-000003', 'location_code' => 'AT', 'date' => '2025-12-31', 'datapoint_code' => 'E1-4_X1', 'kpi_code' => 'EM-xxxx1__E1-4_X1__1-1-1', 'qty' => 10, 'unit_code' => 'cal', 'currency_code' => 'EUR', 'amount_currency' => 20, 'amount_percent' => 30, 'amount_text' => 'AMT text asdfasd', 'notes' => 'NOTES asdfasd' ], [ 'company_plant_code' => 'CPL-000003', 'location_code' => 'AT', 'date' => '2025-12-31', 'datapoint_code' => 'E1-4_X1', 'kpi_code' => 'EN-xxxx1__E1-4_X1__2-1-1', 'qty' => 100, 'unit_code' => 'cal', 'currency_code' => 'EUR', 'amount_currency' => 200, 'amount_percent' => 300, 'amount_text' => 'AMT text asdfasd', 'notes' => 'NOTES asdfasd' ] ], ]; $postdata = json_encode($data); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "http://api.my-esg-manager/add-facts"); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_USERAGENT, "Mozilla/5.0"); curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]); $result = curl_exec($ch); curl_close($ch); echo $result;

Example cURL Request

curl -X POST "http://api.my-esg-manager/add-facts" \ -H "Content-Type: application/json" \ -d '{ "key": "MY_API_KEY", "facts": [ { "company_plant_code": "CPL-000003", "location_code": "AT", "date": "2025-12-31", "datapoint_code": "E1-4_X1", "kpi_code": "EM-xxxx1__E1-4_X1__1-1-1", "qty": 10, "unit_code": "cal", "currency_code": "EUR", "amount_currency": 20, "amount_percent": 30, "amount_text": "AMT text asdfasd", "notes": "NOTES asdfasd" } ] }'

Response

The API returns a response after processing the submitted facts. The exact response may depend on the server configuration and validation rules. In a typical implementation, the response should indicate whether the request was processed successfully or whether validation or authorization errors occurred.

Example Success Response

{ "success": true, "message": "Facts added successfully." }

Example Error Response

{ "success": false, "message": "Invalid API key or invalid request data." }

Notes

The request must be sent using the POST method and must include the Content-Type: application/json header. The API key should be replaced with a valid key issued for the system.

The example endpoint URL uses a local development host. For production use, replace http://api.my-esg-manager/add-facts with the production API URL.