Creating an Assessment with Internal Tags

Overview Prerequisites Steps Field Reference

Overview

This guide explains how to create a new assessment in TrustArc using the Assessment Manager API, including how to assign internal tags (tag groups and tag values) at creation time.

By the end of this guide you will be able to

✓Construct a valid API request payload to create an assessment

✓Assign assessment owners, approvers, respondents, and participants

✓Retrieve available tag groups and tag values from the API

✓Attach one or more tag values to a new assessment

Prerequisites

Before you begin, ensure you have the following:

✓API access credentials for the TrustArc platform

✓A valid Assessment Template Name already configured in your account

✓AAA email addresses for the assessment owner, approver(s), respondent(s), and any participants

✓Tag Group IDs (UUIDs) if you intend to assign tags — retrieve these using the Tag Group Options API (see Step 1 below)

Steps

1

Retrieve Available Tag Groups

Before creating an assessment with tags, retrieve the list of tag groups available in your account. This provides the tag group names and their IDs, which you will need in Step 2.

API Request

GET api/v1/view/project/taggroup_options

This endpoint returns all tag groups applicable to assessments for the current user's account. No additional parameters are required.

Note: Record the id (UUID) of each tag group you want to use. You will pass this value to the Tag Values API in Step 2.

2

Retrieve Tag Values for a Tag Group

Once you have a tag group ID, retrieve the available values for that group. Results are paginated.

API Request

GET api/v1/view/project/tagvalue_options

Query Parameters

Parameter	Format	Required?	Description
group_id	UUID	Required	The ID of the tag group, obtained from the Tag Group Options API. Example: 0405d90d-5c20-45e2-9051-6053e527e9e7
page	numeric	Optional	The page number to retrieve (zero-based).
size	numeric	Optional	The number of results to return per page.

Example: To retrieve the first page of values for a tag group:

GET api/v1/view/project/tagvalue_options ?group_id=0405d90d-5c20-45e2-9051-6053e527e9e7 &page=0 &size=20

Note: Record the tag value names you want to use (e.g., "North America"). You will reference these by name in the Create Assessment request body.

3

Build the Create Assessment Request Payload

Construct a JSON body for the Create Assessment API call. The sections below describe each field.

3.1 Required Fields

name

The display name of the assessment.

"name": "Hello Repro Winzel Internal Project API"

assessmentTemplateName

The exact name of the Assessment Template to use. The template must already exist in your account.

"assessmentTemplateName": "Fix for Data Systems"

assessmentState

Controls whether the assessment is published for survey responses at creation time. Accepted values:

—SURVEY — Assessment is immediately published and respondents can begin filling it out.

—OPEN — Assessment is created but not yet published. Use this to review or configure before sending to respondents.

"assessmentState": "SURVEY"

assessmentOwner

The TrustArc user who owns the assessment. Provide their AAA email address and name.

"assessmentOwner": { "username": "[e-mail]", "firstName": "Joseph John", "lastName": "Superadmin" }

approvalHierarchy

One or more tiers of approvers. Each tier is assigned a sequential tier number and can contain multiple approvers.

"approvalHierarchy": [ { "tier": 1, "approvers": [ { "username": "[e-mail]", "firstName": "Winzel", "lastName": "TrustE SuperAdmin" } ] }, { "tier": 2, "approvers": [ { "username": "[e-mail]", "firstName": "Joseph John", "lastName": "Superadmin" } ] } ]

respondents

The user(s) who will fill out the assessment. Can include multiple users.

"respondents": [ { "username": "[e-mail]", "firstName": "Joseph", "lastName": "Non-System" } ]

3.2 Optional Fields

description

A short description of the assessment.

"description": "description"

participants

Additional users who can view or collaborate on the assessment but are not respondents or approvers.

"participants": [ { "username": "[e-mail]", "firstName": "Joseph John", "lastName": "Admin User" } ]

tags

Assigns one or more tag groups with their values to the assessment. Each entry represents a tag group. Each tag group must include at least one value.

"tags": [ { "name": "Region", "values": [ { "name": "North America" } ] } ]

Note: Tag group names and tag value names must exactly match what is returned by the Tag Group Options and Tag Value Options APIs. Refer to Steps 1 and 2 to retrieve these values.

4

Submit the Create Assessment Request

Once your payload is assembled, submit the request to the Assessment creation endpoint using a POST call with a JSON body.

Complete Example Payload

Create Assessment with Tags — Full Payload

{
  "name": "Hello Repro Winzel Internal Project API",
  "description": "description",
  "assessmentTemplateName": "Fix for Data Systems",
  "assessmentState": "SURVEY",
  "assessmentOwner": {
    "username": "[e-mail]",
    "firstName": "Joseph John",
    "lastName": "Superadmin"
  },
  "approvalHierarchy": [
    {
      "tier": 1,
      "approvers": [
        {
          "username": "[e-mail]",
          "firstName": "Winzel",
          "lastName": "TrustE SuperAdmin"
        }
      ]
    },
    {
      "tier": 2,
      "approvers": [
        {
          "username": "[e-mail]",
          "firstName": "Joseph John",
          "lastName": "Superadmin"
        }
      ]
    }
  ],
  "respondents": [
    {
      "username": "[e-mail]",
      "firstName": "Joseph",
      "lastName": "Non-System"
    }
  ],
  "participants": [
    {
      "username": "[e-mail]",
      "firstName": "Joseph John",
      "lastName": "Admin User"
    }
  ],
  "tags": [
    {
      "name": "Region",
      "values": [
        {
          "name": "North America"
        }
      ]
    }
  ]
}

Quick Reference — Field Summary

Field	Required?	Description
name	Required	Assessment display name
description	Optional	Short description of the assessment
assessmentTemplateName	Required	Name of an existing Assessment Template
assessmentState	Required	SURVEY (published) or OPEN (unpublished)
assessmentOwner	Required	AAA email, first name, and last name of the owner
approvalHierarchy	Required	Tiered list of approvers; each tier can have multiple approvers
respondents	Required	User(s) who will respond to the assessment
participants	Optional	Additional collaborators/viewers
tags	Optional	Tag groups and their values to classify the assessment

TrustArc  ·  Assessment Manager — Creating an Assessment with Internal Tags  ·  support.trustarc.com