Skip to main content

Retrieve an assessment

Abstract

Learn how to retrieve an assessment by its ID using the API endpoint.

Use the GET /assessments/{assessment_id} endpoint to retrieve information about a single assessment when you already know its unique identifier. This endpoint returns the current state of the assessment, including status, workflow context, and error information.

You can find the unique identifiers for your assessments using the List assessments endpoint.

Request

To retrieve an assessment when you know its unique ID, send a GET request to the /assessments/{assessment_id} endpoint.

The following example retrieves an assessment by its ID:

curl --request "GET" \ 
 "https://{api_region}/v5/assessments/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ 
 --header "apikey: YOUR_API_KEY"

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

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

Response

A successful request returns the full assessment object.

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

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.

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.

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 that the assessment_id is valid.

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

Additional information

An assessment outcome represents the overall result of the assessment's workflow, for example, passed, approved, or failed.