Creating an Assessment via API

Overview Steps Sample Payloads

Overview

This article describes how to create an assessment using the Assessment Manager Create Assessment API via an API platform such as Postman or Swagger.

📋 Related: If you want to create an assessment with internal tags, see Creating an Assessment with Internal Tags.

Steps

1

Open an API platform such as Postman or Swagger.

2

From the URL field, enter the environment URL and the API endpoint.

For example: https://assess.truste.com/api/v1/project-internal/create

Where:

—https://assess.truste.com is the Prod URL.

—/api/v1/project-internal/create is the API endpoint.

Note: Make sure that the method is set to POST.

3

Go to the Headers tab, then do the following:

—Set the key to Authorization (1).

—Under the Value column, enter the access token (2). For more information, see Accessing the Token or contact TrustArc support at [e-mail].

Note: All Assessment Manager user roles, except respondents, can use the token.

4

Go to the Body tab, then do the following:

—Select raw (3), then set the request body format to JSON (4).

—Enter the payload in JSON format. For more information, see Sample Payloads below or Understanding the API Endpoint.

5

Make the necessary changes to the payload request.

Notes

✓Make sure that the assessment name is unique.

✓Make sure that the template name matches a published template on the Assessment Templates page. If the template has multiple versions, the latest version is used.

✓If using the payload with an Assessment Config, make sure the Assessment Config name matches a configuration under Admin > Assessment Configurations. The sample assumes the Assessment Config includes assessment owner and user groups for approvers and respondents.

✓The assessment state must be set to OPEN or SURVEY only. If the assessmentState field is empty, the new assessment defaults to Open state and cannot be accessed by respondents.

✓Make sure the firstName, lastName, and username fields for participants, assessment owners, approvers, and respondents are not empty. Owners, approvers, and respondents specified in the payload will override the data in the Assessment Config.

✓If you encounter an error, see Understanding Error Messages for more information.

6

Click Send.

Here's a sample success response:

Sample Payloads

Sample request payload with an Assessment Config:

With Assessment Config

{
  "name": "TrustArc External API to Create Assessment with Assessment Config",
  "assessmentTemplateName": "External API Test Template",
  "assessmentConfigName": "External API Test Assessment Config",
  "assessmentState": "SURVEY",
  "participants": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "username": "[e-mail]"
    }
  ]
}

Sample request payload without an Assessment Config:

Without Assessment Config

{
  "name": "Hello Repro Winzel Internal Project API",  // REQUIRED assessment name
  "description": "description",                       // OPTIONAL assessment description
  "assessmentTemplateName": "Fix for Data Systems",   // REQUIRED assessment template name
  "assessmentState": "SURVEY",                        // REQUIRED — use OPEN or SURVEY only
  "assessmentOwner": {                                // REQUIRED assessment owner
    "username": "[e-mail]",       // assessment owner AAA email
    "firstName": "Joseph John",                       // assessment owner AAA first name
    "lastName": "Superadmin"                          // assessment owner AAA last name
  },
  "approvalHierarchy": [                              // REQUIRED — can be multiple tiers
    {
      "tier": 1,                                      // REQUIRED tier number
      "approvers": [                                  // REQUIRED — can be multiple approvers
        {
          "username": "[e-mail]",
          "firstName": "Winzel",
          "lastName": "TrustE SuperAdmin"
        }
      ]
    },
    {
      "tier": 2,
      "approvers": [
        {
          "username": "[e-mail]",
          "firstName": "Joseph John",
          "lastName": "Superadmin"
        }
      ]
    }
  ],
  "respondents": [                                    // REQUIRED — can be multiple
    {
      "username": "[e-mail]",
      "firstName": "Joseph",
      "lastName": "Non-System"
    }
  ],
  "participants": [                                   // OPTIONAL — can be multiple
    {
      "username": "[e-mail]",
      "firstName": "Joseph John",
      "lastName": "Admin User"
    }
  ]
}

TrustArc  ·  Assessment Manager — Creating an Assessment via API  ·  support.trustarc.com