Creating an Assessment via API

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, and 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 your TrustArc support team at [e-mail].

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

4. Go to the Body tab, and then do the following:

• Select raw (3), and then set the request body to JSON (4).
  
  
   
• Enter the payload in JSON format. For more information, see Understanding the API Endpoint.
  
  

Below is a sample request payload with an 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]"   

     }] 

}

Below is a sample request payload without an 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 assessment state, options are only OPEN and SURVEY, use OPEN if u dont want the assessment published to proceed with the survey, otherwise use SURVEY

   "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 assessment approvers hierarchy - can be multiple with a comma separator
    {
         "tier":1, <– REQUIRED the tier of this hierarchy
         "approvers":[ <— REQUIRED assessment approvers in this tier, can be multiple with a comma separator
           {
               "username":"[e-mail]",
               "firstName":"Winzel",
               "lastName":"TrustE SuperAdmin"
            }
          ]
     },
     {
         "tier":2, <– REQUIRED the tier of this hierarchy
         "approvers":[ <— REQUIRED assessment approvers in this tier, can be multiple with a comma separator
            {
               "username":"[e-mail]",
               "firstName":"Joseph John",
               "lastName":"Superadmin"
            }
         ]
      }
   ],

   "respondents":[ <-- REQUIRED assessment respondents - can be multiple with a comma separator
      {
         "username":"[e-mail]",
         "firstName":"Joseph",
         "lastName":"Non-System"
      }
   ],
   "participants": [ <-- OPTIONAL assessment participants - can be multiple with a comma separator
      { 
"username": "[e-mail]",
"firstName": "Joseph John",
"lastName": "Admin User"
      }
   ]
}

5. Do the necessary changes to the payload request.

NOTES:

• Make sure that the assessment name is unique.
• Make sure that the template name matches any of the published templates in the Assessment Templates page. If the template has multiple versions, the latest version will be used.
• If you are using the payload with an Assessment Config, make sure that the Assessment Config name matches any of the assessment configurations in Admin > Assessment Configurations. The sample above assumes that the Assessment Config has assessment owner and user groups for assessment approvers and respondents.
• The assessment state must only be set to OPEN or SURVEY. If the assessmentState field is empty, the new assessment will be in Open state by default and cannot be accessed by the respondents.
• Make sure that the firstName, lastName, and username fields for the participants, assessment owners, approvers, and respondents are not empty. The assessment owners, approvers, and respondents specified in the payload will override the data in the Assessment Config.
• If you encounter any error, see Understanding the Error Messages for more information.

6. Click Send.

Here’s a sample success response:

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