1Risk API

Download OpenAPI specification:Download

Introduction

This C1Risk documentation helps customer integrate with the 1Risk Platform. If you have any questions, please contact devops@c1risk.com.

Authentication

To authenticate against 1Risk API you will need to provide an API key in the request headers.

Security Scheme Type API Key
Header parameter name X-Auth-Key

Important: Your API key is a secret. Never share your API keys. Keep them safe and secure. Use your API key to make requests from the server side. To authenticate, provide your API key in the request header.

Generating an API Key

You must be an active user in the 1Risk Platform. Your user role will determine the level of record permission. To generate an API key login as the user and follow the steps below.

  • Use the 1Risk Platform in the top navigation bar, click user User Profile. This will take you to the user detail page.
  • In the user detail page click on the subtab API.
  • Click on the action menu, and select + New Key.

gen_api_key_3

gen_api_key_3

Locate your record referenceId

The referenceId is UUID that identifies a record. All records have a referenceId and it should be used wherever {referenceId} is asked for.

gen_api_key_3

Instructions

Asset

The 1Risk Platform provides customers the ability to manage asset types and custom fields to track metadata for each asset. See details for asset type configuration https://c1risk.freshdesk.com/support/solutions/articles/73000523244-asset-type-setup.

It is important to track and understand your asset type fields to generate asset records. You must pass validation checks for all required fields to create an asset record.

Retrieve Asset Type

To create an Asset we first need to get the asset type fields required to successfully create the asset.

The fields you need in your request body to create an asset are found in allFields. All fields marked with key "fieldRequired": true must be included in your request body responses: [...].

Example response:

GET /resource/asset-type/{referenceId}
{
    "id": 5,
    "internalId": "AST-000005",
    "referenceId": "a36d876f-55c4-4ffb-b017-270607bf5e82",
    "name": "Vendors",
    "iconName": "dice-d6",
    "assetTypeTemplate": {
      "name": "Vendors",
      "status": "ACTIVE",
      "iconName": "dice-d6",
      "sections": [...]
    },
    "template": [...],
    "allFields": [
      {
        "fieldLabel": "Name",
        "fieldType": "TEXT",
        "displaySize": "SPLIT",
        "fieldRequired": true,
        "columnDisplay": true,
        "columnOrder": 0,
        "fieldName": "name"
      },
      {
        "fieldLabel": "Risk Tier",
        "fieldType": "DROPDOWN",
        "displaySize": "SPLIT",
        "fieldRequired": false,
        "columnDisplay": true,
        "columnOrder": 0,
        "fieldOptions": [
          "Not Rated",
          "Tier 1",
          "Tier 2",
          "Tier 3"
        ],
        "fieldName": "tier"
      },
      {
        "fieldLabel": "Description",
        "fieldType": "TEXTAREA",
        "displaySize": "FULL",
        "fieldRequired": false,
        "columnDisplay": false,
        "columnOrder": 0,
        "fieldName": "description"
      },
      {
        "fieldLabel": "Business Service",
        "fieldType": "TEXT",
        "displaySize": "SPLIT",
        "fieldRequired": false,
        "columnDisplay": false,
        "columnOrder": 0,
        "fieldName": "businessServices"
      },
      {
        "fieldLabel": "Domain",
        "fieldType": "TEXT",
        "displaySize": "SPLIT",
        "fieldRequired": false,
        "columnDisplay": false,
        "columnOrder": 0,
        "fieldName": "domains"
      },
      {
        "fieldLabel": "API Data 1",
        "fieldType": "TEXTAREA",
        "displaySize": "FULL",
        "fieldRequired": false,
        "columnDisplay": false,
        "columnOrder": 0,
        "fieldName": "apiData1"
      }
    ],
    "status": "Active",
    "fieldCount": 6,
    "ownerName": "Lily Yeoh",
    "createdBy": "Lily Yeoh",
    "createdAt": "2022-04-27T08:18:35",
    "updatedBy": "Lily Yeoh",
    "updatedAt": "2022-04-27T08:18:35",
    "totalRecord": 0,
    "usedBy": 0
  }

Retrieve Contact Id

In order to create an asset record, we need to know who we are assigning the asset record to. We support 1 primary contact and multiple additional contacts.

Asset Contact Rules

  • Must provide 1 primary contact.
  • Additional contacts are optional.
  • Primary contact can not be an additional contact.

Important Contact support@c1risk.com to obtain contact id for your integration job.

All contacts should be added to a contacts object array. Each contact object requires the id and type.

Asset Supported Contact Types: PRIMIARY, ADDITIONAL

"contacts": [
      {
          "id": 1,
          "type": "PRIMARY"
      },
]

Note: id can be found in the Enterprise > Directory > Table View : ID

Create Asset

Add the responses

Iterate over asset type response allFields and fill out required and/or any additional fields. Insert into an object array responses:[...].

"responses": [
  {
      "fieldName": "name",
      "fieldValue": "Example Company"
  },
  {
      "fieldName": "tier",
      "fieldValue": "Tier 2"
  },
  {
      "fieldName": "description",
      "fieldValue": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>"
  },
  {
      "fieldName": "domains",
      "fieldValue": "https://example.com/"
  },
  {
      "fieldName": "apiData1",
      "fieldValue": "<p>Some API Data.</p>"
  }
]

Add the contacts

"contacts": [
      {
          "id": 1,
          "type": "PRIMARY"
      },
      {
          "id": 2,
          "type": "ADDITIONAL"
      },
      {
          "id": 3,
          "type": "ADDITIONAL"
      }
],
...

Create Asset

Now that we have the responses[...] and contacts[...] we can proceed to create the asset.

Example request:

POST /resource/api/asset/
{
    "id": 0,
    "name": "Example Company",
    "active": true,
    "assetTypeId": 5,
    "contacts": [
        {
            "id": "1",
            "type": "PRIMARY"
        },
        {
            "id": "2",
            "type": "ADDITIONAL"
        },
        {
            "id": "3",
            "type": "ADDITIONAL"
        }
    ],
    "relatedAssetIds": [],
    "responses": [
        {
            "fieldName": "name",
            "fieldValue": "Example Company"
        },
        {
            "fieldName": "tier",
            "fieldValue": "Tier 2"
        },
        {
            "fieldName": "description",
            "fieldValue": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>"
        },
        {
            "fieldName": "domains",
            "fieldValue": "https://example.com/"
        },
        {
            "fieldName": "apiData1",
            "fieldValue": "<p>Some API Data.</p>"
        }
    ]
}

Note: assetTypeId can be found in the Administration > Asset Type > Table View : ID

Update Asset

To update an asset follow the same steps done when creating an asset. This time include the id of the record you want to update.

PUT /resource/api/asset/

Example request:

{
    "id": 6,
    "name": "Example Company B",
    "active": true,
    "assetTypeId": 5,
    "contacts": [
        {
            "id": "1",
            "type": "PRIMARY"
        },
        {
            "id": "2",
            "type": "ADDITIONAL"
        },
        {
            "id": "3",
            "type": "ADDITIONAL"
        }
    ],
    "relatedAssetIds": [],
    "responses": [
        {
            "fieldName": "name",
            "fieldValue": "Example Company B"
        },
        {
            "fieldName": "tier",
            "fieldValue": "Tier 3"
        },
        {
            "fieldName": "description",
            "fieldValue": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>"
        },
        {
            "fieldName": "domains",
            "fieldValue": "https://example.com/"
        },
        {
            "fieldName": "apiData1",
            "fieldValue": "<p>Some API Data.</p>"
        }
    ]
}

Note: id can be found in the Enterprise > Asset > Select Asset Type > Table View : ID

Note: assetTypeId can be found in the Administration > Asset Type > Table View : ID

Retrieve Asset

To get an asset you need to have the referenceId of the record.

GET /resource/api/asset/{referenceId}

Example request:

GET /api/asset/4447ed41-27db-43a1-8f5d-5bffcae4c0b6

Example response:

    {
    "id": 6,
    "internalId": "AID-000006",
    "referenceId": "f081df30-f765-40c4-a005-3bd8283bf8be",
    "ownerName": "Lily Yeoh",
    "createdBy": "Lily Yeoh",
    "createdAt": "2022-04-27T08:39:01",
    "updatedBy": "Lily Yeoh",
    "updatedAt": "2022-04-27T08:39:01",
    "templateSections": [
        {
            "sectionName": "Information",
            "displaySize": "FULL",
            "fields": [
                {
                    "fieldLabel": "Name",
                    "fieldType": "TEXT",
                    "displaySize": "SPLIT",
                    "fieldRequired": true,
                    "columnDisplay": true,
                    "columnOrder": 0,
                    "fieldName": "name"
                },
                {
                    "fieldLabel": "Risk Tier",
                    "fieldType": "DROPDOWN",
                    "displaySize": "SPLIT",
                    "fieldRequired": false,
                    "columnDisplay": true,
                    "columnOrder": 0,
                    "fieldOptions": [
                        "Not Rated",
                        "Tier 1",
                        "Tier 2",
                        "Tier 3"
                    ],
                    "fieldName": "tier"
                },
                {
                    "fieldLabel": "Description",
                    "fieldType": "TEXTAREA",
                    "displaySize": "FULL",
                    "fieldRequired": false,
                    "columnDisplay": false,
                    "columnOrder": 0,
                    "fieldName": "description"
                },
                {
                    "fieldLabel": "Business Service",
                    "fieldType": "TEXT",
                    "displaySize": "SPLIT",
                    "fieldRequired": false,
                    "columnDisplay": false,
                    "columnOrder": 0,
                    "fieldName": "businessServices"
                },
                {
                    "fieldLabel": "Domain",
                    "fieldType": "TEXT",
                    "displaySize": "SPLIT",
                    "fieldRequired": false,
                    "columnDisplay": false,
                    "columnOrder": 0,
                    "fieldName": "domains"
                }
            ]
        },
        {
            "sectionName": "API",
            "displaySize": "FULL",
            "fields": [
                {
                    "fieldLabel": "API Data 1",
                    "fieldType": "TEXTAREA",
                    "displaySize": "FULL",
                    "fieldRequired": false,
                    "columnDisplay": false,
                    "columnOrder": 0,
                    "fieldName": "apiData1"
                }
            ]
        }
    ],
    "templateResponses": [
        {
            "fieldName": "name",
            "fieldValue": "Example Company",
            "assetLookupResponses": []
        },
        {
            "fieldName": "tier",
            "fieldValue": "Tier 2",
            "assetLookupResponses": []
        },
        {
            "fieldName": "description",
            "fieldValue": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
            "assetLookupResponses": []
        },
        {
            "fieldName": "domains",
            "fieldValue": "https://example.com/",
            "assetLookupResponses": []
        },
        {
            "fieldName": "apiData1",
            "fieldValue": "<p>Some API Data.</p>",
            "assetLookupResponses": []
        },
        {
            "fieldName": "businessServices",
            "assetLookupResponses": []
        }
    ],
    "linkedAssets": 0,
    "level": 0,
    "totalFieldCount": 6,
    "assetTypeId": 5,
    "assetType": "Vendors",
    "assetTypeIconName": "dice-d6",
    "assetTypeUrlName": "vendors",
    "riskScore": 0.0,
    "impactRating": "Low",
    "name": "Example Company",
    "status": "Active",
    "contacts": [
        {
            "id": 1,
            "referenceId": "1e5110c7-3757-4060-9c3c-850e6aad289c",
            "firstName": "Lily Yeoh",
            "lastName": "Lily",
            "fullName": "Lily Yeoh",
            "type": "PRIMARY",
            "typeLabel": "Primary"
        }
    ],
    "upstreamAssets": [],
    "relatedAssets": [],
    "averageControlStrength": 0.0,
    "relatedAssessmentsCount": 0,
    "relatedInternalControlsCount": 0,
    "relatedFindingsCount": 0,
    "relatedRiskRegistersCount": 0,
    "impactScore": 0.0,
    "customerId": 148652,
    "primaryContact": "Lily Yeoh",
    "editable": true,
    "tier": "Tier 2",
    "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
    "domains": "https://example.com/",
    "apiData1": "<p>Some API Data.</p>"
}

Asset Upload Files

curl --location --request POST 'https://appstaging.1risk.io/resource/api/asset/18e9ce29-fb32-4afb-86aa-6c67d51cd032/attachments' \
--header 'X-Auth-Key: <API-KEY>' \
--form 'files=@"/image.png"'

An assessment is a blank.

Create Assessment

To create an Assessment you need the following:

  • Assessment Template Reference Id
  • Asset Reference Id
POST /resource/v2/api/assessment/
curl --location --request POST 'https://appstaging.1risk.io/resource/v2/api/assessment/' \
--header 'X-Auth-Key: <API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "assessmentTemplateReferenceId": "32i1kifc-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "assetReferenceId": "62h4ebfn-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "contacts": [
        {
            "referenceId": "92b3rtfl-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "type": "PRIMARY"
        }
    ],
    "dueDate": "2022-06-11T12:00:00",
    "name": "Example Assessment"
}'
{
  "name": "Example Assessment",
  "assessmentTemplateReferenceId": "32i1kifc-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "assetReferenceId": "62h4ebfn-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "contacts": [
      {
          "referenceId": "92b3rtfl-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "type": "PRIMARY"
      }
  ],
  "dueDate": "2022-06-11T12:00:00",
}

Assessment Status

An Assessment has the following statuses:

  • OPEN
  • REOPEN
  • EXPIRED
  • SUBMITTED
  • CLOSED

Important Assessment questions can only be saved when an assessment status is: OPEN, REOPEN, or EXPIRED.

Saving assessment answers will NOT change the Assessment status. To submit an assessment see Assessment Submit

Assessment Questions

To retrieve all assessment questions.

Important Questions response will change depending on the assessment template.

GET /resource/v2/api/assessment/{referenceId}/questions
[
  {
      "id": 4558,
      "internalId": "AQR-004558",
      "referenceId": "53390760-a14d-4c02-b933-731c54099e59",
      "ownerName": "1Risk",
      "createdBy": "1Risk",
      "createdAt": "2022-05-16T13:42:15",
      "updatedBy": "1Risk",
      "updatedAt": "2022-05-16T13:42:15",
      "assessmentReferenceId": "20109591-553f-486d-ab4d-cfe758513837",
      "assessmentInternalId": "ASR-000044",
      "assessmentTemplateInternalId": "TID-000001",
      "assessmentTemplateName": "All Question Type Template",
      "questionIdx": "1.5",
      "parentQuestionId": 4553,
      "questionText": "Tell us how you would rate us?",
      "sectionName": "A05 Information security policies",
      "questionType": "TEXTAREA",
      "contentSource": "Test Textarea Question",
      "required": true
  },
  {
      "id": 4553,
      "internalId": "AQR-004553",
      "referenceId": "b3d8c2b3-e6c2-4128-a884-47578c73405b",
      "ownerName": "1Risk",
      "createdBy": "1Risk",
      "createdAt": "2022-05-16T13:42:15",
      "updatedBy": "1Risk",
      "updatedAt": "2022-05-16T13:42:15",
      "assessmentReferenceId": "20109591-553f-486d-ab4d-cfe758513837",
      "assessmentInternalId": "ASR-000044",
      "assessmentTemplateInternalId": "TID-000001",
      "assessmentTemplateName": "All Question Type Template",
      "questionIdx": "1",
      "questionText": "Do you like birthdays?",
      "sectionName": "A05 Information security policies",
      "questionType": "LIST",
      "contentSource": "Test List Question",
      "helpText": "Please explain.",
      "required": true,
      "listValues": [
          {
              "label": "Yes",
              "value": "yesValue",
              "riskScore": 0,
              "commentRequired": false,
              "attachmentRequired": false,
              "displayChild": true,
              "createFinding": false
          },
          {
              "label": "No",
              "value": "noValue",
              "riskScore": 2,
              "commentRequired": false,
              "attachmentRequired": false,
              "displayChild": false,
              "createFinding": true
          },
          {
              "label": "Not Applicable",
              "value": "naValue",
              "riskScore": 0,
              "commentRequired": false,
              "attachmentRequired": false,
              "displayChild": false,
              "createFinding": false
          }
      ]
  },
  {
      "id": 4556,
      "internalId": "AQR-004556",
      "referenceId": "ec71038a-b127-4713-821e-80b2d35697ef",
      "ownerName": "1Risk",
      "createdBy": "1Risk",
      "createdAt": "2022-05-16T13:42:15",
      "updatedBy": "1Risk",
      "updatedAt": "2022-05-16T13:42:15",
      "assessmentReferenceId": "20109591-553f-486d-ab4d-cfe758513837",
      "assessmentInternalId": "ASR-000044",
      "assessmentTemplateInternalId": "TID-000001",
      "assessmentTemplateName": "All Question Type Template",
      "questionIdx": "1.3",
      "parentQuestionId": 4553,
      "questionText": "What is your birth date?",
      "sectionName": "A05 Information security policies",
      "questionType": "DATE",
      "contentSource": "Test Date Question",
      "required": true
  },
  {
      "id": 4557,
      "internalId": "AQR-004557",
      "referenceId": "898a435a-2e0f-4043-afda-2c2e6611792c",
      "ownerName": "1Risk",
      "createdBy": "1Risk",
      "createdAt": "2022-05-16T13:42:15",
      "updatedBy": "1Risk",
      "updatedAt": "2022-05-16T13:42:15",
      "assessmentReferenceId": "20109591-553f-486d-ab4d-cfe758513837",
      "assessmentInternalId": "ASR-000044",
      "assessmentTemplateInternalId": "TID-000001",
      "assessmentTemplateName": "All Question Type Template",
      "questionIdx": "1.4",
      "parentQuestionId": 4553,
      "questionText": "What is the price for the apple?",
      "sectionName": "A05 Information security policies",
      "questionType": "CURRENCY",
      "contentSource": "Test Currency Question",
      "required": true
  },
  {
      "id": 4554,
      "internalId": "AQR-004554",
      "referenceId": "0ecfd24d-5c8f-46dc-ba09-792599aa4699",
      "ownerName": "1Risk",
      "createdBy": "1Risk",
      "createdAt": "2022-05-16T13:42:15",
      "updatedBy": "1Risk",
      "updatedAt": "2022-05-16T13:42:15",
      "assessmentReferenceId": "20109591-553f-486d-ab4d-cfe758513837",
      "assessmentInternalId": "ASR-000044",
      "assessmentTemplateInternalId": "TID-000001",
      "assessmentTemplateName": "All Question Type Template",
      "questionIdx": "1.1",
      "parentQuestionId": 4553,
      "questionText": "What is your favorite color?",
      "sectionName": "A05 Information security policies",
      "questionType": "CHECKBOX",
      "contentSource": "Test Checkbox Question",
      "helpText": "Please explain.",
      "required": true,
      "listValues": [
          {
              "label": "Red",
              "value": "redValue",
              "riskScore": 1,
              "commentRequired": false,
              "attachmentRequired": false,
              "displayChild": false,
              "createFinding": false
          },
          {
              "label": "Yellow",
              "value": "yellowValue",
              "riskScore": 1,
              "commentRequired": false,
              "attachmentRequired": false,
              "displayChild": false,
              "createFinding": true
          },
          {
              "label": "Black",
              "value": "blackValue",
              "riskScore": 1,
              "commentRequired": false,
              "attachmentRequired": false,
              "displayChild": false,
              "createFinding": false
          }
      ]
  },
  {
      "id": 4555,
      "internalId": "AQR-004555",
      "referenceId": "fb8c2c84-32fa-4d3e-9545-868358fbebc1",
      "ownerName": "1Risk",
      "createdBy": "1Risk",
      "createdAt": "2022-05-16T13:42:15",
      "updatedBy": "1Risk",
      "updatedAt": "2022-05-16T13:42:15",
      "assessmentReferenceId": "20109591-553f-486d-ab4d-cfe758513837",
      "assessmentInternalId": "ASR-000044",
      "assessmentTemplateInternalId": "TID-000001",
      "assessmentTemplateName": "All Question Type Template",
      "questionIdx": "1.2",
      "parentQuestionId": 4553,
      "questionText": "How old are you?",
      "sectionName": "A05 Information security policies",
      "questionType": "NUMBER",
      "contentSource": "Test Number Question",
      "required": true
  }
]

Question Types

  • LIST - A single select dropdown value
  • CHECKBOX - A multi select value
  • TEXTAREA - Allows for formatted HTML text. 2000 characters max
  • NUMBER - Whole number (e.g. 1, 100, 1000)
  • DATE - UTC Timestamp (e.g. 2022-05-26T07:00:00.000Z)
  • CURRENCY - USD (e.g. 1, 100.00, 1000.10)

LIST

{
  "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "answerValue": ["a"]
}

CHECKBOX

{
  "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "answerValue": [
    "a",
    "b"
  ]
}

TEXTAREA

{
  "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "answerValue": "<p>test</p>"
}

NUMBER

{
  "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "answerValue": 23
}

DATE

{
  "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "answerValue": "2022-05-26T07:00:00.000Z"
}

CURRENCY

{
  "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "answerValue": 10000.10
}

Assessment Answer

To submit answers the Assessment status needs to be in the following:

  • OPEN
  • REOPENED
  • EXPIRED

The answerValue will depend on the question type.

For LIST and CHECKBOX type questions you can retrieve the answerValue from listValues -> value:

GET /resource/v2/api/assessment/{referenceId}/questions
{
  ...
  "referenceId": "288b9dff-6238-4330-8310-56e72f8dce91",
  "listValues": [
      {
          "label": "a. A government, government agency or entity, government-owned or controlled entity, public international organization, or its officials, employees, or representatives",
          "value": "a",
          "riskScore": 0,
          "commentRequired": false,
          "attachmentRequired": false,
          "displayChild": false,
      },
      {
          "label": "b. A political party, organization (including PAC and other committees), a campaign, a candidate, or its officials, employees, or representatives",
          "value": "b",
          "riskScore": 0,
          "commentRequired": false,
          "attachmentRequired": false,
          "displayChild": false,
      },
      {
          "label": "c. Trade organization, member organization, industry organization or similar entity",
          "value": "c",
          "riskScore": 0,
          "commentRequired": false,
          "attachmentRequired": false,
          "displayChild": false,
      },
      {
          "label": "d. None of the above",
          "value": "d",
          "riskScore": 0,
          "commentRequired": false,
          "attachmentRequired": false,
          "displayChild": false,
      }
  ]
}

Example Request

{
  "assessmentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "submit": 1,
  "completion": 100,
  "silent": false,
  "answers": [
      {
          "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "answerValue": "[yesValue]"
      },
      {
          "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "answerValue": "[redValue, yellowValue]"
      },
      {
        "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "answerValue": "<p>A textarea value!</p>"
      },
      {
          "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "answerValue": 2
      },
      {
          "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "answerValue": "2022-05-30T06:59:59.000Z"
      },
      {
          "assessmentQuestionReferenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "answerValue": 232.99
      }
  ]
}

Assessment Upload Files

Uploading files to Assessments is very similar to Asset.

curl --location --request POST 'https://appstaging.1risk.io/resource/api/assessment/{referenceId}/attachments' \
--header 'X-Auth-Key: <API-KEY>' \
--form 'files=@"/image.png"'

Assessment Question Upload Files

Uploading files to an Assessment Question is again very similar to uploading files to Asset and Assessment.

curl --location --request POST 'https://appstaging.1risk.io/resource/v2/api/assessment/question/{referenceId}/attachments' \
--header 'X-Auth-Key: <API-KEY>' \
--form 'files=@"/image.png"'

Assessment Submit

You can submit an assessment after all questions have been answered. To answer questions see Assessment Answer

PUT /resource/v2/api/assessment/{referenceId}/submit

Create Finding

To create finding you must send the required fields [name, description, source, priority, dueDate, contacts (mandatory to have all types, except ADDITIONAL), related[sourceEntity]ReferenceIds (Just one referenceId)].

POST /resource/api/finding
{
  "id": 0,
  "name": "Name of finding (required)",
  "description": "<p>Write some description. It accepts formatting. <strong>Bold</strong>, <em>italic</em>, etc... (required)</p>",
  "recommendation": "<p>Write some recommendations. It accepts formatting. <strong>Bold</strong>, <em>italic</em>, etc...</p>",
  "dueDate": "2024-12-26T00:59:59",
  "source": "POLICY",
  "priority": "LOW",
  "contacts": [
      {
          "id": "60",
          "type": "PRIMARY"
      },
      {
          "id": "70",
          "type": "ADDITIONAL"
      },
      {
          "id": "71",
          "type": "ADDITIONAL"
      },
      {
          "id": "60",
          "type": "REPORTER"
      },
      {
          "id": "60",
          "type": "RISK_MANAGER"
      }
  ],
  "tags": [
      {
          "tag": "tags1",
          "type": "CUSTOM"
      },
      {
          "tag": "tags2",
          "type": "CUSTOM"
      }
  ],
  "attachments": [],
  "relatedPolicyReferenceIds": [
      "01d6b3c4-5ae2-49f2-93ca-f72ce1d4x3dd"
  ],
  "relatedControlLibraryReferenceIds": [
      "584a0116-4716-429b-95bf-25a3cd4357e7",
      "aa5a6ff3-1dab-479e-919c-cb2590f5b90f"
  ]
}

Retrieve Finding

To get retrieve a Finding you need to have the referenceId of the record.

GET /resource/v2/api/finding/{referenceId}
{
  "internalId": "FID-000056",
  "referenceId": "37437f7e-8e17-44e8-9beb-0ffad7fe7181",
  "ownerName": "Lily Yeoh",
  "createdBy": "Lily Yeoh",
  "createdAt": "2022-05-08T11:30:57",
  "updatedBy": "Vendor User",
  "updatedAt": "2022-05-08T11:36:23",
  "name": "test vendor",
  "description": "<p>test</p>",
  "recommendation": "",
  "dueDate": "2022-06-03T05:00:00",
  "sourceType": "INTERNAL_CONTROL",
  "daysOpen": 0,
  "dueDateDays": 0,
  "closedName": "Vendor User",
  "closedAt": "2022-05-08T11:36:21",
  "priority": "LOW",
  "status": "CLOSED",
  "contacts": [
      {
          "referenceId": "b15c2934-c69a-46ad-8d9f-f6606c5cd3e8",
          "firstName": "Vendor User",
          "lastName": "Vendor",
          "fullName": "Vendor User",
          "type": "PRIMARY"
      },
      {
          "referenceId": "b5194f17-551e-49a9-9e6d-fa5d1bc7a813",
          "firstName": "Lily Yeoh",
          "lastName": "Lily",
          "fullName": "Lily Yeoh",
          "type": "REPORTER"
      },
      {
          "referenceId": "f164ecd2-5be6-450a-b22e-7892a017ac14",
          "firstName": "Lily Yeoh",
          "lastName": "Lily",
          "fullName": "Lily Yeoh",
          "type": "RISK_MANAGER"
      }
  ],
  "ownerEmail": "chris@c1risk.com",
  "relatedInternalControlsCount": 1,
  "relatedAssetsCount": 0,
  "relatedRiskRegistersCount": 0,
  "relatedPoliciesCount": 0,
  "latestRiskMitigation": {
      "referenceId": "61f4ffa2-bc66-4b0a-9d6d-a4bef9886a0c",
      "actionPlans": "<p>test</p>",
      "status": "RESOLVED",
      "expectedCompletionAt": "2022-05-11T05:00:00"
  }
}

Exporting to CSV

Export to CSV requires a parameter for your local timezone because the system converts data from UTC to your local export timezone. The local timezone is stored in the timezone={timezone_value} in base64encode format. We recommend using the tool to convert to base64: https://www.base64encode.org/.

image

To get a list of the standard time zone input to encode, use this guide: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

image

Sample Endpoint

If Timezone is America/Los_Angeles, then endpoint is: https://api.1risk.io/resource/api/{Path}/csv?timezone=QW1lcmljYS9Mb3NfQW5nZWxlcw%3D%3D

Entity Name Path
Incidents incident-management/incidents
Findings issue-management/findings
Risk Register risk-management/risk-register
Assessments risk-management/assessment
Internal Controls compliance-management/internal-controls

For all the entities the response is a text-plain body with CSV formatting. In the CSV the rows are delimited by line. Line 1 would be the first row, and line 2 the second. The columns are comma separated.

E.g.

  1. ID, Name, Status, “Created Date”, Owner
  2. 1234, “The name”, Open, 2023-10-05T24:59:59, “Owner Name”

If the field contains spaces or takes multiple rows it will be delimited by double quotes. E.g.

  1. ID, Name, Description, Status, “Created Date”, Owner
  2. 1234, “The name”, “This is a description example. Here I break the line.
  3. Then the line continues here. If I break the line again
  4. it will keep adding more lines to the document until the description ends and then put a double quote at the end. If there are no line breakers, it will put everything in one really long line like this one.”, Open, 2023-10-05T24:59:59, “Owner Name”

Incidents formatting

The endpoint explanation is here.

Field Name Format Notes
Incident ID String Max Char (45)
Name String Max Char (255)
Description String Max Char (65,535)
Source String Max Char (45)
Type String Max Char (255)
Incident Date String Formatted as %Y-%m-%dT%H:%M:%S
Actors String Max Char (255)*(Number of actors)
Due Date String Formatted as %Y-%m-%dT%H:%M:%S
Severity String Max Char (45)
Days Open Integer From -2147483648 to 2147483647
Priority String Max Char (45)
Total Asset Integer From -2147483648 to 2147483647
Total Risk Register Integer From -2147483648 to 2147483647
Total Internal Control Integer From -2147483648 to 2147483647
Customer Impact Integer From -2147483648 to 2147483647
Operational Impact Integer From -2147483648 to 2147483647
Financial Impact Integer From -2147483648 to 2147483647
Legal Impact Integer From -2147483648 to 2147483647
Insurance Impact Integer From -2147483648 to 2147483647
Breach Notification Impact Integer From -2147483648 to 2147483647
Total Users Impact Integer From -2147483648 to 2147483647
Total Loss Amount Integer From -2147483648 to 2147483647
Investigation Notes String Max Char (65,535)
Closed Code String Max Char (45)
Resolution Effectiveness String Boolean (Yes/No)
Root Cause Analysis String Max Char (65,535)
Close Notes String Max Char (65,535)
Resolution Closed Date String Formatted as %Y-%m-%dT%H:%M:%S
Resolution Closed By String Max Char (255)
Reporter String Max Char (255)
Incident Manager String Max Char (255)
Additional Contacts String Max Char (255)*(Number of records)
Status String Max Char (45)
Owner String Max Char (255)
Created By String Max Char (255)
Created Date String Formatted as %Y-%m-%dT%H:%M:%S
Modified By String Max Char (255)
Modified Date String Formatted as %Y-%m-%dT%H:%M:%S

Findings formatting

The endpoint explanation is here.

Field Name Format Notes
Finding ID String Max Char (45)
Name String Max Char (255)
Description String Max Char (65,535)
Source String Max Char (45)
Priority String Max Char (45)
Total Asset Integer From -2147483648 to 2147483647
Recommendation String Max Char (65,535)
Due Date Date Formatted as %Y-%m-%dT%H:%M:%S
Days Opened Integer From -2147483648 to 2147483647
RM Status String Max Char (45)
Risk Treatment String Max Char (45)
Root Cause Analysis String Max Char (65,535)
Action Plans String Max Char (65,535)
Expected Completion Date Date Formatted as %Y-%m-%dT%H:%M:%S
RM ID String Max Char (45)
Risk Manager String Max Char (255)
Primary Contact String Max Char (255)
Modified Date String Formatted as %Y-%m-%dT%H:%M:%S

Risk Register formatting

The endpoint explanation is here.

Field Name Format Notes
Risk ID String Max Char (45)
Name String Max Char (255)
Description String Max Char (65,535)
Risk Groups String Max Char (80) * (Number of records)
Assets String Max Char (500) * (Number of records)
Risk Treatment String Max Char (45)
Internal Controls String Max Char (548) * (Number of records)
Control Strength Bigint Max Char (264-1)
Probability Double Max Char (4) (One decimal place)
Inherent Risk Double Max Char (4) (One decimal place)
Residual Risk Double Max Char (4) (One decimal place)
Primary Contact String Max Char (255)
Last Modified At String Formatted as %Y-%m-%dT%H:%M:%S

Assessment formatting

The endpoint explanation is here.

Field Name Format Notes
Assessment ID String Max Char (45)
Name String Max Char (255)
Asset String Max Char (255)
Assessment Template String Max Char (255)
Total Questions Integer From -2147483648 to 2147483647
Due Date String Formatted as %Y-%m-%dT%H:%M:%S
Due Days Integer From -2147483648 to 2147483647
Progress Bigint Max Char (264-1)
Answer Score Double Max Char (4) (One decimal place)
Risk Score Double Max Char (4) (Two decimal place)
Risk Rating String Max Char (45)
Approval Required String Boolean (Yes/No)
Reviewer String Max Char (255)
Assessment Review Notes Longtext Max Char (4,294,967,295)
Assessment Review By String Max Char (45)
Assessment Review Date String Formatted as %Y-%m-%dT%H:%M:%S
Status String Max Char (45)
Created By String Max Char (255)
Created Date String Formatted as %Y-%m-%dT%H:%M:%S
Modified By String Max Char (255)
Modified Date String Formatted as %Y-%m-%dT%H:%M:%S

Internal Control formatting

The endpoint explanation is here.

Field Name Format Notes
ID String Max Char (45)
Name String Max Char (255)
Description Longtext Max Char (4,294,967,295)
Source String Max Char (255)
Type String Max Char (45)
Control Frequency String Max Char (45)
Control Strength Bigint Max Char (264-1)
Nature of Control String Max Char (45) * (Number of records)
Key Control String Boolean (Yes/No)
Risk Register String Max Char (545) * (Number of records)
Assets String Max Char (545) * (Number of records)
Primary Contact String Max Char (45)
New Finding Integer From -2147483648 to 2147483647
Open Finding Integer From -2147483648 to 2147483647
Re-Open Finding Integer From -2147483648 to 2147483647
Expired Finding Integer From -2147483648 to 2147483647
Closed Finding Integer From -2147483648 to 2147483647
Last Modified At String Formatted as %Y-%m-%dT%H:%M:%S
Linked Assets Integer From -2147483648 to 2147483647

Asset

Asset

Create Asset by Request

Responses

Response samples

Content type
application/json
{ }

Update Asset by Request

Responses

Response samples

Content type
application/json
{ }

Get Asset by referenceId

path Parameters
referenceId
required
string

referenceId

Responses

Response samples

Content type
application/json
{
  • "additionalAssets": [
    ],
  • "assetType": "string",
  • "assetTypeIconName": "string",
  • "assetTypeId": 0,
  • "assetTypeUrlName": "string",
  • "averageControlStrength": 0.1,
  • "contacts": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "customerId": 0,
  • "cyberRiskRating": 0.1,
  • "editable": true,
  • "id": 0,
  • "impactRating": "string",
  • "impactScore": 0.1,
  • "internalId": "string",
  • "level": 0,
  • "linkedAssets": 0,
  • "name": "string",
  • "overallRisk": 0.1,
  • "overallRiskTier": {
    },
  • "ownerName": "string",
  • "primaryContact": "string",
  • "referenceId": "string",
  • "relatedAssessmentsCount": 0,
  • "relatedAssets": [
    ],
  • "relatedFindingsCount": 0,
  • "relatedInternalControlsCount": 0,
  • "relatedRiskRegistersCount": 0,
  • "riskScore": 0.1,
  • "status": "string",
  • "templateResponses": [
    ],
  • "templateSections": [
    ],
  • "totalFieldCount": 0,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "upstreamAssets": [
    ]
}

Upload attachments for Asset

path Parameters
referenceId
required
string

referenceId

Request Body schema: multipart/form-data
files
Array of strings <binary> [ items <binary > ]

Files being uploaded for assest.

Responses

Response samples

Content type
application/json
{ }

Asset Type

AssetType

Get Asset Type by referenceId

path Parameters
referenceId
required
string

referenceId

Responses

Response samples

Content type
application/json
{ }

Assessment

Create an Assessment

Request Body schema: application/json
required

request

assessmentTemplateReferenceId
required
string
assetReferenceId
required
string
required
Array of objects (ContactRequest)
dueDate
required
string <date>
name
required
string
referenceId
string

Required on PUT request

Responses

Request samples

Content type
application/json
{
  • "assessmentTemplateReferenceId": "string",
  • "assetReferenceId": "string",
  • "contacts": [
    ],
  • "dueDate": "2019-08-24",
  • "name": "string",
  • "referenceId": "string"
}

Response samples

Content type
application/json
{ }

Update Assessment by Request

Request Body schema: application/json
required

Referenceids can be obtained from the URL link.

assessmentTemplateReferenceId
required
string
assetReferenceId
required
string
required
Array of objects (ContactRequest)
dueDate
required
string <date>
name
required
string
referenceId
string

Required on PUT request

Responses

Request samples

Content type
application/json
{
  • "assessmentTemplateReferenceId": "string",
  • "assetReferenceId": "string",
  • "contacts": [
    ],
  • "dueDate": "2019-08-24",
  • "name": "string",
  • "referenceId": "string"
}

Response samples

Content type
application/json
{ }

Retrieve list of Assessment Questions

path Parameters
referenceId
required
string

referenceId

Responses

Response samples

Content type
application/json
{ }

Submit Assessment

path Parameters
referenceId
required
string

referenceId

Responses

Response samples

Content type
application/json
{ }

Upload attachments for Assessment

path Parameters
referenceId
required
string

referenceId

Request Body schema: application/x-www-form-urlencoded
files
Array of strings <binary> [ items <binary > ]

Files being uploaded for assessment.

Responses

Response samples

Content type
application/json
{ }

Upload attachments Assessment Question

path Parameters
referenceId
required
string

referenceId

Request Body schema: application/x-www-form-urlencoded
files
Array of strings <binary> [ items <binary > ]

Files being uploaded for assessment.

Responses

Response samples

Content type
application/json
{ }

Create Assessment Answers

Request Body schema: application/json
required

request

Array of objects (AssessmentAnswerRequestItem)
assessmentReferenceId
string
completion
integer <int64>
submit
boolean

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ],
  • "assessmentReferenceId": "string",
  • "completion": 0,
  • "submit": true
}

Response samples

Content type
application/json
{ }

Exporting Assessment in CSV

Export to CSV requires a parameter for your local timezone because the system converts data from UTC to your local export timezone. The local timezone is stored in the timezone={timezone_value} in base64encode format. We recommend using the tool to convert to base64: https://www.base64encode.org/.

query Parameters
timezone
required
string

timezone (in base64)

Responses

Evidence

Create DRI from evidence

Request Body schema: application/json
Array
integer

Evidence Id

Responses

Request samples

Content type
application/json
[
  • 0
]

Document Request

Get a list of Document Requests

path Parameters
filters
string

filter json encoded in base64

page
required
integer

page number (starts in 0)

pageSize
required
integer

number of records in a page

columnName
required
string

column to sort by

columnDirection
required
string

ASC or DESC

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "pageSize": 0,
  • "pages": 0,
  • "totalRecords": 0,
  • "filterRefId": "string",
  • "items": [
    ]
}

Submit document request response

Request Body schema: application/json
documentRequestId
integer
comments
string
documentUrl
string

Required if documentType is URL

submit
boolean
haveEvidence
boolean
documentType
string
Enum: "FILE" "URL"
documentTypeEnum
string
Enum: "FILE" "URL"
attestation
boolean
editable
boolean
submitForApproval
boolean
Array of objects

Responses

Request samples

Content type
application/json
{
  • "documentRequestId": 0,
  • "comments": "string",
  • "documentUrl": "string",
  • "submit": true,
  • "haveEvidence": true,
  • "documentType": "FILE",
  • "documentTypeEnum": "FILE",
  • "attestation": true,
  • "editable": true,
  • "submitForApproval": true,
  • "attachments": [
    ]
}

Finding

Create a Finding

Request Body schema: application/json
name
string

Required field

description
string

Required field

recommendation
string

long text

dueDate
string <date-time>

Required field

source
string
Enum: "ASSESSMENT" "ASSET" "POLICY" "CONTROL_LIBRARY" "DOCUMENT_REQUEST" "INTERNAL_CONTROL" "RISK_REGISTER" "ASSESSMENT_CAMPAIGN" "INTERNAL_AUDIT" "EXTERNAL_AUDIT" "TEST_RESULT" "INCIDENT" "NESSUS_ASSET" "NESSUS_VULNERABILITY" "RISK_GROUP" "AUDIT" "AUDIT_PROGRAM" "SELF_IDENTIFIED"

Required field

priority
string
Enum: "LOW" "MEDIUM" "HIGH"

Required field

Array of objects

Required field (only ADDTIONAL is optional)

Array of objects
attachments
Array of strings <binary> [ items <binary > ]
related[SourceEntity]ReferenceIds
Array of strings

Required field (Only one item). Change [SourceEntity] for the choosen source in CamelCase

related[Entity]ReferenceIds
Array of strings

Change [Entity] for the entity name in CamelCase

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "recommendation": "string",
  • "dueDate": "2019-08-24T14:15:22Z",
  • "source": "ASSESSMENT",
  • "priority": "LOW",
  • "contacts": [
    ],
  • "tags": [
    ],
  • "attachments": [
    ],
  • "related[SourceEntity]ReferenceIds": [
    ],
  • "related[Entity]ReferenceIds": [
    ]
}

Response samples

Content type
application/json
"string"

Update a Finding

Request Body schema: application/json
id
integer

Required field

name
string

Required field

description
string

Long text. Required field

recommendation
string

Long text

dueDate
string <date-time>

End of hour (yyyy-mm-ddThh:59:59). Required field

source
string
Enum: "ASSESSMENT" "ASSET" "POLICY" "CONTROL_LIBRARY" "DOCUMENT_REQUEST" "INTERNAL_CONTROL" "RISK_REGISTER" "ASSESSMENT_CAMPAIGN" "INTERNAL_AUDIT" "EXTERNAL_AUDIT" "TEST_RESULT" "INCIDENT" "NESSUS_ASSET" "NESSUS_VULNERABILITY" "RISK_GROUP" "AUDIT" "AUDIT_PROGRAM" "SELF_IDENTIFIED"

Required field

priority
string
Enum: "LOW" "MEDIUM" "HIGH"

Required field

Array of objects

Required field

Array of objects
attachments
Array of strings <binary> [ items <binary > ]
related[SourceEntity]ReferenceIds
Array of strings

Required field (Only one item). Change [SourceEntity] for the choosen source in CamelCase

related[Entity]ReferenceIds
Array of strings

Change [Entity] for the entity name in CamelCase

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "recommendation": "string",
  • "dueDate": "2019-08-24T14:15:22Z",
  • "source": "ASSESSMENT",
  • "priority": "LOW",
  • "contacts": [
    ],
  • "tags": [
    ],
  • "attachments": [
    ],
  • "related[SourceEntity]ReferenceIds": [
    ],
  • "related[Entity]ReferenceIds": [
    ]
}

Response samples

Content type
application/json
"string"

Retireve a Finding

path Parameters
referenceId
required
string

referenceId

Responses

Response samples

Content type
application/json
{
  • "closedAt": "2019-08-24T14:15:22Z",
  • "closedName": "string",
  • "contacts": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "daysOpen": 0,
  • "description": "string",
  • "dueDate": "2019-08-24T14:15:22Z",
  • "dueDateDays": 0,
  • "internalId": "string",
  • "latestRiskMitigation": {
    },
  • "name": "string",
  • "ownerEmail": "string",
  • "ownerName": "string",
  • "ownerReferenceId": 0,
  • "priority": "HIGH",
  • "recommendation": "string",
  • "referenceId": "string",
  • "relatedAssetsCount": 0,
  • "relatedInternalControlsCount": 0,
  • "relatedPoliciesCount": 0,
  • "relatedRiskRegistersCount": 0,
  • "riskScore": 0.1,
  • "riskScorePercentage": 0.1,
  • "sourceType": "ASSESSMENT",
  • "status": "ARCHIVED",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "validation": "string"
}

Exporting Finding in CSV

Export to CSV requires a parameter for your local timezone because the system converts data from UTC to your local export timezone. The local timezone is stored in the timezone={timezone_value} in base64encode format. We recommend using the tool to convert to base64: https://www.base64encode.org/.

query Parameters
timezone
required
string

timezone (in base64)

Responses

Incidents

Exporting Incidents in CSV

Export to CSV requires a parameter for your local timezone because the system converts data from UTC to your local export timezone. The local timezone is stored in the timezone={timezone_value} in base64encode format. We recommend using the tool to convert to base64: https://www.base64encode.org/.

query Parameters
timezone
required
string

timezone (in base64)

Responses

Risk Register

Exporting Risk Register in CSV

Export to CSV requires a parameter for your local timezone because the system converts data from UTC to your local export timezone. The local timezone is stored in the timezone={timezone_value} in base64encode format. We recommend using the tool to convert to base64: https://www.base64encode.org/.

query Parameters
timezone
required
string

timezone (in base64)

Responses

Internal Control

Exporting Internal Control in CSV

Export to CSV requires a parameter for your local timezone because the system converts data from UTC to your local export timezone. The local timezone is stored in the timezone={timezone_value} in base64encode format. We recommend using the tool to convert to base64: https://www.base64encode.org/.

query Parameters
timezone
required
string

timezone (in base64)

Responses