Submitting Evidence
On this page
ToggleAn API, or Application Programming Interface, is a set of rules and protocols that allows different software applications to communicate with each other. It serves as an intermediary between different software components, enabling them to interact and exchange data seamlessly.
Submitting evidence securely and efficiently is crucial in various professional and legal contexts. TrustCloud API provides a robust platform designed to streamline the process of evidence submission. Whether you are handling compliance tests, legal documentation, or any other form of verification, understanding how to properly submit evidence through TrustCloud API is essential.
The TrustCloud API offers a secure and efficient solution for submitting evidence in professional and legal contexts. By utilizing the API’s features, such as retrieving tests with evidence due, submitting links or files as evidence, and completing tests, organizations can streamline their compliance and governance processes.
Integrating the TrustCloud API into systems not only minimizes human error but also enhances operational efficiency, ensuring regulatory adherence and maintaining a strong and trustworthy business environment.
With TrustCloud’s API, you can deepen your insights, increase automation in your GRC workflow, and eliminate risky manual tasks.
This tutorial demonstrates how to retrieve tests that have evidence due, complete the test, and submit the evidence using the TrustCloud API.
To access TrustCloud API,
- Go to your TrustCloud program.
- Click on “Integrations” and select “API Access.”
The following screenshot shows the TrustCloud API access page.
Retrieving a TrustCloud API Key
To make requests to the TrustCloud API, an API key is required. To obtain an API key, please contact support, and follow the instructions in the Getting Started Guide to connect to the API.
Setting up the Request
Before we make any requests, we need to set up our HTTP headers. We need to include the API key in the “Authorization” header and set the “x-trustcloud-api-version” header to 1 to ensure we are using the correct API version.
Here is an example of the headers we need to include in our HTTP request:
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
HttpGet request = new HttpGet("https://api.trustcloud.ai/tests");
request.setHeader("Authorization", "");
request.setHeader("x-trustcloud-api-version", "1");
using RestSharp;
using RestSharp.Authenticators;
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
import requests
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
package main
import (
"encoding/json"
"fmt"
"net/http"
)
apiKey := ""
url := "https://api.trustcloud.ai/v1/tests"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
GET /controls HTTP/1.1
Host: api.trustcloud.ai
Authorization: Bearer
x-trustcloud-api-version: 1
Retrieve tests with evidence due
To retrieve a list of tests with evidence due, query the /tests API to retrieve a list of tests. The /tests API includes a number of query filter options that you can use:
- name: The name of the test
- evidenceStatus: The status of evidence requirements for this test. Options are:
- missing: Required evidence has not been provided
- due: Evidence required is due
- outdated: Evidence is past-due
- up_to_date: All evidence is up to date for this test
- not_required: Evidence is not required for this test
- testStatus: The current status of the test
- available: The test is not executing, and is available to view or execute
- in_progress: The test is currently executing
- excluded: The test has been excluded from the program. No evidence or test execution is required.
- evidenceDueByDate: All tests with evidence that is pending and due before the specified date (yyyy-mm-dd format).
- EvidenceDueByDays: All tests with evidence that is pending and due in the next x days.
In this example, we will query all tests with an evidence status of due.
const axios = require('axios');
const apiKey = '';
const url = 'https://api.trustcloud.ai/tests?evidenceStatus=due';
axios.get(url, {
headers: {
'Authorization': apiKey,
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
public class TrustCloud {
public static void main(String[] args) throws IOException {
String apiKey = "";
URL url = new URL("https://api.trustcloud.ai/tests?evidenceStatus=due");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", apiKey);
connection.setRequestProperty("x-trustcloud-api-version", "1");
Scanner scanner = new Scanner(connection.getInputStream());
while (scanner.hasNext()) {
System.out.println(scanner.nextLine());
}
scanner.close();
}
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
class TrustCloud {
static async Task Main(string[] args) {
string apiKey = "";
string url = "https://api.trustcloud.ai/tests?evidenceStatus=due";
using (HttpClient client = new HttpClient()) {
client.DefaultRequestHeaders.Add("Authorization", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
HttpResponseMessage response = await client.GetAsync(url);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
}
import requests
api_key = ''
url = 'https://api.trustcloud.ai/tests?evidenceStatus=due'
headers = {
'Authorization': api_key,
'x-trustcloud-api-version': '1'
}
response = requests.get(url, headers=headers)
print(response.json())
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := ""
url := "https://api.trustcloud.ai/tests?evidenceStatus=due"
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", apiKey)
req.Header.Add("x-trustcloud-api-version", "1")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
GET /tests?evidenceStatus=due HTTP/1.1
Host: api.trustcloud.ai
Authorization:
x-trustcloud-api-version: 1
Here is an example of the response we might receive:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234
[
{
"id": "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f",
"testId": "change-management",
"type": "self_assessment",
"name": "Change management workflow",
"level": "basic",
"question": "Do you have a documented change management process outlining the workflow for propagating application and infrastructure code changes to production environments, including tracking, testing, review, and approval?",
"recommendation": "Document your change management process, outlining the workflow for propagating application and infrastructure code changes to the production environment. Including information about tracking, testing, review, and approval processes.",
"evidenceCount": {},
"evidenceDescription": "Your change management, release management, or software development life cycle process documentation, outlining the workflows for propagating application and infrastructure code changes to production environments, including tracking, testing, review and approval",
"evidenceStatus": "missing",
"executionOutcome": {},
"executionSatus": {},
"nextEvidenceDueDate": {},
"owner": {
"name": {},
"id": {}
},
"control": {
"id": "cd2d4fe0-187f-4126-9cdb-edb9867b8040",
"controlId": "PDP-11",
"name": "Product Delivery Process",
"category": "Change Management Workflow"
},
"system": {
"id": {},
"name": {}
},
"metadata": {
"createdby": "59246246-ed25-48a8-ae5e-67732c6ee332",
"createddate": "2022-02-15 17:14:28.757+00",
"lastmodifiedby": "0ef2f025-46df-47d0-8bcd-11f62aa10612",
"lastmodifieddate": "2023-02-20 16:16:07.316+00"
},
},...
]
Submitting a link as evidence
You can submit a link as evidence by invoking the POST /tests/{id}/evidence with a type of “link” and passing the URL in the request body.
const axios = require('axios');
const apiKey = '';
const testId = 'c6354cde-3a4e-4b35-8bfd-aafb33a9f44f';
const url = `https://api.trustcloud.ai/tests/${testId}/evidence`;
const data = {
type: 'link',
url: 'https://someurl.com',
description: 'Some URL evidence to support my test.',
evidenceDate: '2022/12/31'
};
axios.post(url, data, {
headers: {
'Authorization': apiKey,
'Content-Type': 'application/json',
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
public class TrustCloudLink {
public static void main(String[] args) throws IOException {
String apiKey = "";
String testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
String url = "https://api.trustcloud.ai/tests/" + testId + "/evidence";
OkHttpClient client = new OkHttpClient();
String json = "{\"type\":\"link\",\"url\":\"https://someurl.com\",\"description\":\"Some URL evidence to support my test.\",\"evidenceDate\":\"2022/12/31\"}";
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
RequestBody requestBody = RequestBody.create(json, JSON);
Request request = new Request.Builder()
.url(url)
.post(requestBody)
.addHeader("Authorization", apiKey)
.addHeader("x-trustcloud-api-version", "1")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class TrustCloudLink
{
static async Task Main()
{
string apiKey = "";
string testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
string url = $"https://api.trustcloud.ai/tests/{testId}/evidence";
using HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
string json = "{\"type\":\"link\",\"url\":\"https://someurl.com\",\"description\":\"Some URL evidence to support my test.\",\"evidenceDate\":\"2022/12/31\"}";
HttpContent content = new StringContent(json, Encoding.UTF8, "application/json");
HttpResponseMessage response = await client.PostAsync(url, content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
import requests
api_key = ""
test_id = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url = f"https://api.trustcloud.ai/tests/{test_id}/evidence"
headers = {
"Authorization": api_key,
"Content-Type": "application/json",
"x-trustcloud-api-version": "1"
}
data = {
"type": "link",
"url": "https://someurl.com",
"description": "Some URL evidence to support my test.",
"evidenceDate": "2022/12/31"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
type EvidenceLink struct {
Type string `json:"type"`
URL string `json:"url"`
Description string `json:"description"`
EvidenceDate string `json:"evidenceDate"`
}
func main() {
apiKey := ""
testID := "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url := "https://api.trustcloud.ai/tests/" + testID + "/evidence"
data := EvidenceLink{
Type: "link",
URL: "https://someurl.com",
Description: "Some URL evidence to support my test.",
EvidenceDate: "2022/12/31",
}
jsonData, err := json.Marshal(data)
if err != nil {
panic(err)
}
client := &http.Client{}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trustcloud-api-version", "1")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/evidence HTTP/1.1
Host: api.trustcloud.ai
Authorization:
Content-Type: application/json
x-trustcloud-api-version: 1
{
"type": "link",
"url": "https://someurl.com",
"description": "Some URL evidence to support my test.",
"evidenceDate": "2022/12/31"
}
Submitting a file as evidence
You can submit a file as evidence submitting by invoking the POST /tests/{id}/evidence with a type of “file” and passing the filename in the request body. Files are submitted via multipart form post, with the metadata
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');
const apiKey = '';
const testId = 'c6354cde-3a4e-4b35-8bfd-aafb33a9f44f';
const url = `https://api.trustcloud.ai/tests/${testId}/evidence`;
const formData = new FormData();
formData.append('description', 'Some file to support my test.');
formData.append('evidenceDate', '2022/12/31');
formData.append('type', 'file');
formData.append('file', fs.createReadStream('evidence.png'), 'evidence.png');
axios.post(url, formData, {
headers: {
...formData.getHeaders(),
'Authorization': apiKey,
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.File;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.RequestBody;
import okhttp3.Request;
import okhttp3.Response;
public class TrustCloudFile {
public static void main(String[] args) throws IOException {
String apiKey = "";
String testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
String url = "https://api.trustcloud.ai/tests/" + testId + "/evidence";
String filePath = "evidence.png";
OkHttpClient client = new OkHttpClient();
File file = new File(filePath);
MediaType mediaType = MediaType.parse("image/png");
RequestBody fileBody = RequestBody.create(file, mediaType);
RequestBody requestBody = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("description", "Some file to support my test.")
.addFormDataPart("evidenceDate", "2022/12/31")
.addFormDataPart("type", "file")
.addFormDataPart("file", "evidence.png", fileBody)
.build();
Request request = new Request.Builder()
.url(url)
.post(requestBody)
.addHeader("Authorization", apiKey)
.addHeader("x-trustcloud-api-version", "1")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class TrustCloudFile
{
static async Task Main()
{
string apiKey = "";
string testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
string url = $"https://api.trustcloud.ai/tests/{testId}/evidence";
string filePath = "evidence.png";
using HttpClient client = new HttpClient();
using MultipartFormDataContent formData = new MultipartFormDataContent();
formData.Add(new StringContent("Some file to support my test."), "description");
formData.Add(new StringContent("2022/12/31"), "evidenceDate");
formData.Add(new StringContent("file"), "type");
formData.Add(new StreamContent(File.OpenRead(filePath)), "file", "evidence.png");
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
HttpResponseMessage response = await client.PostAsync(url, formData);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
import requests
api_key = ""
test_id = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url = f"https://api.trustcloud.ai/tests/{test_id}/evidence"
headers = {
"Authorization": api_key,
"x-trustcloud-api-version": "1"
}
data = {
"description": "Some file to support my test.",
"evidenceDate": "2022/12/31",
"type": "file"
}
with open("evidence.png", "rb") as file:
files = {"file": ("evidence.png", file, "image/png")}
response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
apiKey := ""
testID := "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url := "https://api.trustcloud.ai/tests/" + testID + "/evidence"
var buffer bytes.Buffer
writer := multipart.NewWriter(&buffer)
description, _ := writer.CreateFormField("description")
io.WriteString(description, "Some file to support my test.")
evidenceDate, _ := writer.CreateFormField("evidenceDate")
io.WriteString(evidenceDate, "2022/12/31")
evidenceType, _ := writer.CreateFormField("type")
io.WriteString(evidenceType, "file")
file, err := os.Open("evidence.png")
if err != nil {
fmt.Println(err)
return
}
defer file.Close()
fileWriter, _ := writer.CreateFormFile("file", "evidence.png")
io.Copy(fileWriter, file)
writer.Close()
req, _ := http.NewRequest("POST", url, &buffer)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
var respBuffer bytes.Buffer
io.Copy(&respBuffer, resp.Body)
fmt.Println(respBuffer.String())
}
POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/evidence HTTP/1.1
Host: api.trustcloud.ai
Authorization:
Content-Type: multipart/form-data; boundary=
x-trustcloud-api-version: 1
--
Content-Disposition: form-data; name="description"
Some file to support my test.
--
Content-Disposition: form-data; name="evidenceDate"
2022/12/31
--
Content-Disposition: form-data; name="type"
file
--
Content-Disposition: form-data; name="file"; filename="evidence.png"
Content-Type:
----
Completing the test
Once you submit evidence associated with a test, you can complete the test by invoking POST /tests/{id}/execute and answering the assessment with either a yes (to pass the assessment) or no to fail the assessment. .
const axios = require('axios');
const apiKey = '';
const testId = 'c6354cde-3a4e-4b35-8bfd-aafb33a9f44f';
const url = `https://api.trustcloud.ai/tests/${testId}/execute`;
const data = {
answer: yes,
comment: “Optional description of the assessment details”
};
axios.post(url, data, {
headers: {
'Authorization': apiKey,
'Content-Type': 'application/json',
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
public class TrustCloudLink {
public static void main(String[] args) throws IOException {
String apiKey = "";
String testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
String url = "https://api.trustcloud.ai/tests/" + testId + "/execute";
OkHttpClient client = new OkHttpClient();
String json = "{\"answer\":\"yes\",\"comment\":\"Optional description of the assessment details\"}";
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
RequestBody requestBody = RequestBody.create(json, JSON);
Request request = new Request.Builder()
.url(url)
.post(requestBody)
.addHeader("Authorization", apiKey)
.addHeader("x-trustcloud-api-version", "1")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class TrustCloudLink
{
static async Task Main()
{
string apiKey = "";
string testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
string url = $"https://api.trustcloud.ai/tests/{testId}/execute";
using HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
string json = "{\"answer\":\"yes\",\"comment\":\"Optional description of the assessment details\"}";
HttpContent content = new StringContent(json, Encoding.UTF8, "application/json");
HttpResponseMessage response = await client.PostAsync(url, content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
import requests
api_key = ""
test_id = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url = f"https://api.trustcloud.ai/tests/{test_id}/evidence"
headers = {
"Authorization": api_key,
"Content-Type": "application/json",
"x-trustcloud-api-version": "1"
}
data = {
"answer": "yes",
"comment": "Optional description of the assessment details"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
type EvidenceLink struct {
Type string `json:"type"`
URL string `json:"url"`
Description string `json:"description"`
EvidenceDate string `json:"evidenceDate"`
}
func main() {
apiKey := ""
testID := "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url := "https://api.trustcloud.ai/tests/" + testID + "/execute"
data := EvidenceLink{
answer: "yes",
comment: "Optional description of the assessment details"
"
}
jsonData, err := json.Marshal(data)
if err != nil {
panic(err)
}
client := &http.Client{}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trustcloud-api-version", "1")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/execute HTTP/1.1
Host: api.trustcloud.ai
Authorization:
Content-Type: application/json
x-trustcloud-api-version: 1
{
"answer": "yes",
"comment": "Optional description of the assessment details"
}
API Reference
In conclusion, submitting evidence securely and efficiently via the TrustCloud API serves as a strategic asset to enhance compliance and governance processes. By integrating specific API calls into your systems, you can automate and streamline the evidence retrieval and submission process, minimizing human error and increasing operational efficiency. Whether you are managing tests, tracking evidence due dates, or submitting various types of evidence, the TrustCloud API provides a robust and secure platform to support your needs. Implementing these tools not only simplifies regulatory adherence but also fortifies the integrity of your organizational processes, ultimately helping you maintain a strong, compliant, and trustworthy business environment.
Deepen your insights and increase automation in your GRC workflow!
TrustCloud’s API empowers you to leverage your data so you can eliminate risky manual tasks and maximize your efficiency.
Read more about TrustCloud API here.
Want to learn more about GRC?
Explore our GRC launchpad to gain expertise on numerous compliance standards and topics.