API Access to Suppliers Assessments
- Skill required
- Command Line Interface
You have been a user of a Practices Survey Platform (ex: tspproject.org). It works great! Now you are looking to mechanically pull suppliers assessments from the Practices Survey Platform into your internal Suppliers Relationship Management (SRM) or Enterprise Resource Planning (ERP) systems.
This tutorial will guide you through the important Practices Survey Platform APIs to do so.
Get an API key
The first step is to login into your user account on the Practices Survey Platform Website (ex: tspproject.org), then retrieve an API key.
To do so click on your username in the top-right corner of the browser window, then on Profile in the drop-down menu. Scroll down to the Programmatic Keys link, then click on it. On the Programmatic Keys page, click on the Reset API Key button. Enter your password, then click Update.
An API key will show up. It will only appear once so make sure to write it down in a secure place. This is the key we will use to authenticate to the Practices Survey Platform in further API calls.
Before moving forward, let's make sure the API works. We will do by retrieving information about our own user account.
curl -u api-key: https://api-base-url/api/users/user
Let's assume your username on www.tspproject.org is alice
and your API key is e4HQ*****Uhcg9p3B, running the curl
command shown after the prompt ($ sign) in a Terminal window, you should get
a JSON response with the details about alice's user account on
www.tspproject.org.
$ curl -u e4HQ*****Uhcg9p3B: https://www.tspproject.org/api/users/alice
{"slug":"alice","username":"alice","printable_name":"Alice","picture":null,"email":"alice@localhost.localdomain","phone":null,"full_name":"Alice","nick_name":"Alice","lang":"en","credentials":true,"created_at":"2017-03-23T18:05:01.065667Z","last_login":"2023-09-07T17:45:42.013612Z"}
We will use jq to format the output and make it more readable.
$ curl -u e4HQ*****Uhcg9p3B: https://www.tspproject.org/api/users/alice | jq .
{
"slug": "alice",
"username": "alice",
"printable_name": "Alice",
"picture": null,
"email": "alice@localhost.localdomain",
"phone": null,
"full_name": "Alice",
"nick_name": "Alice",
"lang": "en",
"credentials": true,
"created_at": "2017-03-23T18:05:01.065667Z",
"last_login": "2023-09-07T17:45:42.013612Z"
}
Retrieve the list of suppliers for my organization
Armed with a working API key, we are now going to retrieve the list of suppliers that have shared information with us. The following API is the core of the Track dashboard so you might also want to open the Developer Tools in your favorite browser, go to the Track dashboard for your organization, then look at the HTTP requests generated in the Network tab instead.
The API end point we are interested in is Lists accessible samples by year.
GET /api/{profile}/reporting/{campaign}/accessibles
The API endpoint requires two parameters, a profile and
a campaign. Let's say the unique key, or slug, for our
organization is energy-utility and we are interested in the
ESG/Environmental practices assessment which slug happens to
be sustainability.
We will thus run the following curl command in our Terminal window.
$ curl -u e4HQ*****Uhcg9p3B: https://www.tspproject.org/api/energy-utility/reporting/sustainability/accessibles | jq .
{
"count": 1,
"next": null,
"previous": null,
"title": "Accessibles",
"scale": 1,
"unit": null,
"labels": [
2022,
2023
],
"results": [{
"slug": "supplier-1",
"title": "S1 - Tamerin (Demo)",
"printable_name": "S1 - Tamerin (Demo)",
"extra": {"tags": []},
"values": [[
"2022-07-13T02:31:53.517288Z",
"completed",
"https://www.tspproject.org/app/energy-utility/scorecard/dda134c8b4da487da9169e771794deed/",
0
], [
"2023-03-08T19:31:16.015553Z",
"responded",
"https://www.tspproject.org/app/energy-utility/scorecard/d7094e01633d4cf2b5772209c8baf73a/",
0
]]
}]
}
We can see here that the output is following the
structure of APIs returning
a table of aggregated values over a metric.
The count is 1 because we only have one supplier.
previous and next are null because we have a single
page of results. results contains the bulk of the data we are
interested in.
Retrieve a supplier assessment
In the previous API response, we find the URL to browse to in order to view a supplier response on the Practices Survey Platform at a specific date. The URL is structured as https://api-base-url/app/profile/scorecard/sample/.
We will extract the sample unique slug and use it in a call to list answers for a sample.
GET /api/{profile}/sample/{sample}/content
Since our user account, alice, has a
role on
the energy-utility profile and the supplier shared their response
with energy-utility, we use energy-utility for the
profile parameter. - Note that if we were to use the supplier
slug (supplier-1), we would get a 403 permission denied because our
user account does not have a role on supplier-1.
$ curl -u e4HQ*****Uhcg9p3B: https://www.tspproject.org/api/energy-utility/sample/dda134c8b4da487da9169e771794deed/content | jq .
{
"count": 198,
"path": "",
"normalized_score": 62,
"verified_status": "no-review",
"results": [
...
{
"slug": "ghg-emissions-scope1",
"path": "/sustainability/data-measured/ghg-emissions-measured/ghg-emissions-totals/ghg-emissions-scope1",
"indent": 4,
"title": "Total Scope 1 GHG Emissions",
"picture": null,
"rank": 60,
"required": false,
"frozen": true,
"ui_hint": "ghg-emissions",
"extra": null,
"default_unit": {
"slug": "tons-year",
"title": "Metric Tons / Year",
"system": "standard",
"choices": null
},
"answers": [
{
"unit": "tons-year",
"measured": "9",
"created_at": "2022-07-13T02:31:53.354648Z",
"collected_by": "steve"
},
{
"unit": "starts-at",
"measured": "2021-01-01",
"created_at": "2022-07-13T02:31:53.354648Z",
"collected_by": "steve"
},
{
"unit": "ends-at",
"measured": "2021-12-31",
"created_at": "2022-07-13T02:31:53.354648Z",
"collected_by": "steve"
}
]
},
...
],
"units": {
"tons-year": {
"slug": "tons-year",
"title": "Metric Tons / Year",
"system": "standard",
"choices": null
},
"starts-at": {
"slug": "starts-at",
"title": "Starts at",
"system": "datetime",
"choices": null
},
"ends-at": {
"slug": "ends-at",
"title": "Ends at",
"system": "datetime",
"choices": null
}
}
}
We would like to know the total Scope1 GHG Emissions reported by
supplier-1 so we locate the specific answer through either
its slug or full path in the results
array. In the example above we read that steve reported
S1 - Tamerin (Demo) produced 9 metric tons of CO2e between
Jan 1st and Dec 31st 2021.
Wrapping up
In this tutorial we have seen how to retrieve an API key and call a Practices Survey Platform API endpoints to retrieve a list of suppliers that have shared information with our organization, then retrieve a detailed response for a specific supplier.