Submit a ticket My Tickets
Login  Sign up

How to Change the Status of an Evaluation in Manual Review via API

Whenever an evaluation is assigned the outcome of "Manual Review", based on the outcome logic of the workflow it went through, it goes to the Review Queue. Evaluations are commonly manually reviewed in the dashboard. However, it is also possible to change the status of an evaluation which is sitting in the Review Queue via API. This is done by making a POST request to the /reviews endpoint. Hint: you'll need your Alloy entity_token for the request (not your evaluation_token)!

Here's an example of a curl request (remember to switch your url from '' to '' if you're in production):

curl -X "POST" "[your-entity-token-here]/reviews" \

     -H 'Content-Type: application/json; charset=utf-8' \

     -u '[your-app-token]:[your-app-secret]' \

     -d $'{

  "agent": {

    "email": ""


  "outcome": "Denied",

  "reasons": [




A few things to note:
-The agent whose email you include in the body of the request must be an agent on the account (you can view the agents on the account on the main page of your account under "Agents").
-The chosen outcome for the evaluation & the reason given for that outcome in the body of the API request must match exactly the way outcomes and reasons are set up in Settings --> Review Reasons. So, if my accounts Review Reasons are configured this way:

an outcome of "Denied" will work because it is linked here to a Review Reason of "Other". However, if I tried to make the request with an outcome of "Approved" and a Review Reason of "Bad Quiz", it will throw an error because these are not linked in the Review Reasons Settings in my account.
-Beware of capitalization for Review Reason/Outcome. It needs to match the capitalization in your Review Reasons Settings exactly.
-If you are getting a 404 error (reason code 4042), that is probably because there is one of the above issues in your request body.

Here is an example Postman request:

And a successful response, which generates a review_token:

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.