Create an assessment

Developer reference

Abstract

Learn how to create an assessment for an entity using the API endpoint. This guide shows how to submit the request and interpret the response.

Use the POST /assessments endpoint to create a new assessment for an entity. Creating an assessment automatically creates and starts a workflow instance based on the selected assessment template. Learn more about assessments.

Request

To create a new assessment, make a POST request to the /assessments endpoint.

To authenticate your request, include the apikey: API_KEY header. See Manage API keys for more information.

Parameters

There are two required body parameters for this request:

entity_id: The ID of the entity to assess. You can find the unique identifiers for your entities using the GET /entities endpoint.
template_id: The ID of the assessment template to use for the assessment being created. Use the GET / assessments/templates endpoint to find template IDs.

Sample request

The following example creates an instance of an assessment based on the assessment template referenced by template_id. The assessment is created on the entity referenced by entity_id.

curl --request "POST" \ 
 "https://{api_region}/v5/assessments" \ 
 --header "apikey: API_KEY" \ 
 --header "Content-Type: application/json" \ 
 --data "{  
  "entity_id": "8161163a-f227-466f-bc01-090a01e80165",  
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc" 
 }"

Replace {api_region} with the domain from your region's base URL.

Response

A successful request creates a new assessment and starts a new workflow instance. The response returns the assessment record along with workflow-related identifiers.

The workflow_state field returns the assessment's workflow state: Active, Cancelled, or Error. If the workflow state is Error, inspect the error_message, error_details, error_step, and error_type fields in the response to help diagnose the issue.

The outcome_id field gives the current outcome of the assessment. Use the Get an outcome by ID endpoint to retrieve the name of the outcome associated with this ID.

{
  "created_at": "2019-08-24T14:15:22Z",
  "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  "error_details": null,
  "error_message": null,
  "error_step": null,
  "error_type": null,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "institution_id": "c75f2c73-5ae4-4f1c-99c0-fc726cd41798",
  "outcome_id": "0323e489-6bf9-4b68-9c8d-5674f46921e4",
  "status_id": "4e949624-bc0f-439e-a9f2-25a23938812c",
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  "workflow_instance_id": "46ff49d0-5f69-46b0-9de7-5703639a02ce",
  "workflow_state": "Active"
}

Troubleshooting

If you receive a 401 Unauthorized response, make sure the apikey header is included and contains a valid key. Check that you are using the correct base URL for your region, and if IP allow listing is enabled, verify your request originates from an allowed IP address.
If you receive a 404 Not Found response, check the entity_id and template_id you supplied are correct.
If you receive a 409 Conflict response, check that there isn't an existing assessment for the requested template_id type.
If the assessment is created but the workflow enters the Error state, inspect the error_message, error_details, error_step, and error_type fields in the response to help diagnose the issue.

For a full list of the possible error codes, view the API reference.