Inbound APIs

Importing Data for Measures and Metrics

There are two ways for importing, validating, and persisting data for measures and basic custom metrics:

Method	Import	Validate	Persist
Manual Flow	API request	Manage Quantitative ESG Data app	Manage Quantitative ESG Data app
API Flow: For measures For basic custom metrics	API request To import more than 10,000 records in one call, you can group multiple API requests. See Grouping Multiple API Requests for details.	API request	API request

Method

Import

Validate

Persist

Manual Flow

API request

Manage Quantitative ESG Data app

API Flow:

For measures
For basic custom metrics

API request

To import more than 10,000 records in one call, you can group multiple API requests. See Grouping Multiple API Requests for details.

API request

Manual Flow for Measures

First, use the APIs to push data into the measures. See Push Measure Data into SAP Sustainability Control Tower.
Once you have pushed the data, navigate to the Manage Quantitative ESG Data app. Here, you will find the pushed data under the relevant measure for which you have pushed the data.
View the replicated data, validate, and publish it for using it across SAP Sustainability Control Tower.

For more details on validating and publishing data, see Using the Manage ESG Data Application.

API Flow for Measures and Metrics

The API workflow is almost identical for measures and basic custom metrics, so you can follow the below steps for each of them. Any difference between them is explicitly mentioned.

First, use the APIs to push data into SAP Sustainability Control Tower.
- To push data into a measure, use the APIs listed here: Push Measure Data into SAP Sustainability Control Tower.
  For example, if you want to push emission data, use the API /pushEmissionData:
```
POST /pushEmissionData
```
- To push data for basic custom metrics, use the API Push Metric Data into SAP Sustainability Control Tower.
After successfully pushing the data, validate it next (see the section Validation and Persistence in SAP Business Accelerator Hub):
```
POST /validate
```
Retrieve your validation results:
```
GET /validationResults(runId='runId')
```
In case of any errors, check the logs in the Manage Quantitative ESG Data app or fetch the validation logs for a particular measure by using the entity path.

Example

If you want to fetch the logs from pushing emission data, use the /Emissions path with the runId filter. For the current run, you can find any issues in the section validationIssues after each record.
You have two options on how to proceed in case there are errors in the data:
1. Publish the valid records, see step 5.
2. Interrupt the process by discarding the current run, using the API /discardRun.
```
POST /discardRun
```
  After fixing the issues, re-import the data and validate it again, using the three API calls from steps 1 to 3.
After successfully validating your data, publish it using the call:
```
POST /publish
```

Importing Master Data for Dimensions with User-Defined Values and Custom Dimensions

For most dimensions with user-defined values and for custom dimensions, the import, validation, and publishing of master data values is done as a single "push" step, but for reporting hierarchies you need separate steps for "push", "validate", and "publish".

API Flow for Dimensions with User-Defined Values

You can use the following APIs to push master data values to dimensions with user-defined values:

POST Account
POST Asset Class
POST Asset Transaction Type
POST GL Account
POST Absence Type
POST Account To Group
POST Air Emission Type
POST Emission Pollutant Type
POST Employee Category
POST Energy Carrier
POST Ethnicity
POST Gender
POST Grade
POST Leave Reason
POST Payment Type
POST Sentence Type
POST Use of Energy

For example, to push data to the "Absence Type" dimension, you use:

POST./pushAbsenceTypeData

When the process is complete, you see a response from the POST method that confirms it was successful, or indicates if there was a problem. Data that was successfully posted is immediately available for use in the apps (there are no further validation or publishing steps).

API Flow for Custom Dimensions

You can use the API to push master data values to custom dimensions as follows:

Add the customDimensionId value to the payload so that the system knows which dimension to push the data to.
Push the data using /pushCustomDimensionData:
```
POST./pushCustomDimensionData
```

When the process is complete, you see a response from the POST method that confirms it was successful, or indicates if there was a problem. Data that was successfully posted is immediately available for use in the apps (there are no further validation or publishing steps).

API Flow for Reporting Hierarchies

For reporting hierarchies (Organizational Unit, Business Location, Legal Entity) there are separate steps for pushing, validating, and publishing data using APIs. There are separate APIs for the Nodes and Links for each dimension:

POST Business Location Node
POST Business Location Link
POST Legal Entity Node
POST Legal Entity Link
POST Organizational Unit Node
POST Organizational Unit Link

First, use the API to push the data.
For example:
```
POST./pushBusinessLocationNodeData
```
After successfully pushing the data, validate it with:
```
POST./validate
```
retrieve your validation results:
```
GET./validationResults(runID='runID')
```
In case of any errors, check the logs in the Manage Master Data app or fetch the validation logs for a particular measure by using the entity path.

Example

If you want to fetch the logs from pushing Business Location Node data, use the /BusinessLocationNode path with the runId filter. For the current run, you can find any issues in the section validationIssues after each record.
You have two options on how to proceed in case there are errors in the data:
1. Publish the valid records, see step 5.
2. Interrupt the process by discarding the current run, using the API /discardRun.
```
POST /discardRun
```
  After fixing the issues, re-import the data and validate it again, using the three API calls from steps 1 to 3.
After successfully validating your data, publish it using the call:
```
POST /publish
```

Grouping Multiple API Requests (All Inbound Data Types)

If you want to import more than 10,000 records at a time, use the set of APIs for managing runs as listed below. These APIs enable you to group multiple requests into one run.

Procedure

First, start a run. This request returns a runId:
```
POST /startRun
```
To push data, for example, for emissions, use the runId you have received in step 1 above. You can send multiple requests with this runId to send data in bulk. Each request has an upper limit of 10,000 records.
```
POST /pushEmissionData
```
End the current run with the given runId that you have obtained from step 1:
```
POST /endRun
```
After successfully pushing the data, validate it next (see the section Validation and Persistence in SAP Business Accelerator Hub):
```
POST /validate
```
Retrieve your validation results:
```
GET /validationResults(runId='runId')
```
In case of any errors, fetch the validation logs for a particular measure by using the entity path.

Example

If you want to fetch the logs from pushing emission data, use the /Emissions path with the runId filter. For the current run, you can find any issues in the section validationIssues after each record.
You have two options on how to proceed in case there are errors in the data:
1. Publish the valid records, see step 7.
2. Interrupt the process by discarding the current run, using the API /discardRun.
```
POST /discardRun
```
  After fixing the issues, re-import the data and validate it again, using the three API calls from steps 1 to 5.
After successfully validating your data, publish it using the call:
```
POST /publish
```

Adding User Information (Metrics and Measures Only)

When importing data using APIs, users remain anonymous by default. If you want to add more context to your user, for example, by allowing your user name and email address to be visible, you can do so by using the options listed below. This only applies when importing data for metrics and measures, it does not apply to master data values for dimesnions. All three are standard methods for business user login. The token service URL, client ID, and client secret are available in the service key of your service instance.

Prerequisites

Assign the role SUS_SCT_Inbound_Api_Administrator to any user you want to give access to the inbound APIs to push data into SAP Sustainability Control Tower with their user information.

Client Credentials

This authentication method is the default and does not propagate user information. Use this method if your user information should remain anonymous.

Send a request for an access token with the following properties:

Property	Value
Token Service URL	Append `/oauth/token` to the URL you have obtained from your service instance credentials. Example https://<my-sap-sustainability-control-tower-instance>.authentication.eu20.hana.ondemand.com/oauth/token
Client ID	<client ID from the service key>
Client Secret	<client secret from the service key>
Grant Type	`client_credentials`

Supply the retrieved JWT (JSON Web Token) as part of the Authorization header in the HTTP calls.

Authorization Code

Use this two-step process to authorize your user.

Send an authentication request to the authorization server with the following properties:

Property	Value
Callback URL	The URL from your launchpad, depending on the region: Example For `eu20`: https://<subdomain>.eu20.sct.sustainability.cloud.sap For `us10`: https://<subdomain>.us10.sct.sustainability.cloud.sap
Authorization URL	Append `/oauth/token` to the URL you have obtained from your service instance credentials. Example https://<my-sap-sustainability-control-tower-instance>.authentication.eu20.hana.ondemand.com/oauth/token
Client ID	<client ID from the service key>
Client Secret	<client secret from the service key>
Grant Type	`authorization_code`

You will receive an authorization code.

Send the authorization code to receive an access token through the authorization server.
Supply the retrieved JWT (JSON Web Token) as part of the Authorization header in the HTTP calls.

Password Credentials

Use the password grant flow to authorize your user.

Send a request with the following properties to the OAuth server to receive an access token:

Property	Value
Token Service URL	Append `/oauth/token` to the URL you have obtained from your service instance credentials. Example https://<my-sap-sustainability-control-tower-instance>.authentication.eu20.hana.ondemand.com/oauth/token
Client ID	<client ID from the service key>
Client Secret	<client secret from the service key>
Grant Type	`password`
User Name	Your unique user name
Password	Your unique password

Supply the retrieved JWT (JSON Web Token) as part of the Authorization header in the HTTP calls.

Working with Reporting Scopes

The Reporting Scopes API allows you to create, update, and delete reporting scopes and their associated data. Use this API to define organizational boundaries, add disclosure requirement items, assign metrics, and control the scope lifecycle through actions such as release, withdrawal, and versioning.

API Flow for Batch Requests

POST /$batch Sends a group of requests

API Flow for Scopes

GET /Scopes Retrieves a list of scopes
POST /Scopes Creates a single scope
GET /Scopes({ID}) Retrieves a single scope
PATCH /Scopes({ID}) Changes a single scope
DELETE /Scopes({ID}) Deletes a single scope
POST /Scopes({ID})/ScopingAPIService.copy Copy the Scope
POST /Scopes({ID})/ScopingAPIService.createNewVersion Create a New Version of the Scope
POST /Scopes({ID})/ScopingAPIService.release Release the Scope
POST /Scopes({ID})/ScopingAPIService.resetOrganizationalBoundaries Reset Organizational Boundaries of the Scope
POST /Scopes({ID})/ScopingAPIService.resetScopeItems Reset Scope Items of the Scope
POST /Scopes({ID})/ScopingAPIService.withdraw Withdraw the Scope
GET /Scopes({ID})/organizationalBoundaries Retrieves a list of organizational boundaries of a scope
POST /Scopes({ID})/organizationalBoundaries Creates a single organizational boundary of a scope
GET /Scopes({ID})/scopeItems Retrieves a list of scope items of a scope
POST /Scopes({ID})/scopeItems Creates a single scope item of a scope
DELETE /Scopes({ID})/organizationalBoundaries({ScopeOrganizations_ID}) Deletes a single organizational boundary of a scope
PATCH /Scopes({ID})/scopeItems({ScopeItems_ID}) Changes a single scope item of a scope
DELETE /Scopes({ID})/scopeItems({ScopeItems_ID}) Deletes a single scope item of a scope
GET /Scopes({ID})/scopeItems({ScopeItems_ID})/metrics Retrieves a list of metrics of a scope item
POST /Scopes({ID})/scopeItems({ScopeItems_ID})/metrics Creates a single metric for a scope item
DELETE /Scopes({ID})/scopeItems({ScopeItems_ID})/metrics({ScopeMetrics_ID}) Deletes a single metric of a scope item

API Flow for Scope Organizations

GET /ScopeOrganizations Retrieves a list of scope organizations
GET /ScopeOrganizations({ID}) Retrieves a single scope organization

API Flow for Scope Items

GET /ScopeItems Retrieves a list of scope items
GET /ScopeItems({ID}) Retrieves a single scope item
GET /ScopeItems({ID})/metrics Retrieves a list of metrics of a scope item
POST /ScopeItems({ID})/metrics Creates a single metric of a scope item

API Flow for Scope Metrics

GET /ScopeMetrics Retrieves a list of scope metrics
GET /ScopeMetrics({ID}) Retrieves a single scope metric