Submitting Evidence

Estimated reading: 25 minutes 509 views

This tutorial demonstrates how to retrieve tests that have evidence due, complete the test, and submit the evidence using the TrustCloud API. 

Retrieving an 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:

Javascript
				
					const headers = {
  'Authorization': '<your_api_key_here>',
  'x-trustcloud-api-version': '1'
};

				
			
Java
				
					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", "<your_api_key_here>");
request.setHeader("x-trustcloud-api-version", "1");

				
			
Csharp
				
					using RestSharp;
using RestSharp.Authenticators;
using System;
using System.Collections.Generic;

string apiKey = "<your_api_key_here>";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";

				
			
Python
				
					import requests
headers = {
   'Authorization': '<your_api_key_here>',
   'x-trustcloud-api-version': '1'
}

				
			
Go
				
					package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

apiKey := "<your_api_key_here>"
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")

				
			
Bash
				
					GET /controls HTTP/1.1
Host: api.trustcloud.ai
Authorization: Bearer <your_api_key_here>
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.  

Javascript
				
					const axios = require('axios');

const apiKey = '<your_api_key_here>';
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);
});



				
			
Java
				
					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 = "<your_api_key_here>";
        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();
    }
}

				
			
Csharp
				
					using System;
using System.Net.Http;
using System.Threading.Tasks;

class TrustCloud {
    static async Task Main(string[] args) {
        string apiKey = "<your_api_key_here>";
        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);
        }
    }
}

				
			
Python
				
					import requests

api_key = '<your_api_key_here>'
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())

				
			
Go
				
					package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	apiKey := "<your_api_key_here>"
	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))
}

				
			
Bash
				
					GET /tests?evidenceStatus=due HTTP/1.1
Host: api.trustcloud.ai
Authorization: <your_api_key_here>
x-trustcloud-api-version: 1

				
			

Here is an example of the response we might receive:

Html
				
					HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234

				
			
Html
				
					[  
  {
    "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.

Javascript
				
					const axios = require('axios');

const apiKey = '<your_api_key_here>';
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);
});

				
			
Java
				
					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 = "<your_api_key_here>";
        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());
    }
}

				
			
Csharp
				
					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 = "<your_api_key_here>";
        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);
    }
}

				
			
Python
				
					import requests

api_key = "<your_api_key_here>"
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())

				
			
Go
				
					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 := "<your_api_key_here>"
	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))
}

				
			
Bash
				
					POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/evidence HTTP/1.1
Host: api.trustcloud.ai
Authorization: <your_api_key_here>
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

Javascript
				
					const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const apiKey = '<your_api_key_here>';
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);
});

				
			
Java
				
					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 = "<your_api_key_here>";
        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());
    }
}

				
			
Csharp
				
					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 = "<your_api_key_here>";
        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);
    }
}

				
			
Python
				
					import requests

api_key = "<your_api_key_here>"
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())

				
			
Go
				
					package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	apiKey := "<your_api_key_here>"
	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())
}


				
			
Bash
				
					POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/evidence HTTP/1.1
Host: api.trustcloud.ai
Authorization: <your_api_key_here>
Content-Type: multipart/form-data; boundary=<boundary>
x-trustcloud-api-version: 1

--<boundary>
Content-Disposition: form-data; name="description"
Some file to support my test.

--<boundary>
Content-Disposition: form-data; name="evidenceDate"
2022/12/31

--<boundary>
Content-Disposition: form-data; name="type"
file

--<boundary>
Content-Disposition: form-data; name="file"; filename="evidence.png"
Content-Type: <file_mime_type>

<file_binary_data>
--<boundary>--

				
			

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.  .  

Javascript
				
					const axios = require('axios');

const apiKey = '<your_api_key_here>';
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);
});

				
			
Java
				
					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 = "<your_api_key_here>";
        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());
    }
}

				
			
Csharp
				
					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 = "<your_api_key_here>";
        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);
    }
}

				
			
Python
				
					import requests

api_key = "<your_api_key_here>"
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())

				
			
Go
				
					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 := "<your_api_key_here>"
	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))
}

				
			
Bash
				
					POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/execute HTTP/1.1
Host: api.trustcloud.ai
Authorization: <your_api_key_here>
Content-Type: application/json
x-trustcloud-api-version: 1

{
  "answer": "yes",
  "comment": "Optional description of the assessment details"
}

				
			

API Reference

Join the conversation

ON THIS PAGE
SHARE THIS PAGE

SUBSCRIBE
FlightSchool
OR