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 text shown in the input field
Minimum number of characters required
Maximum number of characters allowed (1-5000)
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 )
const requestData = { 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" }; const response = await axios . post ( `https://api.hitl.sh/v1/api/loops/ ${ loopId } /requests` , requestData , { headers: { Authorization: `Bearer ${ apiKey } ` }} );
curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "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" }'
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 Array of options (1-20 options max). Can be simple strings or SelectOption objects. [ "Option 1" , "Option 2" , "Option 3" ]
Automatically converted to rich SelectOption objects for mobile app compatibility. Show Rich Format (SelectOption)
Internal value for the option (max 100 chars)
Display text for the option (max 200 chars)
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" : [ "Approve" , "Approve with Warning" , "Reject" , "Escalate" ] }, "default_response" : "reject" , "timeout_seconds" : 1800 , "platform" : "api" }
const requestData = { 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: [ "Approve" , "Approve with Warning" , "Reject" , "Escalate" ] }, default_response: "reject" , timeout_seconds: 1800 , platform: "api" };
{ "response_data" : "approve_with_warning" }
Multi Select Response Allow reviewers to choose multiple options from a predefined list.
Configuration Array of options (1-20 options max). Can be simple strings or SelectOption objects. [ "Option 1" , "Option 2" , "Option 3" ]
Automatically converted to rich SelectOption objects for mobile app compatibility. Show Rich Format (SelectOption)
Internal value for the option (max 100 chars)
Display text for the option (max 200 chars)
Maximum number of options that can be selected
Minimum number of options that must be selected (auto-added when max_selections is provided)
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" : [ "Incorrect Address" , "Wrong Phone Number" , "Outdated Hours" , "Poor Quality Photos" , "Duplicate Listing" , "No Issues Found" ], "max_selections" : 5 }, "default_response" : [], "timeout_seconds" : 2400 , "platform" : "api" }
{ "response_data" : [ "incorrect_address" , "outdated_hours" ] }
Rating Response Numeric rating scale with configurable range and step values.
Configuration Maximum value of the rating scale
Minimum value of the rating scale (must be < scale_max)
Step increment for the rating scale (e.g., 0.5 for half-star ratings, 1 for full-star ratings)
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" }
const requestData = { 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" };
Number Response Numeric input with validation and formatting options.
Configuration Minimum allowed value (must be < max_value)
Number of decimal places allowed (0-10)
Whether negative numbers are allowed
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" : { "max_value" : 10000 , # min_value defaults to 1 # decimal_places defaults to 2 # allow_negative defaults to false # required defaults to false }, "default_response" : 50 , "timeout_seconds" : 2400 , "platform" : "api" }
const requestData = { 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: { max_value: 10000 , // min_value defaults to 1 // decimal_places defaults to 2 // allow_negative defaults to false // required defaults to false }, default_response: 50 , timeout_seconds: 2400 , platform: "api" };
{ "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
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.
Single Select for Decisions
Use single select for clear decisions with mutually exclusive options. Perfect for approval workflows, categorization, and status assignments.
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.
Rating for Quality Assessment
Use ratings for quantitative assessments where you need to measure quality, satisfaction, confidence levels, or performance on a scale.
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 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 for issue in issues: handle_identified_issue(issue) elif response_type == "rating" : score = response_data if score >= 8 : mark_as_high_quality() elif score <= 3 : flag_for_improvement() elif response_type == "number" : value = response_data update_pricing_model(request_id, value)
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
Simple Integration Learn how to integrate HITL.sh with practical examples
