Creating an Assessment with Internal Tags

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) to the assessment 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)

Step 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 to look up tag values in the next step.

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 the next step.

Step 2 — Retrieve Tag Values for a Tag Group

Once you have a tag group ID, retrieve the available values for that group. The 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.

Step 3 — Build the Create Assessment Request Payload

Construct a JSON body for the Create Assessment API call. The table below describes every field in the payload.

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 if you want to review or configure it 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 separated by commas inside the array.

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

3.2  Optional Fields

description

A short description of the assessment. This field is optional.

"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 in the array 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.

Step 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

{
  "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