PUT
/
v1
/
reviews
/
{reviewId}
{
  "400": {},
  "404": {},
  "422": {},
  "reviewId": "<string>",
  "status": "<string>",
  "updatedAt": "<string>",
  "completedAt": "<string>",
  "nextSteps": [
    {}
  ]
}

​
Update Review

Update a review’s status, add findings, or submit a completed review.

​
Request

​
reviewId
string
required
The unique identifier of the review to update
​
status
string
Update review status: in_progress, completed, escalated
​
findings
object
Review findings (required when completing)
​
escalationReason
string
Reason for escalation (required if status is “escalated”)
​
additionalReviewRequired
boolean
Request additional review

​
Response

​
reviewId
string
The review identifier
​
status
string
Updated review status
​
updatedAt
string
ISO 8601 timestamp of update
​
completedAt
string
Completion timestamp (if completed)
​
nextSteps
array
Suggested next actions

​
Examples

# Complete a review
curl -X PUT https://api.authentivoice.com/v1/reviews/rev_abc123def456 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "findings": {
      "fraudConfirmed": true,
      "riskAssessment": "high",
      "notes": "Multiple fraud indicators confirmed. Caller attempted to obtain SSN and credit card information using urgency tactics.",
      "flaggedSections": [
        {
          "timestamp": "01:23-01:55",
          "reason": "Request for SSN"
        },
        {
          "timestamp": "03:10-03:45",
          "reason": "Credit card request"
        }
      ],
      "recommendedActions": [
        "Block caller number",
        "Notify affected customer",
        "File fraud report"
      ],
      "confidence": 0.95
    }
  }'

​
Response Example

​
Completed Review

{
  "reviewId": "rev_abc123def456",
  "status": "completed",
  "updatedAt": "2024-01-15T13:30:00Z",
  "completedAt": "2024-01-15T13:30:00Z",
  "nextSteps": [
    "Fraud report filed",
    "Customer notification scheduled",
    "Number added to blocklist"
  ]
}

​
Escalated Review

{
  "reviewId": "rev_abc123def456",
  "status": "escalated",
  "updatedAt": "2024-01-15T13:30:00Z",
  "escalatedTo": "user_senior_001",
  "nextSteps": [
    "Senior review assigned",
    "Notification sent to supervisor"
  ]
}

​
Review States

​
Starting a Review

{
  "status": "in_progress"
}

​
Saving Progress

{
  "findings": {
    "notes": "Initial observations: Caller seems nervous...",
    "flaggedSections": [
      {
        "timestamp": "00:30-00:45",
        "reason": "Suspicious introduction"
      }
    ]
  }
}

​
Completing a Review

{
  "status": "completed",
  "findings": {
    "fraudConfirmed": true,
    "riskAssessment": "high",
    "notes": "Complete review notes...",
    "recommendedActions": ["Action 1", "Action 2"],
    "confidence": 0.85
  }
}

​
Error Responses

​
404
Not Found
Review not found
{
  "error": {
    "code": "REVIEW_NOT_FOUND",
    "message": "The specified review was not found"
  }
}
​
400
Bad Request
Invalid update
{
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "message": "Cannot transition from completed to in_progress"
  }
}
​
422
Unprocessable Entity
Missing required fields
{
  "error": {
    "code": "MISSING_FINDINGS",
    "message": "Findings are required when completing a review"
  }
}