Skip to main content

​
Response Types

HITL.sh supports five different response types that allow reviewers to provide structured feedback. Each response type has its own configuration options and validation rules, giving you flexibility to design the perfect review experience for your use case.

​
Overview

When creating a request, you specify the response_type and response_config to define how reviewers will respond. The response type determines the UI reviewers see in the mobile app and how their responses are structured and validated.

Text

Free-form text responses with character limits and validation

Single Select

Choose one option from a predefined list with labels

Multi Select

Choose multiple options with minimum/maximum selection limits

Rating

Numeric ratings with custom scales, steps, and labeled endpoints

Number

Numeric input with ranges, decimal places, and formatting

​
Text Response

Free-form text input allowing reviewers to provide detailed written feedback.

​
Configuration

​
placeholder
string
Placeholder text shown in the input field
​
min_length
integer
default:"0"
Minimum number of characters required
​
max_length
integer
required
Maximum number of characters allowed (1-5000)
​
required
boolean
default:"false"
Whether the response is required

​
Example Request

import requests

request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown", 
    "priority": "medium",
    "request_text": "Please review this article and provide detailed feedback on accuracy and tone.",
    "response_type": "text",
    "response_config": {
        "placeholder": "Provide your detailed feedback here...",
        "min_length": 50,
        "max_length": 1000,
        "required": True
    },
    "default_response": "No feedback provided within timeout period",
    "timeout_seconds": 3600,
    "platform": "api"
}

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{loop_id}/requests",
    headers={"Authorization": f"Bearer {api_key}"},
    json=request_data
)

​
Response Format

When a reviewer submits a text response, you’ll receive: 
{
  "response_data": "This article is well-written and factually accurate. The tone is professional and engaging. I recommend approval with minor grammar corrections on paragraph 3."
}

​
Single Select Response

Allow reviewers to choose one option from a predefined list.

​
Configuration

​
options
array
required
Array of SelectOption objects (1-20 options max)
​
required
boolean
required
Whether a selection is required

​
Example Request

request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "high",
    "request_text": "Please review this user comment for community guideline compliance:",
    "response_type": "single_select",
    "response_config": {
        "options": [
            {
                "value": "approve",
                "label": "Approve"
            },
            {
                "value": "approve_with_warning", 
                "label": "Approve with Warning"
            },
            {
                "value": "reject",
                "label": "Reject"
            },
            {
                "value": "escalate",
                "label": "Escalate"
            }
        ],
        "required": true
    },
    "default_response": "reject",
    "timeout_seconds": 1800,
    "platform": "api"
}

​
Response Format

{
  "response_data": {
    "selected_value": "approve_with_warning",
    "selected_label": "⚠️ Approve with Warning"
  }
}

​
Multi Select Response

Allow reviewers to choose multiple options from a predefined list.

​
Configuration

​
options
array
required
Array of SelectOption objects with value and label properties
​
min_selections
integer
required
Minimum number of options that must be selected
​
max_selections
integer
required
Maximum number of options that can be selected
​
required
boolean
required
Whether at least one selection is required

​
Example Request

request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "medium",
    "request_text": "What issues do you see in this business listing? Select all that apply:",
    "response_type": "multi_select",
    "response_config": {
        "options": [
            {
                "value": "incorrect_address",
                "label": "Incorrect Address"
            },
            {
                "value": "wrong_phone",
                "label": "Wrong Phone Number"
            },
            {
                "value": "outdated_hours",
                "label": "Outdated Hours"
            },
            {
                "value": "poor_photos",
                "label": "Poor Quality Photos"
            },
            {
                "value": "duplicate_listing",
                "label": "Duplicate Listing"
            },
            {
                "value": "no_issues",
                "label": "No Issues Found"
            }
        ],
        "min_selections": 1,
        "max_selections": 5,
        "required": true
    },
    "default_response": "no_issues",
    "timeout_seconds": 2400,
    "platform": "api"
}

​
Response Format

{
  "response_data": {
    "selected_values": ["incorrect_address", "outdated_hours"],
    "selected_labels": ["📍 Incorrect Address", "🕒 Outdated Hours"]
  }
}

​
Rating Response

Numeric rating scale with configurable range and step values.

​
Configuration

​
scale_min
number
required
Minimum value of the rating scale
​
scale_max
number
required
Maximum value of the rating scale (must be > scale_min)
​
scale_step
number
required
Step increment for the rating (e.g., 0.5 for half-point ratings)
​
required
boolean
required
Whether a rating is required

​
Example Request

request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "medium", 
    "request_text": "Please rate the quality of this AI-generated content on a scale of 1-10:",
    "response_type": "rating",
    "response_config": {
        "scale_min": 1,
        "scale_max": 10,
        "scale_step": 0.5,
        "required": true
    },
    "default_response": 5,
    "timeout_seconds": 1800,
    "platform": "api"
}

​
Response Format

{
  "response_data": 7.5
}

​
Number Response

Numeric input with validation and formatting options.

​
Configuration

​
min_value
number
required
Minimum allowed value
​
max_value
number
required
Maximum allowed value (must be > min_value)
​
decimal_places
integer
default:"0"
Number of decimal places allowed (0-10)
​
allow_negative
boolean
default:"false"
Whether negative numbers are allowed
​
required
boolean
required
Whether a value is required

​
Example Request

request_data = {
    "processing_type": "time-sensitive", 
    "type": "markdown",
    "priority": "medium",
    "request_text": "What's a fair market price for this product based on your expertise?",
    "response_type": "number",
    "response_config": {
        "min_value": 0,
        "max_value": 10000,
        "decimal_places": 2,
        "allow_negative": false,
        "required": true
    },
    "default_response": 0,
    "timeout_seconds": 2400,
    "platform": "api"
}

​
Response Format

{
  "response_data": 299.99
}

​
Validation Rules

HITL.sh validates all responses against the configured rules:
  • Response must be a string
  • Length must be within min_length and max_length bounds
  • Required responses cannot be empty strings
  • Response must be a valid option value from the options array
  • Required responses must include a selection
  • Only one option can be selected
  • All selected values must be valid options from the options array
  • Number of selections must be within min_selections and max_selections bounds
  • No duplicate selections allowed
  • Response must be a number within scale_min and scale_max bounds
  • Value must align with scale_step increments (e.g., only .0 and .5 for step=0.5)
  • Required ratings cannot be null
  • Response must be a number within min_value and max_value bounds
  • Decimal places must not exceed configured decimal_places
  • Negative numbers only allowed if allow_negative is true

​
Best Practices

​
Choosing Response Types

1

Text for Complex Feedback

Use text responses when you need detailed explanations, qualitative feedback, or open-ended input that can’t be captured in predefined options.
2

Single Select for Decisions

Use single select for clear decisions with mutually exclusive options. Perfect for approval workflows, categorization, and status assignments.
3

Multi Select for Categorization

Use multi select when multiple aspects need to be evaluated simultaneously, such as content issues, feature requests, or compliance checklist items.
4

Rating for Quality Assessment

Use ratings for quantitative assessments where you need to measure quality, satisfaction, confidence levels, or performance on a scale.
5

Number for Quantitative Input

Use number responses for pricing, quantities, measurements, or any numeric data that needs validation and formatting.

​
Configuration Tips

Keep Options Clear

Use descriptive labels and include helpful descriptions for select options. Consider adding colors for visual clarity.

Set Reasonable Limits

Configure appropriate min/max values, character limits, and selection bounds to prevent invalid or unusable responses.

Provide Good Defaults

Always specify meaningful default responses that represent the safest or most common expected outcome.

Consider Mobile UX

Remember that reviewers will interact with these response types on mobile devices. Keep options concise and touch-friendly.

​
Response Handling

When processing responses in your application: 
def handle_response(request_id, response_data, response_type):
    """Handle different response types appropriately"""
    
    if response_type == "text":
        text = response_data
        # Process free-form text feedback
        analyze_sentiment(text)
        extract_keywords(text)
        
    elif response_type == "single_select":
        selected = response_data["selected_value"]
        if selected == "approve":
            approve_content()
        elif selected == "reject":
            reject_content()
        elif selected == "escalate":
            escalate_to_senior_reviewer()
            
    elif response_type == "multi_select":
        issues = response_data["selected_values"]
        for issue in issues:
            handle_identified_issue(issue)
            
    elif response_type == "rating":
        score = response_data["rating"]
        if score >= 8:
            mark_as_high_quality()
        elif score <= 3:
            flag_for_improvement()
            
    elif response_type == "number":
        value = response_data["number"]
        update_pricing_model(request_id, value)
        
    elif response_type == "boolean":
        decision = response_data["boolean"]
        if decision:
            trigger_investigation()
        else:
            approve_transaction()

​
Next Steps

Create Your First Request

Start using these response types in your requests

Mobile App Guide

See how reviewers interact with these response types

Webhooks

Set up webhooks to receive responses in real-time

Best Practices

Learn optimization strategies for better response quality
⌘I