{
	"info": {
		"_postman_id": "47f650e8-4dbc-41df-8b6c-9d4a249ea941",
		"name": "SureCloud External API",
		"description": "# 📄 Get started here\n\nWelcome to the **SureCloud External API**.\n\nThis API provides secure access to metadata stored in your SureCloud tenant. It allows Integration Administrators to bulk retrieve entity information and record data for synchronisation or analysis in external systems.\n\nWith this API, you can:\n\n- Fetch a list of all entities available in your tenant.\n    \n- Retrieve all records for a given entity, including attribute values, workflow state and stage, linked records, and question answers.\n    \n- Build integrations or reporting pipelines without needing to query each record individually.\n    \n\n## 🚀 Getting started guide\n\nTo start using the SureCloud External API:\n\n1. **Request an API key** from SureCloud.\n    \n2. **Import this Postman collection** into your workspace.\n    \n3. **Set your collection variables**:\n    \n    - `tenant`\n        \n    - `apiKey`\n        \n4. Send a request to `GET /workflows` to verify your setup.\n    \n5. Use `GET /workflows/{workflowId}/records` to retrieve record metadata for a specific workflow's records.\n    \n\n## 🔑 Authentication\n\nAccess to the SureCloud External Read API is secured using **JSON Web Tokens (JWTs)**.\n\n### Obtaining a token\n\n- JWTs are issued directly by SureCloud upon request.\n    \n- Each token is tied to the tenant and a specific user.\n    \n- Tokens do **not expire automatically**. If you need to revoke a token (e.g. in case of compromise), please contact SureCloud Support.\n    \n- If you need an additional token, request one via your SureCloud Support.\n    \n\n### Using a token\n\nInclude the JWT in the `Authorization` header of every request:\n\n```\nAuthorization: Bearer <your-jwt-token>\n\n ```\n\n### Authentication errors\n\n- **401 Unauthorized** → Missing or invalid JWT\n    \n- **403 Forbidden** → JWT is valid, but you don’t have permission to access the requested data\n    \n\n## 📖 Pagination\n\nThe SureCloud External API uses **cursor-based pagination** to return large sets of records. Results are returned in deterministic order by creation date, followed by the identifier of the record (incase two records are created at the exact same time).\n\n### How it works\n\n- Each request returns a **page of results** (100 by default) along with a `nextCursor` value (if more results are available).\n    \n- To fetch the next page, include the `cursor` query parameter with the value of `nextCursor` from the previous response.\n    \n- When a `null` `nextCursor` is returned, you have reached the end of the dataset.\n    \n\n### Page size (`limit`)\n\nYou can control how many records are returned per page with the `limit` query parameter:\n\n- **Minimum**: `1`\n    \n- **Maximum**: `100`\n    \n- **Default**: `100`\n    \n\n### Request example\n\n```\nGET /api/v1/entities/risks/records?limit=50&nextCursor=eyJhbGciOiJIUzI1NiIsInR5cCI...\nAuthorization: Bearer <your-jwt-token>\n\n ```\n\n### Response example\n\n``` json\n{\n  \"entity\": \"Third Party\",\n  \"records\": [\n    { \"id\": \"550e8400-e29b-41d4-a716-446655440000\", \"attributes\": { \"name\": \"Third Party Risk\" }, ... },\n    { \"id\": \"6fa459ea-ee8a-3ca4-894e-db77e160355e\", \"attributes\": { \"name\": \"Data Privacy Breach\" }, ... }\n  ],\n  \"nextCursor\": \"eyJhbGciOiJIUzI1NiIsInR5cCI...\"\n}\n\n ```\n\n## 📊 Rate and usage guidelines\n\nAt present, the SureCloud External Read API does **not enforce any hard rate limits**.\n\nWe ask all clients to follow **fair usage practices** to ensure stability for everyone:\n\n- Avoid sending unnecessarily high-frequency requests.\n    \n- Use bulk endpoints (e.g. _Get All Records by Workflow_) instead of making repeated single-record calls.\n    \n- Implement caching where appropriate.\n    \n\n⚠️ Note: SureCloud reserves the right to introduce formal rate limiting in the future if usage patterns impact platform performance.\n\n## ⛔️ Error handling\n\n- **401 Unauthorized** – Invalid or missing API key\n    \n- **403 Forbidden** – Access denied due to record-level permissions\n    \n- **404 Not Found** – Requested data does not exist\n    \n- **5XX** – Server error (contact SureCloud support if persistent)\n    \n\n## 🆘 Need some help?\n\n- Visit the [Help Center](https://help.surecloud.io/hc/en-us) for further documentation.\n    \n- Contact **SureCloud Support** via your account portal for assistance.",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "16882070",
		"_collection_link": "https://surecloud.postman.co/workspace/7d62afb5-0db7-4e48-8fd0-5c989b0f1d04/collection/7828253-47f650e8-4dbc-41df-8b6c-9d4a249ea941?action=share&source=collection_link&creator=16882070"
	},
	"item": [
		{
			"name": "Workflows",
			"item": [
				{
					"name": "Get all workflows",
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{baseUrl}}/workflows",
							"host": [
								"{{baseUrl}}"
							],
							"path": [
								"workflows"
							]
						},
						"description": "Gets all of your [collections](https://www.getpostman.com/docs/collections). The response includes all of your subscribed collections."
					},
					"response": [
						{
							"name": "Successful",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows"
									]
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json",
									"description": {
										"content": "",
										"type": "text/plain"
									}
								}
							],
							"cookie": [],
							"body": "{\n    \"items\": [\n        {\n            \"workflowId\": \"a7b7a76d-c9cd-2ed0-b05d-6812e40d31da\",\n            \"name\": \"Third Party\"\n        },\n        {\n            \"workflowId\": \"8d495c7e-368f-46bf-a212-ac56f871b097\",\n            \"name\": \"Findings\"\n        },\n        {\n            \"workflowId\": \"33b42e3f-2d5d-4eae-2258-32384262c758\",\n            \"name\": \"Actions\"\n        },\n        {\n            \"workflowId\": \"c8f6080c-0b52-4daa-9102-4b44ae6d4ba7\",\n            \"name\": \"Exceptions\"\n        }\n    ],\n    \"nextCursor\": null\n}"
						},
						{
							"name": "Unauthorized",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows"
									]
								}
							},
							"status": "Unauthorized",
							"code": 401,
							"_postman_previewlanguage": "",
							"header": [],
							"cookie": [
								{
									"expires": "Invalid Date",
									"domain": "",
									"path": ""
								}
							],
							"body": ""
						}
					]
				}
			],
			"description": "The `/workflows` endpoints let you manage your workflows."
		},
		{
			"name": "Records",
			"item": [
				{
					"name": "Get all records of given workflow",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									""
								],
								"type": "text/javascript",
								"packages": {}
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
							"host": [
								"{{baseUrl}}"
							],
							"path": [
								"workflows",
								"{{workflowId}}",
								"records"
							]
						}
					},
					"response": [
						{
							"name": "Successful",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json",
									"description": {
										"content": "",
										"type": "text/plain"
									}
								}
							],
							"cookie": [],
							"body": "{\n  \"items\": [\n    {\n      \"recordId\": \"11111111-1111-1111-1111-111111111111\",\n      \"attributes\": [\n        { \"id\": \"aaaa1111-aaaa-1111-aaaa-1111aaaa1111\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control A\" } },\n        { \"id\": \"bbbb2222-bbbb-2222-bbbb-2222bbbb2222\", \"name\": \"SCF ID\", \"value\": { \"type\": \"TEXT\", \"data\": \"GOV-01\" } }\n      ]\n    },\n    {\n      \"recordId\": \"22222222-2222-2222-2222-222222222222\",\n      \"attributes\": [\n        { \"id\": \"cccc3333-cccc-3333-cccc-3333cccc3333\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control B\" } },\n        { \"id\": \"dddd4444-dddd-4444-dddd-4444dddd4444\", \"name\": \"SCF ID\", \"value\": { \"type\": \"TEXT\", \"data\": \"GOV-02\" } }\n      ]\n    },\n    {\n      \"recordId\": \"33333333-3333-3333-3333-333333333333\",\n      \"attributes\": [\n        { \"id\": \"eeee5555-eeee-5555-eeee-5555eeee5555\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control C\" } },\n        { \"id\": \"ffff6666-ffff-6666-ffff-6666ffff6666\", \"name\": \"SCF ID\", \"value\": { \"type\": \"TEXT\", \"data\": \"GOV-03\" } }\n      ]\n    },\n    {\n      \"recordId\": \"44444444-4444-4444-4444-444444444444\",\n      \"attributes\": [\n        { \"id\": \"1111aaaa-1111-aaaa-1111-aaaa1111aaaa\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control D\" } },\n        { \"id\": \"2222bbbb-2222-bbbb-2222-bbbb2222bbbb\", \"name\": \"SCF ID\", \"value\": { \"type\": \"TEXT\", \"data\": \"GOV-04\" } }\n      ]\n    },\n    {\n      \"recordId\": \"55555555-5555-5555-5555-555555555555\",\n      \"attributes\": [\n        { \"id\": \"3333cccc-3333-cccc-3333-cccc3333cccc\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control E\" } },\n        { \"id\": \"4444dddd-4444-dddd-4444-dddd4444dddd\", \"name\": \"SCF ID\", \"value\": { \"type\": \"TEXT\", \"data\": \"GOV-05\" } }\n      ]\n    }\n  ]\n}\n"
						},
						{
							"name": "Limit to 2 records",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records?limit=2",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									],
									"query": [
										{
											"key": "limit",
											"value": "2"
										}
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": "{\n  \"items\": [\n    {\n      \"recordId\": \"11111111-1111-1111-1111-111111111111\",\n      \"attributes\": [\n        { \"id\": \"aaaa1111-aaaa-1111-aaaa-1111aaaa1111\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control A\" } },\n      ]\n    },\n    {\n      \"recordId\": \"22222222-2222-2222-2222-222222222222\",\n      \"attributes\": [\n        { \"id\": \"cccc3333-cccc-3333-cccc-3333cccc3333\", \"name\": \"Name\", \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control B\" } },\n      ]\n    }\n  ],\n  \"nextCursor\": \"aaaa9999-bbbb-cccc-dddd-eeeeffff0000\"\n}\n"
						},
						{
							"name": "Next page of records",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records?limit=2&nextCursor=aaaa9999-bbbb-cccc-dddd-eeeeffff0000",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									],
									"query": [
										{
											"key": "limit",
											"value": "2"
										},
										{
											"key": "nextCursor",
											"value": "aaaa9999-bbbb-cccc-dddd-eeeeffff0000"
										}
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": "{\n  \"items\": [\n    {\n      \"recordId\": \"33333333-3333-3333-3333-333333333333\",\n      \"attributes\": [\n        { \n          \"id\": \"dddd4444-dddd-4444-dddd-4444dddd4444\", \n          \"name\": \"Name\", \n          \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control C\" } \n        }\n      ]\n    },\n    {\n      \"recordId\": \"44444444-4444-4444-4444-444444444444\",\n      \"attributes\": [\n        { \n          \"id\": \"eeee5555-eeee-5555-eeee-5555eeee5555\", \n          \"name\": \"Name\", \n          \"value\": { \"type\": \"TEXT\", \"data\": \"Example Control D\" } \n        }\n      ]\n    }\n  ],\n  \"nextCursor\": \"ffff1111-2222-3333-4444-555566667777\"\n}"
						},
						{
							"name": "Not Found",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows/workflow-id-does-not-exist/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"workflow-id-does-not-exist",
										"records"
									]
								}
							},
							"status": "Not Found",
							"code": 404,
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": "Aggregate of type Workflow with id 3fdb70b1-950b-4bf2-b5c1-bfa6b04f665c not found for tenant 58aefaf9-1536-4109-a4fb-f3300d44bdac"
						}
					]
				},
				{
					"name": "Get record of given workflow and recordid",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									""
								],
								"type": "text/javascript",
								"packages": {},
								"requests": {}
							}
						},
						{
							"listen": "prerequest",
							"script": {
								"exec": [
									""
								],
								"type": "text/javascript",
								"packages": {},
								"requests": {}
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{baseUrl}}/workflows/{{workflowId}}/records/{{recordId}}",
							"host": [
								"{{baseUrl}}"
							],
							"path": [
								"workflows",
								"{{workflowId}}",
								"records",
								"{{recordId}}"
							]
						}
					},
					"response": [
						{
							"name": "Not Found",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows/11111111-1111-1111-1111-111111111111/records/22222222-2222-2222-2222-222222222222",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"11111111-1111-1111-1111-111111111111",
										"records",
										"22222222-2222-2222-2222-222222222222"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": "Aggregate of type Record with id 22222222-2222-2222-2222-222222222222 not found for tenant 58aefaf9-1536-4109-a4fb-f3300d44bdac"
						},
						{
							"name": "Successful",
							"originalRequest": {
								"method": "GET",
								"header": [],
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records/{{recordId}}",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records",
										"{{recordId}}"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": "{\n    \"recordId\": \"11111111-1111-1111-1111-111111111111\",\n    \"attributes\": [\n    { \n        \"id\": \"aaaa1111-\n        \"value\": { \n            \"type\": \"TEXT\", \n            \"data\": \"Example Control A\"\n        } \n    },\n    { \n        \"id\": \"bbbb2222-bbbb-2222-bbbb-2222bbbb2222\", \n        \"name\": \"SCF ID\", \n        \"value\": { \n            \"type\": \"TEXT\",\n                \"data\": \"GOV-01\"\n        }\n    }\n    ]\n}"
						}
					]
				},
				{
					"name": "Create record for given workflow",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									""
								],
								"type": "text/javascript",
								"packages": {},
								"requests": {}
							}
						}
					],
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "raw",
							"raw": "",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
							"host": [
								"{{baseUrl}}"
							],
							"path": [
								"workflows",
								"{{workflowId}}",
								"records"
							]
						}
					},
					"response": [
						{
							"name": "Using attribute name as identifier",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"attributes\": [\n        {\n            \"name\": \"Attribute Name\",\n            \"value\": \"String value\"\n        }\n    ]\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": null
						},
						{
							"name": "Using attribute ID as identifier",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"attributes\": [\n        {\n            \"id\": \"d882ab3d-2e17-4b19-926c-802b3bc8bd65\",\n            \"value\": \"String value\"\n        }\n    ]\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": null
						},
						{
							"name": "Numeric values",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"attributes\": [\n        {\n            \"name\": \"Attribute Name\",\n            \"value\": 2\n        }\n    ]\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": null
						},
						{
							"name": "Boolean values",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"attributes\": [\n        {\n            \"name\": \"Attribute Name\",\n            \"value\": true\n        }\n    ]\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": null
						},
						{
							"name": "Date values",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"attributes\": [\n        {\n            \"name\": \"date\",\n            \"value\": \"1970-01-01\"\n        }\n    ]\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": null
						},
						{
							"name": "Multiple Values",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"attributes\": [\n        {\n            \"name\": \"Attribute Name\",\n            \"value\": [\"value 1\", \"value 2\"]\n        }\n    ]\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{baseUrl}}/workflows/{{workflowId}}/records",
									"host": [
										"{{baseUrl}}"
									],
									"path": [
										"workflows",
										"{{workflowId}}",
										"records"
									]
								}
							},
							"_postman_previewlanguage": null,
							"header": null,
							"cookie": [],
							"body": null
						}
					]
				}
			]
		}
	],
	"auth": {
		"type": "bearer",
		"bearer": [
			{
				"key": "token",
				"value": "{{apiKey}}",
				"type": "string"
			}
		]
	},
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"requests": {},
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"requests": {},
				"exec": [
					""
				]
			}
		}
	],
	"variable": [
		{
			"key": "tenant",
			"value": "exampleTenant",
			"description": "Your company's subdomain, e.g. https://THISPART.surecloud.io"
		},
		{
			"key": "apiKey",
			"value": "exampleOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyZXN0LWFwaSIsInJvbGVzIjpbIlJPTEVfUkVTVF9BUElfUkVBRCJdLCJ0ZW5hbnRfaWQiOiI3NmJhMzYwZS05NDUwLTQ5YWItYWQwYy03ZGYwMDVjNzgzYzQiLCJpc3MiOiJyZXN0LWFwaS5zdXJlY2xvdWQuaW8iLCJpYXQiOjE3NTgyMDUzNzIsInN1YiI6IjQxODRhZWY4LTEwOGYtNGYxNS1hNWFmLThlZDE4ZGU0ZDM5MCJ9.wYXMGYGdszTI0Q7KsgygksBdvmAfPKbjBtxQYhpa6dBhCA1Biu5z70JaZS1c6gQSgEbMbufZIuo6BeHPcMM8Tw",
			"description": "Your secure authentication token provided by SureCloud support"
		},
		{
			"key": "baseUrl",
			"value": "https://{{tenant}}.uk.surecloud.io/api/rest/v1",
			"description": "The full path to the API (do not change this)"
		}
	]
}