POST
/
v1
/
requests
/
{id}
/
feedback
curl -X POST https://api.hitl.sh/v1/requests/65f1234567890abcdef12348/feedback \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }'
{
  "error": false,
  "msg": "Feedback added successfully",
  "data": {
    "request_id": "65f1234567890abcdef12348",
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    },
    "feedback_id": "65f1234567890abcdef12355",
    "submitted_at": "2024-03-15T12:30:00Z",
    "reviewer_notified": true
  }
}
Add feedback to completed requests to help improve reviewer performance and overall system quality. Feedback can include ratings, comments, and specific quality metrics that help reviewers understand what worked well and what could be improved.

Authentication

Authorization
string
required
Your API key for authentication

Path Parameters

id
string
required
The unique identifier of the completed request

Body Parameters

feedback
object
required
Feedback object containing ratings, comments, and quality metrics

Feedback Object Structure

The feedback object can contain any combination of the following fields:
feedback.rating
number
Overall quality rating (1-5 scale, where 5 is excellent)
feedback.comment
string
Free-form text feedback and comments (max 1000 characters)
feedback.accuracy
number
Response accuracy rating (1-5 scale)
feedback.timeliness
number
Response timeliness rating (1-5 scale)
feedback.helpfulness
number
Response helpfulness rating (1-5 scale)
feedback.would_recommend
boolean
Whether you would recommend this reviewer for similar requests
feedback.tags
array
Array of feedback tags (e.g., [“thorough”, “quick”, “insightful”])
feedback.follow_up_needed
boolean
Whether this request requires follow-up action
feedback.category
string
Feedback category: “positive”, “constructive”, “issue”

Response

error
boolean
Whether an error occurred
msg
string
Success message
data
object
curl -X POST https://api.hitl.sh/v1/requests/65f1234567890abcdef12348/feedback \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    }
  }'
{
  "error": false,
  "msg": "Feedback added successfully",
  "data": {
    "request_id": "65f1234567890abcdef12348",
    "feedback": {
      "rating": 5,
      "comment": "Excellent review! Very thorough analysis and quick turnaround time.",
      "accuracy": 5,
      "timeliness": 5,
      "helpfulness": 4,
      "would_recommend": true,
      "tags": ["thorough", "quick", "professional"],
      "category": "positive"
    },
    "feedback_id": "65f1234567890abcdef12355",
    "submitted_at": "2024-03-15T12:30:00Z",
    "reviewer_notified": true
  }
}

Feedback Categories

Positive

Category: positive
  • High ratings (4-5)
  • Appreciation for good work
  • Reinforces desired behaviors
  • Builds reviewer confidence

Constructive

Category: constructive
  • Moderate ratings (2-4)
  • Specific improvement suggestions
  • Educational feedback
  • Growth-oriented

Issue

Category: issue
  • Low ratings (1-2)
  • Identifies problems
  • May require follow-up
  • Used sparingly for serious issues

Feedback Best Practices

Effective Feedback Structure

Feedback Analytics

Track Feedback Patterns

Monitor your feedback trends to improve request quality:
def analyze_feedback_patterns():
    """Analyze feedback patterns across all requests"""
    
    # Get all completed requests
    response = requests.get(
        "https://api.hitl.sh/v1/requests?status=completed&limit=100",
        headers={"Authorization": "Bearer your_api_key_here"}
    )
    
    completed_requests = response.json()["data"]["requests"]
    
    # Analyze feedback patterns (this would require additional API endpoints)
    feedback_stats = {
        "total_requests": len(completed_requests),
        "feedback_given": 0,
        "avg_rating": 0,
        "common_tags": {},
        "category_breakdown": {"positive": 0, "constructive": 0, "issue": 0},
        "reviewer_performance": {}
    }
    
    # Note: In a real implementation, you'd need endpoints to retrieve 
    # feedback data to perform this analysis
    
    return feedback_stats

def generate_feedback_suggestions(request_data, response_quality):
    """Generate feedback suggestions based on request and response analysis"""
    
    suggestions = {
        "recommended_rating": 3,
        "suggested_tags": [],
        "feedback_template": "",
        "category": "constructive"
    }
    
    # Analyze response time
    response_time = request_data.get("response_time_seconds", 0)
    if response_time < 300:  # Under 5 minutes
        suggestions["suggested_tags"].append("quick")
        suggestions["recommended_rating"] += 1
    elif response_time > 3600:  # Over 1 hour
        suggestions["feedback_template"] += "Consider faster response times for future requests. "
    
    # Analyze priority handling
    if request_data["priority"] == "critical" and response_time < 600:
        suggestions["suggested_tags"].append("urgent-handling")
        suggestions["recommended_rating"] += 1
    
    # Generate template
    if suggestions["recommended_rating"] >= 4:
        suggestions["category"] = "positive"
        suggestions["feedback_template"] = "Great work! " + suggestions["feedback_template"]
    elif suggestions["recommended_rating"] <= 2:
        suggestions["category"] = "issue"
        suggestions["feedback_template"] = "There are some areas for improvement: " + suggestions["feedback_template"]
    
    return suggestions

Bulk Feedback Operations

Provide feedback on multiple completed requests:
async function bulkFeedback(requestFeedbackPairs, options = {}) {
    const { delay = 200, validateFirst = true } = options;
    const results = [];
    
    for (const { requestId, feedback } of requestFeedbackPairs) {
        try {
            if (validateFirst) {
                // Get request details to ensure it's completed
                const requestResponse = await axios.get(
                    `https://api.hitl.sh/v1/requests/${requestId}`,
                    { headers: { 'Authorization': 'Bearer your_api_key_here' } }
                );
                
                const requestData = requestResponse.data.data.request;
                
                if (requestData.status !== 'completed') {
                    results.push({
                        requestId,
                        success: false,
                        error: `Request status is '${requestData.status}', not 'completed'`
                    });
                    continue;
                }
            }
            
            // Submit feedback
            const feedbackResponse = await axios.post(
                `https://api.hitl.sh/v1/requests/${requestId}/feedback`,
                { feedback },
                { headers: { 'Authorization': 'Bearer your_api_key_here', 'Content-Type': 'application/json' } }
            );
            
            results.push({
                requestId,
                success: true,
                feedbackId: feedbackResponse.data.data.feedback_id
            });
            
            // Rate limiting delay
            if (delay > 0) {
                await new Promise(resolve => setTimeout(resolve, delay));
            }
            
        } catch (error) {
            results.push({
                requestId,
                success: false,
                error: error.response?.data?.msg || error.message
            });
        }
    }
    
    return {
        total: requestFeedbackPairs.length,
        successful: results.filter(r => r.success).length,
        failed: results.filter(r => !r.success).length,
        results
    };
}

// Usage
const feedbackBatch = [
    {
        requestId: '65f1234567890abcdef12348',
        feedback: { rating: 5, comment: 'Excellent work!', category: 'positive' }
    },
    {
        requestId: '65f1234567890abcdef12349', 
        feedback: { rating: 4, comment: 'Good job, could be more detailed', category: 'constructive' }
    }
];

const results = await bulkFeedback(feedbackBatch);
console.log(`Submitted feedback for ${results.successful}/${results.total} requests`);

Feedback Templates

Pre-built Feedback Templates

Create reusable feedback templates for common scenarios:

Access Control

Feedback Permissions

Error Handling

Common Error Scenarios

Impact of Feedback

On Reviewers

On System Quality

Next Steps

View Request History

Review your request history and identify requests that could benefit from feedback.

Loop Analytics

See how feedback is improving your loop performance over time.

Reviewer Guidelines

Learn how reviewers see and respond to feedback on the mobile app.