Table of Content
🚀 Getting Started
The endpoint to access the Whistic Reporting API is located at https://graphql.whistic.com
To access your data, you'll need a Whistic API key. You can create this key in the Whistic API:
- From the dropdown Settings, select Integrations. (also found under Resources dropdown)
- From Integrations, select Whistic Public API
- Select Generate New Key
Once you have your key, test it by running this cURL script:
curl --location 'https://graphql.whistic.com' \
--header 'api-key: your_api_key' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Content-Type: application/json' \
--data '{"query":"query { hello }","variables":{}}'If the test was successful, you'll see this as a response:
{"data":{"hello":"Hello world!"}} 📊 Retrieving Your Data
Moving beyond the simple example, here are some other cURL scripts that may be useful to access data from your Whistic account:
Vendor Information:
curl --location 'https://graphql.whistic.com' \
--header 'api-key: your_api_key' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Content-Type: application/json' \
--data '{"query":"query reportFull(\n $index: String,\n $page_size: Int,\n $page: Int,\n $sort_by: [ReportSortBy],\n $search: ReportSearch,\n $cursor: [String],\n $includeFields: [String],\n $aggregate_on: [String],\n $filters: [ReportFilter],\n $report_aggregation_value_requests: [ReportAggregationValueRequest],\n $use_saved_catalog_settings: Boolean,\n $kbQABatchId: String\n) {\n report(\n index: $index,\n page_size: $page_size,\n page: $page,\n sort_by: $sort_by,\n search: $search,\n cursor: $cursor,\n includeFields: $includeFields,\n aggregate_on: $aggregate_on,\n filters: $filters,\n report_aggregation_value_requests: $report_aggregation_value_requests,\n use_saved_catalog_settings: $use_saved_catalog_settings,\n kbQABatchId: $kbQABatchId\n ) {\n data {\n cells {\n name\n type\n __typename\n }\n __typename\n }\n aggregations {\n name\n dateType\n buckets {\n value\n count\n __typename\n }\n __typename\n }\n aggregation_values {\n name\n type\n value\n __typename\n }\n total\n cursor\n __typename\n }\n}","variables":{"index":"vendors","page_size":10,"page":0,"sort_by":[{"name":"Vendor Created Date","order":"desc"}],"search":{"query":"","fields":["Vendor Name","Service/Product","Assessment Progress","Questionnaire Progress","Results","Criticality","Vendor Status","Vendor Created Date","Crowd Confidence Score"]},"includeFields":["Vendor Name","Service/Product","Assessment Progress","Questionnaire Progress","Results","Criticality","Vendor Status","Vendor Created Date","Crowd Confidence Score","Identifier"],"filters":[{"name":"Vendor Created Date","from":"2020-02-05T07:00:00.000Z","to":"2024-02-27T07:00:00.000Z"}],"use_saved_catalog_settings":true}}'Customer Information:
curl --location 'https://graphql.whistic.com' \
--header 'api-key: your_api_key' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Content-Type: application/json' \
--data '{"query":"query reportFull(\n $index: String\n $page_size: Int\n $page: Int\n $sort_by: [ReportSortBy]\n $search: ReportSearch\n $cursor: [String]\n $includeFields: [String]\n $aggregate_on: [String]\n $filters: [ReportFilter]\n $report_aggregation_value_requests: [ReportAggregationValueRequest]\n $use_saved_catalog_settings: Boolean\n $kbQABatchId: String\n) {\n report(\n index: $index\n page_size: $page_size\n page: $page\n sort_by: $sort_by\n search: $search\n cursor: $cursor\n includeFields: $includeFields\n aggregate_on: $aggregate_on\n filters: $filters\n report_aggregation_value_requests: $report_aggregation_value_requests\n use_saved_catalog_settings: $use_saved_catalog_settings\n kbQABatchId: $kbQABatchId\n ) {\n data {\n cells {\n name\n value\n href\n displayColor\n tooltip\n type\n __typename\n }\n __typename\n }\n aggregations {\n name\n dateType\n buckets {\n value\n count\n __typename\n }\n __typename\n }\n aggregation_values {\n name\n type\n value\n __typename\n }\n total\n cursor\n __typename\n }\n}\n","variables":{"index":"customers","page_size":10,"page":0,"sort_by":[{"name":"Share Date","order":"desc"}],"search":{"query":"Mastercard","fields":["Viewed Date","Share Date","Share Source","Customer Domain","Customer Name","Recipient Full Name","Sender Full Name","NDA Accepted Date","Recipient Title","Recipient Email","Type","Identifier","NDA Status","Version","Sender Title","Sender Email","Share Status","NDA Accepted By","NDA Source"]},"includeFields":["Viewed Date","Share Date","Share Source","Customer Domain","Customer Name","Recipient Full Name","Sender Full Name","NDA Accepted Date","Recipient Title","Recipient Email","Type","Identifier","NDA Status","Version","Sender Title","Sender Email","Share Status","NDA Accepted By","NDA Source","Identifier"],"filters":[],"use_saved_catalog_settings":true}}'🧪 Customer Sandbox
Often, running cURL scripts against the endpoint is not the optimal way to develop queries for the Whistic Reporting API. We have provided a sandbox tool that is available in our stage environment. To use it, you'll need to have a Whistic sandbox account and generate a new API key in that account.
Once you have access to stage and have generated an API key, go to https://graphql.whistic.co to view the sandbox UI.
In order to query your stage data, you will need to set the `api-key` header in the UI. This is done in the bottom panel of the screen, under the "Headers" tab:
Add a new header named `api-key` and paste in your stage API key as the value:
Then in the "Operation" panel of the UI, paste in this "Hello world" query and see if it responds appropriately in the "Response" panel.
Here's the query to paste into the "Operation" panel:
query {
hello
}Here's what a successful result should look like:
⚙️ Running More Complex Queries
If that worked, here are some more complex queries. These queries are structured with variables that you can change to tailor the results to your liking. This means there are two parts needed to execute the query in the sandbox. You'll paste the operation into the "Operation" panel, and then paste the variables into the "Variables" tab in the lower section of the UI.
Vendor Information:
Operation:
query reportFull(
$index: String,
$page_size: Int,
$page: Int,
$sort_by: [ReportSortBy],
$search: ReportSearch,
$cursor: [String],
$includeFields: [String],
$aggregate_on: [String],
$filters: [ReportFilter],
$report_aggregation_value_requests: [ReportAggregationValueRequest],
$use_saved_catalog_settings: Boolean,
$kbQABatchId: String
) {
report(
index: $index,
page_size: $page_size,
page: $page,
sort_by: $sort_by,
search: $search,
cursor: $cursor,
includeFields: $includeFields,
aggregate_on: $aggregate_on,
filters: $filters,
report_aggregation_value_requests: $report_aggregation_value_requests,
use_saved_catalog_settings: $use_saved_catalog_settings,
kbQABatchId: $kbQABatchId
) {
data {
cells {
name
type
}
__typename
}
aggregations {
name
dateType
buckets {
value
count
__typename
}
__typename
}
aggregation_values {
name
type
value
__typename
}
total
cursor
__typename
}
}Variables:
{
"index": "vendors",
"page_size": 10,
"page": 0,
"sort_by": [
{
"name": "Vendor Created Date",
"order": "desc"
}
],
"search": {
"query": "",
"fields": [
"Vendor Name",
"Service/Product",
"Assessment Progress",
"Questionnaire Progress",
"Results",
"Criticality",
"Vendor Status",
"Vendor Created Date",
"Crowd Confidence Score"
]
},
"includeFields": [
"Vendor Name",
"Service/Product",
"Assessment Progress",
"Questionnaire Progress",
"Results",
"Criticality",
"Vendor Status",
"Vendor Created Date",
"Crowd Confidence Score",
"Identifier"
],
"filters": [
{
"name": "Vendor Created Date",
"from": "2020-02-05T07:00:00.000Z",
"to": "2024-02-27T07:00:00.000Z"
}
],
"use_saved_catalog_settings": true
}Here's a screenshot of the query setup in the sandbox:
Once you've customized the query to your liking, you can export the query to a cURL script and try it against the production endpoint (don't forget to change your API key to the production key). You export the query by clicking the ellipse button in the upper right corner of the "Operation" panel: